Skip to main content
This page provides technical instructions for setting up a local development environment for the Palyra workspace. It covers the initial bootstrap process, environment configuration, the automated onboarding wizard, and the available build/test automation targets.

​
Environment Prerequisites

Palyra is a polyglot codebase primarily using Rust for the core daemon and CLI, and TypeScript/React for the web and desktop interfaces.

​
Required Toolchain

  • Rust: Latest stable (via rustup).
  • Node.js & npm: Required for apps/web and apps/desktop/ui.
  • Just or Make: Command runners for workspace automation.
  • Protoc: Protocol Buffer compiler for stub generation.

​
Development Bootstrap Flow

The development setup is designed to be self-correcting via the palyra doctor command, which performs strict environment validation before allowing build operations.

​
1. Initial Setup

The quickest way to prepare the environment is using the provided Makefile or justfile. 
# Using Just (recommended)
just dev

# Using Make
make dev
The dev target executes the following sequence:
  1. Environment Validation: Runs palyra doctor --strict to ensure all system dependencies (like protoc, cargo, and npm) are present Makefile#7-11, justfile#7-11.
  2. UI Preparation: Ensures the desktop UI artifacts are initialized via scripts/test/ensure-desktop-ui.sh Makefile#94-95, justfile#44-45.
  3. Workspace Build: Performs a locked build of all Cargo members Makefile#38-40, justfile#112-114.

​
2. Web Workspace Materialization

Palyra uses a custom tool vp (Version Porter) to manage JS dependencies. After the initial build, run: 
make web-bootstrap
This executes vp install to materialize the root JS workspace Makefile#80-81, justfile#30-31.

​
Data Flow: Development Bootstrap

The following diagram illustrates how the bootstrap targets interact with the codebase entities to reach a “Ready” state. Title: Development Bootstrap Lifecycle Sources: Makefile#7-19, justfile#7-22, crates/palyra-cli/src/commands/setup.rs

​
Onboarding & Configuration Wizard

Palyra includes a sophisticated onboarding engine located in crates/palyra-cli/src/commands/operator_wizard.rs. This engine handles both fresh installations (palyra setup) and safe reconfigurations (palyra configure).

​
Wizard Flow Kinds

The wizard supports three primary flows defined in WizardFlowKind crates/palyra-cli/src/commands/operator_wizard.rs#65-69:
  1. Quickstart: Minimal prompts, uses defaults for ports and model selections (e.g., gpt-4o-mini) crates/palyra-cli/src/commands/operator_wizard.rs#18.
  2. Manual: Granular control over bind_profile, TLS paths, and specific model providers.
  3. Remote: Configures a local CLI to communicate with a remote daemon, including SSH tunneling or verified HTTPS setup crates/palyra-cli/src/commands/operator_wizard.rs#97-100.

​
Key Implementation Entities

​
System Mapping: Onboarding Logic

This diagram maps the CLI arguments to the internal mutation logic. Title: Onboarding Logic Mapping Sources: crates/palyra-cli/src/commands/operator_wizard.rs#24-30, crates/palyra-cli/src/commands/operator_wizard.rs#169-195, crates/palyra-cli/src/args/onboarding.rs#34-89

​
Environment Variables

The CLI and Daemon respect several environment variables for overriding local paths and secrets. These are frequently used in tests to isolate the environment crates/palyra-cli/tests/wizard_cli.rs#12-21.
VariableDescription
PALYRA_STATE_ROOTDirectory for databases, logs, and persistent state.
PALYRA_VAULT_DIRDirectory where the encrypted secret vault is stored.
PALYRA_VAULT_BACKENDType of vault storage (e.g., encrypted_file).
OPENAI_API_KEYUsed during quickstart onboarding to seed the vault.
ANTHROPIC_API_KEYAlternative provider key for onboarding crates/palyra-cli/tests/wizard_cli.rs#159.

​
Workspace Automation (Makefile/Justfile)

The workspace provides comprehensive targets for testing, linting, and security auditing.

​
Testing Targets

  • test: Runs all workspace tests, ensuring the desktop UI is ready Makefile#34-36.
  • deterministic-core: Runs a subset of tests that are guaranteed to be deterministic Makefile#97-98.
  • deterministic-soak: Executes long-running stability tests for components like the Discord connector and the daemon’s access record backfill scripts/test/run-deterministic-soak.ps1#9-11.
  • cli-regression: Runs workflow-level regression tests for the CLI Makefile#103-104.

​
Security & Hygiene Targets

  • security: Aggregated target running cargo audit, cargo deny, and custom scripts to check for high-risk patterns Makefile#56-61.
  • protocol: Validates .proto files and regenerates Rust/TypeScript stubs Makefile#29-32.
  • fuzz-build: Compiles all fuzzing targets (e.g., a2ui_json_parser, webhook_payload_parser) Makefile#147-160.

​
Formatting & Linting

  • fmt: Runs cargo fmt across the entire workspace Makefile#1-2.
  • lint: Runs cargo clippy with all targets and treats warnings as errors Makefile#20-21.
Sources: Makefile#1-163, justfile#1-171, scripts/test/run-deterministic-soak.ps1#1-12