> ## Documentation Index
> Fetch the complete documentation index at: https://docs-code.palyra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started: Setup and Configuration

<details>
  <summary>Relevant source files</summary>

  The following files were used as context for generating this wiki page:

  * .githooks/pre-push
  * Makefile
  * crates/palyra-cli/src/args/models.rs
  * crates/palyra-cli/src/args/onboarding.rs
  * crates/palyra-cli/src/commands/configure.rs
  * crates/palyra-cli/src/commands/init.rs
  * crates/palyra-cli/src/commands/models.rs
  * crates/palyra-cli/src/commands/onboarding.rs
  * crates/palyra-cli/src/commands/operator\_wizard.rs
  * crates/palyra-cli/src/commands/setup.rs
  * crates/palyra-cli/src/commands/wizard.rs
  * crates/palyra-cli/tests/help\_snapshots/configure-help.txt
  * crates/palyra-cli/tests/help\_snapshots/onboarding-help.txt
  * crates/palyra-cli/tests/help\_snapshots/onboarding-wizard-help.txt
  * crates/palyra-cli/tests/help\_snapshots/setup-help.txt
  * crates/palyra-cli/tests/models\_cli.rs
  * crates/palyra-cli/tests/wizard\_cli.rs
  * crates/palyra-common/src/daemon\_config\_schema.rs
  * crates/palyra-common/src/feature\_rollouts.rs
  * crates/palyra-daemon/src/application/route\_message/response.rs
  * crates/palyra-daemon/src/config/load.rs
  * crates/palyra-daemon/src/config/schema.rs
  * crates/palyra-daemon/src/model\_provider.rs
  * crates/palyra-daemon/src/model\_provider/adapters.rs
  * crates/palyra-daemon/src/transport/http/handlers/console/mobile.rs
  * crates/palyra-daemon/src/transport/http/handlers/console/onboarding.rs
  * crates/palyra-daemon/src/transport/http/handlers/console/tool\_permissions.rs
  * crates/palyra-daemon/tests/current\_state\_inventory.rs
  * crates/palyra-daemon/tests/support/mod.rs
  * infra/ci/security.yml
  * justfile
  * scripts/clean-runtime-artifacts.sh
  * scripts/test/run-deterministic-core.ps1
  * scripts/test/run-deterministic-core.sh
  * scripts/test/run-performance-smoke.ps1
</details>

This section details the bootstrap process for developers and operators, covering the transition from a fresh repository clone to a fully configured and running Palyra environment. The system utilizes a multi-layered configuration strategy and an interactive onboarding wizard to ensure secure defaults across various deployment profiles.

## Developer Bootstrap and Environment Validation

Palyra uses a `justfile` (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](http://justfile#7-11).                |
| `just dev`           | Full bootstrap: doctor, UI prep, and build. | Enforces `doctor` before `cargo build` [justfile#16-19](http://justfile#16-19).      |
| `just protocol`      | Validates and generates Protobuf stubs.     | Executes scripts in `scripts/protocol/` [justfile#121-125](http://justfile#121-125). |
| `just web-bootstrap` | Materializes JS workspace.                  | Executes `vp install` [justfile#30-31](http://justfile#30-31).                       |

### The Doctor System

The `doctor` 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](http://justfile#10-11).

**Sources:** [justfile#1-22](http://justfile#1-22), [Makefile#1-19](http://Makefile#1-19)

***

## Operator Onboarding Wizard

For operators, the `palyra 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 a `WizardSession` that collects a mutation plan [crates/palyra-cli/src/commands/operator\_wizard.rs#1-6](http://crates/palyra-cli/src/commands/operator_wizard.rs#1-6). It supports three primary variants:

1. **Quickstart:** Minimal configuration for local evaluation [crates/palyra-cli/src/commands/onboarding.rs#34](http://crates/palyra-cli/src/commands/onboarding.rs#34).
2. **Manual:** Granular control over every subsystem [crates/palyra-cli/src/commands/onboarding.rs#35](http://crates/palyra-cli/src/commands/onboarding.rs#35).
3. **Remote:** Optimized for VPS/Server deployments with SSH tunnel or verified HTTPS setup [crates/palyra-cli/src/commands/onboarding.rs#36](http://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

```mermaid theme={null}
graph TD
    subgraph "CLI Layer (palyra-cli)"
        A["OnboardingCommand"] -- "Wizard" --> B["run_onboarding_wizard()"]
        A -- "Status" --> C["run_onboarding_status()"]
    end

    subgraph "Wizard Core"
        B --> D["WizardSession"]
        D --> E["InteractiveWizardBackend"]
        D --> F["NonInteractiveWizardBackend"]
    end

    subgraph "Implementation (operator_wizard.rs)"
        E --> G["auth_method_flow()"]
        G --> H["ModelProviderConfig"]
        B --> I["ApplyContext"]
    end

    style A stroke-width:2px
    style B stroke-width:2px
    style H stroke-width:2px
```

**Sources:** [crates/palyra-cli/src/commands/onboarding.rs#137-152](http://crates/palyra-cli/src/commands/onboarding.rs#137-152), [crates/palyra-cli/src/commands/operator\_wizard.rs#39-44](http://crates/palyra-cli/src/commands/operator_wizard.rs#39-44), [crates/palyra-cli/src/commands/operator\_wizard.rs#112-117](http://crates/palyra-cli/src/commands/operator_wizard.rs#112-117)

***

## Configuration 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](http://crates/palyra-common/src/daemon_config_schema.rs#32).

### Key Configuration Sections

* **`deployment`**: Defines the `profile` (e.g., `local_desktop`, `server`) and security acknowledgments [crates/palyra-common/src/daemon\_config\_schema.rs#58-79](http://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](http://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](http://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](http://crates/palyra-daemon/src/config/schema.rs#81-105).

### Configuration Precedence

The `load_config` function enforces a strict hierarchy of values:

1. **Defaults:** Hardcoded in `crates/palyra-daemon/src/config/schema.rs` [crates/palyra-daemon/src/config/load.rs#92-115](http://crates/palyra-daemon/src/config/load.rs#92-115).
2. **Config File:** Values provided in `palyra.toml` [crates/palyra-daemon/src/config/load.rs#121-125](http://crates/palyra-daemon/src/config/load.rs#121-125).
3. **Environment Variables:** Prefixed with `PALYRA_` (e.g., `PALYRA_DAEMON_PORT`) [crates/palyra-daemon/src/config/load.rs#4-9](http://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 `VaultRef` [crates/palyra-common/src/daemon\_config\_schema.rs#29](http://crates/palyra-common/src/daemon_config_schema.rs#29).
* Referenced via **Environment Variables** using `SecretRef` [crates/palyra-common/src/daemon\_config\_schema.rs#12](http://crates/palyra-common/src/daemon_config_schema.rs#12).
* Redacted in logs and exports via `SECRET_CONFIG_PATHS` [crates/palyra-common/src/daemon\_config\_schema.rs#22-38](http://crates/palyra-common/src/daemon_config_schema.rs#22-38).

**Sources:** [crates/palyra-daemon/src/config/load.rs#1-18](http://crates/palyra-daemon/src/config/load.rs#1-18), [crates/palyra-common/src/daemon\_config\_schema.rs#1-52](http://crates/palyra-common/src/daemon_config_schema.rs#1-52), [crates/palyra-daemon/src/config/schema.rs#30-141](http://crates/palyra-daemon/src/config/schema.rs#30-141)

***

## Deployment Profiles

The `deployment.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](http://crates/palyra-common/src/daemon_config_schema.rs#70-79). |
| `remote_agent`  | Headless worker node | Variable     | Enforces mTLS and Vault-backed secrets.                                                                                                                         |

**Sources:** [crates/palyra-common/src/daemon\_config\_schema.rs#58-68](http://crates/palyra-common/src/daemon_config_schema.rs#58-68), [crates/palyra-daemon/src/config/load.rs#130-141](http://crates/palyra-daemon/src/config/load.rs#130-141)

***

## Model Provider Setup Flow

A critical part of "Getting Started" is the `palyra models` CLI family, which manages the provider registry.

### Provider Discovery and Validation

1. **Set Provider:** `palyra models set <MODEL_ID>` updates the default text model [crates/palyra-cli/tests/models\_cli.rs#33-45](http://crates/palyra-cli/tests/models_cli.rs#33-45).
2. **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](http://crates/palyra-cli/src/commands/models.rs#177-182).
3. **Discovery:** `palyra models discover` fetches available models from the remote and caches them in `models/provider_checks.json` [crates/palyra-cli/src/commands/models.rs#39-40](http://crates/palyra-cli/src/commands/models.rs#39-40).

### Data Flow: Provider Configuration

Title: Model Provider Configuration Flow

```mermaid theme={null}
sequenceDiagram
    participant Op as Operator (CLI)
    participant Wiz as operator_wizard.rs
    participant V as palyra-vault
    participant C as LoadedConfig
    participant P as RegistryBackedModelProvider

    Op->>Wiz: palyra setup --auth-method api-key
    Wiz->>V: Store API Key (VaultRef)
    Wiz->>C: Write palyra.toml (model_provider.kind)
    C->>P: Initialize with ProviderRegistryEntryConfig
    P->>P: resolve_credentials()
    P-->>Op: Health Check Success
```

**Sources:** [crates/palyra-cli/src/commands/models.rs#1-10](http://crates/palyra-cli/src/commands/models.rs#1-10), [crates/palyra-daemon/src/model\_provider.rs#10-12](http://crates/palyra-daemon/src/model_provider.rs#10-12), [crates/palyra-cli/src/commands/operator\_wizard.rs#4-6](http://crates/palyra-cli/src/commands/operator_wizard.rs#4-6)