Skip to main content
This page provides a technical guide for onboarding engineers to the Palyra codebase. It covers environment validation, dependency bootstrapping, and the initial setup of the palyrad daemon using the integrated CLI wizard.

​
1. Prerequisites and Environment Validation

Before running bootstrap scripts, engineers should verify their local environment meets the system requirements. Palyra provides a diagnostic tool, palyra doctor, to check for required dependencies and configuration integrity. The doctor command performs strict environment checks, including verifying the presence of necessary build tools and runtime isolation primitives.
CommandPurpose
palyra doctor --strictRuns mandatory environment checks; required for development justfile#8-11.
just doctorAlias for the strict doctor check via the project justfile justfile#7-11.
Sources: justfile#7-11, crates/palyra-cli/src/args/tests.rs#86-101

​
2. Bootstrapping the Workspace

Palyra uses a multi-language monorepo structure. Bootstrapping involves fetching Rust dependencies, setting up the Node.js workspace, and preparing desktop UI components.

​
2.1 Dependency Initialization

The primary entry point for new developers is the dev recipe in the justfile (or Makefile). This orchestrates the following flow:
  1. Environment Validation: Executes just doctor.
  2. Desktop UI Preparation: Runs scripts/test/ensure-desktop-ui.sh to ensure the Tauri frontend assets are available justfile#44-45.
  3. Rust Compilation: Performs a cargo build --workspace to compile all crates, including the daemon and CLI justfile#19-19.
  4. JS Workspace: Instructs the user to run vp install to materialize the npm workspaces via the Vite+ (vp) tooling justfile#20-20.

​
2.2 Scripted Bootstrap

For automated environments, standalone scripts are provided:
  • Unix: scripts/dev/bootstrap.sh
  • Windows: scripts/dev/bootstrap.ps1
Sources: justfile#16-22, Makefile#16-18, scripts/dev/bootstrap.sh#1-1

​
3. The Setup Wizard and Onboarding

Once the binaries are built, the palyra CLI provides a guided setup experience to initialize the local daemon configuration and state.

​
3.1 Setup Modes

The palyra setup command (aliased as init) supports different deployment targets:

​
3.2 Wizard Implementation

The setup process is powered by the WizardSession engine, which abstracts terminal interactions into discrete steps. Code Entity Space: Wizard Logic
EntityRole
WizardStepDefines a UI element (Note, Select, Text, Confirm) with validation logic crates/palyra-cli/src/commands/wizard.rs#29-39.
WizardSessionOrchestrates the flow of steps and handles user input via a WizardBackend crates/palyra-cli/src/commands/wizard.rs#155-165.
InitModeArgEnum defining Local vs Remote bootstrap paths crates/palyra-cli/src/args/init.rs#77-77.
Data Flow: CLI Setup Sources: crates/palyra-cli/src/commands/wizard.rs#11-39, crates/palyra-cli/src/args/mod.rs#111-111, crates/palyra-cli/src/args/tests.rs#33-83

​
4. Running the Daemon (palyrad)

After setup, the core orchestrator (palyrad) can be started. In the development environment, this is typically done via the CLI.

​
4.1 Gateway Execution

The daemon provides several transport layers, including gRPC and QUIC, which are initialized based on the configuration generated during the setup phase.

​
4.2 Health Verification

To verify the bootstrap was successful and the daemon is responsive, use the health command. This probe checks both the HTTP and gRPC gateway surfaces crates/palyra-cli/tests/help_snapshots/root-help-unix.txt#9-9. Sources: crates/palyra-cli/src/lib.rs#150-165, crates/palyra-cli/src/args/mod.rs#170-183, crates/palyra-cli/tests/help_snapshots/root-help-unix.txt#9-11

​
5. Troubleshooting the Bootstrap

If the development environment fails to initialize, engineers should use the following diagnostic sequence:
  1. Doctor Repair: palyra doctor --repair can automatically fix common issues like missing directories or stale runtime artifacts crates/palyra-cli/src/args/tests.rs#122-149.
  2. Log Tailing: palyra logs --follow allows viewing real-time diagnostics from the gateway journal crates/palyra-cli/src/args/tests.rs#171-192.
  3. Reset: As a last resort, palyra reset --scope state will clear local databases and cached artifacts to allow a clean setup crates/palyra-cli/src/args/mod.rs#197-200.
Sources: crates/palyra-cli/src/args/tests.rs#122-192, crates/palyra-cli/src/args/mod.rs#197-200