Skip to main content
The Palyra configuration system provides a structured, versioned, and secure mechanism for managing daemon settings via the palyra.toml file. It supports automatic migrations, secret redaction, and runtime mutation through both the CLI and the web console.

​
Root Configuration Schema

The configuration is anchored by the RootFileConfig struct, which maps the TOML file structure into strongly-typed Rust modules.
SectionDescriptionKey Code Entity
daemonBasic networking (bind address, port).FileDaemonConfig
gatewaygRPC and QUIC transport settings, TLS, and identity.FileGatewayConfig
model_providerLLM backend settings (OpenAI, API keys, timeouts).FileModelProviderConfig
memoryVector memory retention and auto-injection policies.FileMemoryConfig
tool_callSandboxing tiers and execution limits for plugins.FileToolCallConfig
vault_refReferences to secrets stored in the platform vault.VaultRef
Sources: crates/palyra-common/src/daemon_config_schema.rs#64-81, crates/palyra-daemon/src/config/schema.rs#87-105

​
Configuration Loading Pipeline

The daemon loads configuration by searching standard paths (e.g., ./palyra.toml, ~/.config/palyra/palyra.toml). The process involves parsing, migrating old versions to the current schema, and merging file values with system defaults.

​
Loading Logic Flow

The load_config function in palyra-daemon orchestrates the transformation from a raw TOML file to a LoadedConfig object used by the runtime. Config Loading Sequence Sources: crates/palyra-daemon/src/config/load.rs#29-56, crates/palyra-common/src/config_system.rs#89-129

​
Secret Redaction and Safety

Palyra implements a “Secure by Default” approach to configuration display. Sensitive keys are never printed to logs or CLI output unless explicitly requested.

​
Redaction Mechanisms

  1. Path-Based Redaction: Specific TOML paths (e.g., admin.auth_token) are hardcoded in SECRET_CONFIG_PATHS for redaction.
  2. Marker-Based Redaction: Any key containing substrings like api_key, secret, or token is automatically redacted during general JSON/TOML tree processing.
  3. Vault References: Instead of storing raw strings, configuration can use vault_ref values (e.g., vault://global/openai_api_key), which instructs the daemon to fetch the value from the secure Vault at runtime.
Sources: crates/palyra-common/src/daemon_config_schema.rs#6-14, crates/palyra-common/src/redaction.rs#5-22, crates/palyra-daemon/src/model_provider.rs#131-134

​
Runtime Mutation via CLI

The palyra CLI provides a sub-command tree for manipulating palyra.toml without manual text editing. It uses the config_system.rs utilities to perform atomic updates and maintain backups.

​
CLI Config Commands

  • palyra config get --key <PATH>: Retrieves a value. Redacts secrets unless --show-secrets is passed.
  • palyra config set --key <PATH> --value <TOML_LITERAL>: Updates or creates a key.
  • palyra config unset --key <PATH>: Removes a configuration entry.

​
Mutation Logic

When a value is set, the system:
  1. Parses the existing file into a toml::Value table.
  2. Creates a backup (e.g., palyra.toml.bak.1) using a rotation strategy.
  3. Traverses the table to the target path, creating intermediate tables if necessary.
  4. Serializes the result back to disk, preserving file permissions (e.g., 0o600 for private configs).
Sources: crates/palyra-cli/tests/config_mutation.rs#26-103, crates/palyra-common/src/config_system.rs#174-204, crates/palyra-cli/tests/config_mutation.rs#149-191

​
Data Flow: File to Code Entities

This diagram illustrates how a TOML entry is transformed into a functional runtime configuration within the palyrad process. Config Entity Mapping Sources: crates/palyra-common/src/daemon_config_schema.rs#64-81, crates/palyra-daemon/src/config/schema.rs#87-105, crates/palyra-daemon/src/model_provider.rs#123-140

​
Implementation Details

​
Key Functions and Constants

​
Config Permissions (Unix)

On Unix systems, the configuration system explicitly preserves the file mode. If a palyra.toml is set to 0o600 (owner read/write only), the set_value_at_path logic ensures the new file written after mutation retains these restricted permissions. Sources: crates/palyra-cli/tests/config_mutation.rs#107-146, crates/palyra-common/src/config_system.rs#8-10