palyrad), and utilizing the CLI-driven onboarding workflows. It covers the transition from a fresh repository clone to a fully functional local control plane with a configured profile.
1. Environment Bootstrapping
Palyra utilizes ajustfile (and a fallback Makefile) to orchestrate the development lifecycle. The primary entry point for a new developer is the doctor command, which performs environment validation before attempting a build.
The Developer “Doctor” Check
Thedoctor command executes palyra doctor --strict to verify system dependencies, toolchains, and filesystem permissions justfile#7-11. It ensures that the environment is capable of running the daemon and its associated sandboxes.
| Command | Purpose | Implementation |
|---|---|---|
just doctor | Validates environment | cargo run -p palyra-cli -- doctor --strict justfile#10 |
just dev | Full bootstrap | Runs doctor, builds workspace, and checks UI justfile#16-21 |
just build | Compile all crates | cargo build --workspace --locked justfile#118-120 |
just protocol | Schema generation | Validates and generates Protobuf stubs justfile#103-113 |
JS Workspace Setup
The web dashboard and desktop UI require a Node.js environment. The project usesvp (a workspace manager) to materialize the root JS workspace justfile#30-31. Developers must run just web-bootstrap to install dependencies across all frontend applications Makefile#80-81.
Sources: justfile#1-22, Makefile#1-19, justfile#103-113
2. Profile Setup and Onboarding Wizard
Palyra is profile-centric. Every daemon instance and CLI interaction operates within a profile context defined inprofiles.toml. The setup process creates the necessary configuration files and state directories (typically in .palyra/).
Onboarding Flows
Thepalyra setup command is the primary entry point for new installations crates/palyra-cli/tests/help_snapshots/setup-help.txt#1-3. It supports two main modes:
- Manual (
--mode local): Directly initializes configuration files usingrun_initcrates/palyra-cli/src/commands/setup.rs#13. - Guided (
--wizard): Launches an interactive session to configure model providers, ports, and security settings crates/palyra-cli/src/commands/setup.rs#15-50.
Wizard Implementation
The wizard is built on a genericWizardSession that manages a sequence of WizardStep entities crates/palyra-cli/src/commands/wizard.rs#29-39.
Onboarding Logic Flow
Sources: crates/palyra-cli/src/commands/setup.rs#3-55, crates/palyra-cli/src/commands/wizard.rs#11-39, crates/palyra-cli/tests/help_snapshots/setup-help.txt#1-1153. Running the Daemon and Console
Once configured, thepalyrad daemon acts as the central control plane.
Bootstrapping the Daemon
The daemon can be started via the CLI or as a standalone binary. It initializes theGateway, starts the Axum-based HTTP server for the Console API, and opens the gRPC management interface.
- Start Daemon:
palyra gateway start - Verify Health:
palyra gateway statuscrates/palyra-cli/tests/help_snapshots/setup-help.txt#114 - Access Web Dashboard: By default, the console is served at
http://localhost:4000(or the port configured duringsetup).
Developer Pre-push Checks
To maintain repository health, developers should run the pre-push suite which mirrors CI gates. This is orchestrated byscripts/run-pre-push-checks.sh scripts/run-pre-push-checks.sh#1-5.
| Profile | Checks Performed |
|---|---|
fast (Default) | JS checks, rustfmt, artifact hygiene, deterministic smoke tests scripts/run-pre-push-checks.sh#49-72 |
full | All fast checks + clippy, full workspace test, protocol validation scripts/run-pre-push-checks.sh#74-108 |
4. Technical Data Flow: Setup to Execution
The following diagram bridges the natural language “Setup” concepts to the internal code structures that handle profile initialization.Configuration & Profile Bootstrapping
Sources: crates/palyra-cli/src/commands/setup.rs#15-54, crates/palyra-cli/src/commands/configure.rs#37-77, crates/palyra-cli/src/commands/wizard.rs#155-165Key Functions and Classes
run_setup: Entry point for installation. Dispatches to eitherrun_initorrun_setup_wizardcrates/palyra-cli/src/commands/setup.rs#3-10.WizardStep: Defines an interactive prompt, including itsStepKind(Note, Select, Text, etc.) crates/palyra-cli/src/commands/wizard.rs#29-39.update_active_profile_paths: Persists the location of the newly created configuration into the global CLI state crates/palyra-cli/src/commands/setup.rs#53.run_configure: Allows modifying an existing profile’s sections (Auth, Network, TLS) without a full re-init crates/palyra-cli/src/commands/configure.rs#6-35.