Skip to main content
This page provides the technical details for bootstrapping a local Palyra development environment, performing system diagnostics via the doctor utility, and utilizing the onboarding wizard to generate a valid palyra.toml configuration.

​
1. Local Development Bootstrapping

Palyra uses a multi-layered bootstrap process involving Rust, Node.js, and platform-specific shell scripts. The primary entry points for developers are the justfile (for just users) and the Makefile.

​
1.1 Toolchain Prerequisites

The system expects a standard Rust toolchain and a Node.js environment. Key development targets are managed through just or make.
  • Rust: Managed via Cargo.toml workspace.
  • Frontend: Managed via vp (Vite+) tooling in the apps/web and apps/desktop directories.
  • Protocols: Protobuf generation requires protoc.

​
1.2 Bootstrap Commands

The dev target is the canonical entry point for setting up a fresh repository clone.
CommandActionSource
just devRuns doctor, ensures UI assets, and builds the workspace.justfile#16-21
make devEquivalent to just dev using Makefile.Makefile#16-19
just web-bootstrapRuns vp install to materialize the root JS workspace.justfile#30-31
just protocolValidates and generates gRPC stubs for Rust/Kotlin/Swift.justfile#103-107

​
1.3 Developer Data Flow

The following diagram illustrates the bootstrap sequence from a clean clone to a running environment: Developer Onboarding Flow Sources: justfile#16-21, Makefile#16-19, justfile#44-46

​
2. The Doctor Diagnostic Pipeline

The doctor command is a comprehensive diagnostic utility located in crates/palyra-cli/src/commands/doctor.rs. It performs environment checks, runtime validation, and automated repairs.

​
2.1 Diagnostic Scopes

When running palyra doctor --strict, the system evaluates several critical paths:

​
2.2 Automated Recovery & Rollbacks

The DoctorCommandRequest struct supports a repair mode which can automatically fix common configuration drifts or missing directories crates/palyra-cli/src/commands/doctor/recovery.rs#48-57. Sources: crates/palyra-cli/src/commands/doctor.rs#8-10, crates/palyra-cli/src/commands/doctor/recovery.rs#48-57, crates/palyra-cli/src/commands/doctor/recovery.rs#178-236

​
3. Configuration & Onboarding Wizard

Palyra utilizes an interactive wizard to generate the palyra.toml configuration file. This is handled by the operator_wizard.rs module.

​
3.1 Wizard Flow Types

The WizardFlowKind enum defines three distinct onboarding experiences:
  1. Quickstart: Minimal prompts, uses defaults for models (e.g., gpt-4o-mini) and local loopback binding crates/palyra-cli/src/commands/operator_wizard.rs#18-66.
  2. Manual: Granular control over ports, TLS certificates, and workspace roots crates/palyra-cli/src/commands/operator_wizard.rs#67-75.
  3. Remote: Configures a CLI client to connect to an existing remote palyrad instance crates/palyra-cli/src/commands/operator_wizard.rs#68-76.

​
3.2 Configuration Entities

The wizard populates the OnboardingMutationPlan, which is eventually serialized to palyra.toml. Code-to-System Mapping: Configuration Wizard Sources: crates/palyra-cli/src/args/onboarding.rs#5-31, crates/palyra-cli/src/commands/operator_wizard.rs#151-195, crates/palyra-cli/src/commands/operator_wizard.rs#131-135

​
3.3 Non-Interactive Setup

For CI/CD or automated scripts, the wizard supports a --non-interactive flag combined with environment variables (e.g., OPENAI_API_KEY) to bypass prompts crates/palyra-cli/tests/wizard_cli.rs#88-101. Sources: crates/palyra-cli/src/commands/operator_wizard.rs#240-248, crates/palyra-cli/tests/wizard_cli.rs#39-71

​
4. Environment Variables & Paths

Palyra relies on several environment variables to locate its state and configuration. These are primarily handled during the palyra setup phase.
VariableDescriptionDefault / Source
PALYRA_STATE_ROOTRoot directory for all persistent data (DBs, logs).crates/palyra-cli/tests/wizard_cli.rs#14
PALYRA_VAULT_DIRDirectory containing the encrypted secret vault.crates/palyra-cli/tests/wizard_cli.rs#15
PALYRA_CONFIGExplicit path to the palyra.toml file.crates/palyra-cli/tests/cli_parity_matrix.toml#8
PALYRA_LOG_LEVELLogging verbosity (error, warn, info, debug, trace).crates/palyra-cli/tests/help_snapshots/setup-help.txt#89-92

​
4.1 Path Resolution Logic

The system resolves paths relative to the STATE_ROOT unless absolute paths are provided. The ApplyContext struct tracks these resolved paths during configuration application crates/palyra-cli/src/commands/operator_wizard.rs#151-157. Sources: crates/palyra-cli/src/commands/operator_wizard.rs#151-157, crates/palyra-cli/tests/wizard_cli.rs#12-21