Developer Bootstrap and Environment Validation
Palyra uses ajustfile (and a legacy Makefile) to orchestrate developer workflows. The primary entry point for a new developer is the dev target, which enforces environment sanity before building the workspace.
Core Bootstrap Commands
| Command | Action | Implementation |
|---|---|---|
just doctor | Runs strict environment checks. | Calls palyra doctor --strict justfile#7-11. |
just dev | Full bootstrap: doctor, UI prep, and build. | Enforces doctor before cargo build justfile#16-19. |
just protocol | Validates and generates Protobuf stubs. | Executes scripts in scripts/protocol/ justfile#121-125. |
just web-bootstrap | Materializes JS workspace. | Executes vp install justfile#30-31. |
The Doctor System
Thedoctor command is a critical diagnostic tool that verifies system dependencies, filesystem permissions, and network accessibility. It must pass with --strict for the dev target to proceed justfile#10-11.
Sources: justfile#1-22, Makefile#1-19
Operator Onboarding Wizard
For operators, thepalyra onboarding and palyra setup commands initiate an interactive wizard. This wizard abstracts the complexity of generating a valid palyra.toml, configuring the vault, and verifying model provider connectivity.
Onboarding Flow Logic
The wizard operates through aWizardSession that collects a mutation plan crates/palyra-cli/src/commands/operator_wizard.rs#1-6. It supports three primary variants:
- Quickstart: Minimal configuration for local evaluation crates/palyra-cli/src/commands/onboarding.rs#34.
- Manual: Granular control over every subsystem crates/palyra-cli/src/commands/onboarding.rs#35.
- Remote: Optimized for VPS/Server deployments with SSH tunnel or verified HTTPS setup crates/palyra-cli/src/commands/onboarding.rs#36.
Code Entity Mapping: Onboarding Logic
The following diagram maps the CLI command structure to the underlying wizard implementation. Title: Onboarding Command to Code Mapping Sources: crates/palyra-cli/src/commands/onboarding.rs#137-152, crates/palyra-cli/src/commands/operator_wizard.rs#39-44, crates/palyra-cli/src/commands/operator_wizard.rs#112-117Configuration Schema (palyra.toml)
The palyra.toml file is the source of truth for the daemon. It is mirrored in code by the RootFileConfig struct crates/palyra-common/src/daemon_config_schema.rs#32.
Key Configuration Sections
deployment: Defines theprofile(e.g.,local_desktop,server) and security acknowledgments crates/palyra-common/src/daemon_config_schema.rs#58-79.model_provider: Configures the LLM backend (OpenAI, Anthropic, or Deterministic) crates/palyra-common/src/daemon_config_schema.rs#158-167.gateway: Network bind settings and TLS configuration crates/palyra-common/src/daemon_config_schema.rs#103-134.tool_call: Sandbox limits, browser service endpoints, and allowed tools crates/palyra-daemon/src/config/schema.rs#81-105.
Configuration Precedence
Theload_config function enforces a strict hierarchy of values:
- Defaults: Hardcoded in
crates/palyra-daemon/src/config/schema.rscrates/palyra-daemon/src/config/load.rs#92-115. - Config File: Values provided in
palyra.tomlcrates/palyra-daemon/src/config/load.rs#121-125. - Environment Variables: Prefixed with
PALYRA_(e.g.,PALYRA_DAEMON_PORT) crates/palyra-daemon/src/config/load.rs#4-9.
Secret Handling
Palyra distinguishes between standard configuration and sensitive data. Secrets (API keys, admin tokens) are never stored in the clear if configured via the wizard. They are either:- Stored in the Vault using
VaultRefcrates/palyra-common/src/daemon_config_schema.rs#29. - Referenced via Environment Variables using
SecretRefcrates/palyra-common/src/daemon_config_schema.rs#12. - Redacted in logs and exports via
SECRET_CONFIG_PATHScrates/palyra-common/src/daemon_config_schema.rs#22-38.
Deployment Profiles
Thedeployment.profile setting determines the runtime’s security posture and network behavior.
| Profile | Target Use Case | Default Bind | Security Posture |
|---|---|---|---|
local_desktop | Local dev/Tauri app | 127.0.0.1 | Assumes local user trust. |
server | Shared VPS / Docker | 0.0.0.0 | Requires dangerous_remote_bind_ack crates/palyra-common/src/daemon_config_schema.rs#70-79. |
remote_agent | Headless worker node | Variable | Enforces mTLS and Vault-backed secrets. |
Model Provider Setup Flow
A critical part of “Getting Started” is thepalyra models CLI family, which manages the provider registry.
Provider Discovery and Validation
- Set Provider:
palyra models set <MODEL_ID>updates the default text model crates/palyra-cli/tests/models_cli.rs#33-45. - Test Connection: The CLI performs a probe against the provider endpoint (e.g.,
/v1/models) to verify the API key and network egress crates/palyra-cli/src/commands/models.rs#177-182. - Discovery:
palyra models discoverfetches available models from the remote and caches them inmodels/provider_checks.jsoncrates/palyra-cli/src/commands/models.rs#39-40.