Environment Bootstrapping
Before running the Palyra CLI or daemon, the environment must be prepared with necessary dependencies and workspace materialization.Developer Bootstrap
The repository provides two primary scripts for automated dependency installation and environment preparation:scripts/dev/bootstrap.sh: For Unix-based systems.scripts/dev/bootstrap.ps1: For Windows systems.
- Toolchain Validation: Ensures
rustc,cargo, andnpmare available. - Protocol Buffers: Validates or installs
protocfor gRPC stub generation Makefile#23-32. - JS Workspace: Executes
vp installto materialize the root JavaScript/TypeScriptnode_modulesacross the monorepo justfile#30-31. - UI Preparation: Ensures the desktop UI assets are staged for the Tauri build justfile#44-45.
Automation with Just/Make
The project usesjust (preferred) or make to orchestrate common setup tasks.
just dev: Runs the doctor check, prepares the UI, and builds the workspace justfile#16-20.just doctor: Runs strict environment validation justfile#7-11.
The Setup and Onboarding Wizard
Palyra uses a guided onboarding system implemented in the CLI to generate initial configurations. This is handled by thepalyra setup command (aliased to init) crates/palyra-cli/tests/cli_parity_report.md#30.
Wizard Flows
TheOnboardingWizardRequest crates/palyra-cli/src/commands/operator_wizard.rs#24-30 supports three primary flows defined by WizardFlowKind crates/palyra-cli/src/commands/operator_wizard.rs#65-69:
| Flow | Purpose | Key Actions |
|---|---|---|
Quickstart | Rapid local setup | Auto-detects environment, prompts for API keys, sets up loopback-only binding. |
Manual | Custom local/server setup | Allows specific port configuration, TLS certificate paths, and advanced storage options. |
Remote | Connecting to a remote daemon | Configures mTLS identities and remote base URLs for CLI-to-Daemon communication. |
Implementation Logic
The wizard operates as a state machine usingWizardSession and WizardStep crates/palyra-cli/src/commands/operator_wizard.rs#10-13. It can run in InteractiveWizardBackend (terminal prompts) or NonInteractiveWizardBackend (using CLI flags for CI/CD) crates/palyra-cli/src/commands/operator_wizard.rs#9-13.
Sources: crates/palyra-cli/src/commands/operator_wizard.rs, crates/palyra-cli/tests/help_snapshots/setup-help.txt
Configuration Schema (palyra.toml)
The central configuration file is palyra.toml. It is parsed into the RootFileConfig struct crates/palyra-common/src/daemon_config_schema.rs#102-119.
Key Configuration Sections
deployment: Sets the mode (e.g.,local) and security acknowledgments for remote binding crates/palyra-common/src/daemon_config_schema.rs#123-126.daemon: Defines thebind_addrandportfor the HTTP Admin API crates/palyra-common/src/daemon_config_schema.rs#130-133.gateway: Configures gRPC/QUIC listeners, mTLS, and identity storage crates/palyra-common/src/daemon_config_schema.rs#137-150.model_provider: Defines the LLM backends (OpenAI, Anthropic, etc.) and their respective API keys crates/palyra-common/src/daemon_config_schema.rs#112.
Security and Redaction
To prevent accidental leakage of secrets in logs or support bundles, the system usesSECRET_CONFIG_PATHS crates/palyra-common/src/daemon_config_schema.rs#6-16. The function redact_secret_config_values recursively traverses the TOML document and replaces sensitive values with <redacted> crates/palyra-common/src/daemon_config_schema.rs#24-29.
Data Flow: Configuration Loading
The daemon loads configuration through a multi-step process: Sources: crates/palyra-daemon/src/config/load.rs#31-60, crates/palyra-common/src/daemon_config_schema.rsEnvironment Variables
Palyra uses environment variables to override file-based configuration or provide secrets in containerized environments.| Variable | Description |
|---|---|
PALYRA_STATE_ROOT | The directory where the SQLite database and logs are stored crates/palyra-cli/tests/wizard_cli.rs#14. |
PALYRA_VAULT_DIR | Location of the encrypted secret vault crates/palyra-cli/tests/wizard_cli.rs#15. |
PALYRA_BROWSERD_STATE_DIR | Storage for headless browser profiles crates/palyra-cli/src/commands/doctor/recovery.rs#34. |
PALYRA_BROWSERD_STATE_ENCRYPTION_KEY | Key used to encrypt browser profile data crates/palyra-cli/src/commands/doctor/recovery.rs#33. |
Environment Validation: The Doctor Command
Thepalyra doctor command is a diagnostic tool used to validate the health of the environment and perform automated repairs.
Diagnostic Pipeline
The doctor executes a series ofDoctorCheck routines. If a check fails, it generates a DoctorRepairStep crates/palyra-cli/src/commands/doctor/recovery.rs#105-118.
Repair and Recovery
The doctor can perform several automated fixes:- Config Migration: Updates
palyra.tomlto the latest schema version crates/palyra-cli/src/commands/doctor/recovery.rs#182-184. - Registry Normalization: Fixes malformed JSON/TOML files in the
auth_profiles.tomlorroutines/directory crates/palyra-cli/src/commands/doctor/recovery.rs#195-198. - Identity Recovery: Regenerates missing mTLS certificates or browser auth tokens crates/palyra-cli/src/commands/doctor/recovery.rs#192-194.