Core System Concepts
Gateway Runtime State
The central in-memory state of thepalyrad daemon. It orchestrates the lifecycle of sessions, runs, and the routing of messages between inbound channels (e.g., Discord, CLI) and the LLM provider.
- Implementation: Managed via
GatewayRuntimeStatein crates/palyra-daemon/src/gateway.rs#1-100. - Key Function:
route_messagehandles the entry point for new user interactions crates/palyra-daemon/src/gateway.rs#96-96.
Journal Store
The persistence layer for all system events, audit logs, and agent memory. It uses an append-only logic backed by SQLite with hash-chaining to ensure audit integrity.- Implementation:
JournalStorestruct in crates/palyra-daemon/src/journal.rs#63-71. - Data Flow: Every state transition in a
RunStateMachineis persisted as aJournalEventRecordcrates/palyra-daemon/src/journal.rs#63-63.
Orchestrator Tape
A linear sequence of events belonging to a specific “Run”. It includes the prompt, LLM responses, tool calls, and tool outputs. It acts as the “memory” of a single conversation turn.- Code Pointer:
OrchestratorTapeRecordin crates/palyra-daemon/src/journal.rs#69-69. - Usage: The
RunStateMachineappends events to the tape during execution crates/palyra-daemon/src/gateway.rs#69-71.
Security & Governance
Cedar Policy Engine
The authorization layer that evaluates whether a principal (user/agent) is allowed to perform an action (e.g., execute a tool) on a resource.- Implementation:
palyra-policycrate using the Cedar language crates/palyra-policy/src/lib.rs#1-10. - Key Function:
evaluate_with_contextcrates/palyra-daemon/src/tool_protocol.rs#4-6.
Tool Sandboxing Tiers
Palyra categorizes tool execution into three isolation tiers to balance performance and security.- Tier A: WASM-based isolation using
wasmtimecrates/palyra-daemon/src/tool_protocol.rs#17-17. - Tier B: Unix-level resource controls (
rlimit) crates/palyra-daemon/src/sandbox_runner.rs#65-78. - Tier C: OS-level sandboxing (e.g.,
bwrapon Linux,sandbox-execon macOS) crates/palyra-daemon/src/sandbox_runner.rs#65-78.
Vault
A secure storage abstraction for secrets (API keys, tokens). It supports platform-specific backends like macOS Keychain or Linux Secret Service.- Implementation:
palyra-vaultcrate crates/palyra-vault/src/lib.rs#1-28. - Code Pointer:
Vaulttrait andVaultScopecrates/palyra-daemon/src/gateway.rs#28-28.
Technical Domain Map
Natural Language to Code Entity Space
The following diagram maps high-level user concepts to the specific Rust structs and Protobuf definitions that implement them. System Concept Mapping Sources: crates/palyra-daemon/src/gateway.rs#50-54, crates/palyra-daemon/src/tool_protocol.rs#4-6, crates/palyra-vault/src/lib.rs#28-28Data Flow & Lifecycle
Run State Machine (RSM)
The RSM manages the lifecycle of an AI interaction, transitioning through states likePending, Running, AwaitingApproval, and Completed.
Run Lifecycle Transitions
Sources: crates/palyra-daemon/src/gateway.rs#77-77, crates/palyra-daemon/src/orchestrator.rs#1-100
Key Abbreviations
| Abbreviation | Full Term | Description | Code Pointer |
|---|---|---|---|
| ACP | Agent Control Protocol | Protocol for external tools to control the daemon via stdio/gRPC. | crates/palyra-cli/src/cli.rs#1-2 |
| A2UI | Agent-to-User Interface | JSON-patch based protocol for rendering dynamic UIs in the console. | crates/palyra-a2ui/src/lib.rs#1-15 |
| CDP | Chrome DevTools Protocol | Used by browserd to automate headless Chromium. | crates/palyra-browserd/Cargo.toml#1-20 |
| mTLS | Mutual TLS | Used for secure Node-to-Daemon communication. | crates/palyra-daemon/src/gateway.rs#116-121 |
| TOFU | Trust On First Use | Security model for pairing new devices or installing skills. | crates/palyra-identity/src/lib.rs#1-10 |
System Components Relationship
This diagram illustrates how the various daemons and libraries interact within the monorepo. Crate Architecture Sources: Cargo.toml#1-21, apps/desktop/src-tauri/src/supervisor.rs#1-50Configuration Terms
Redacted Config Path
A set of hardcoded paths inpalyra.toml that the system ensures are never logged or returned in plain text via the Admin API.
- Definition:
SECRET_CONFIG_PATHSin crates/palyra-common/src/daemon_config_schema.rs#6-14. - Mechanism:
redact_secret_config_valuesfunction crates/palyra-common/src/daemon_config_schema.rs#22-26.
Cron Schedule Types
Definitions for recurring background tasks.- Cron: Standard crontab string.
- Every: Interval-based (e.g., every 5 minutes).
- At: One-time execution at a specific timestamp.
- Implementation:
CronScheduleTypeenum in crates/palyra-daemon/src/journal.rs#104-108.