palyrad daemon is the central orchestrator of the Palyra ecosystem. It manages agent lifecycles, handles multi-modal transport (HTTP, gRPC, QUIC), enforces security policies, and persists system state in a secure journal.
System Overview
The daemon is built as a high-performance asynchronous service in Rust, utilizingtokio for its runtime and axum for its web surface. It acts as the “brain” that connects user interfaces (Console, CLI, Discord) to execution environments (Sandboxes, Browser) and AI models.
Initialization Sequence
The daemon follows a strict bootstrap sequence defined incrates/palyra-daemon/src/lib.rs. It loads configuration, initializes the SQLite-backed JournalStore, starts the GatewayRuntimeState, and spawns background loops for scheduling and maintenance.
Code-to-Entity Mapping
The following diagram maps high-level system components to their primary implementation structures and files within thepalyra-daemon crate.
Daemon Component Map
Sources: crates/palyra-daemon/src/lib.rs#51-84, crates/palyra-daemon/src/gateway.rs#73-82, crates/palyra-daemon/src/app/state.rs#29-59
Subsystems
The daemon is partitioned into several specialized subsystems. Detailed documentation for each can be found in the linked child pages.Gateway and Orchestration Engine
TheGatewayRuntimeState is the central hub for all operations. It manages the RunStateMachine, which transitions agent tasks through states like Accepted, Running, and Succeeded. It handles the “tape”—an append-only log of events for every run.
- Key Entity:
GatewayRuntimeStatesrc/gateway.rs#74-141 - Key Entity:
RunStateMachinesrc/orchestrator.rs
HTTP and gRPC Transport Layer
Palyra exposes multiple interfaces: an Axum-based HTTP server for the Admin UI and OpenAI-compatible clients, and a Tonic-based gRPC server for high-performance internal communication and the CLI.- Key Entity:
build_routersrc/transport/http/router.rs#17-210 - Key Entity:
GatewayServicesrc/transport/grpc/proto/palyra.gateway.v1.rs
Configuration and Model Provider
Manages theRootFileConfig (TOML) and abstracts AI interactions through the ModelProvider trait. This allows the system to switch between OpenAI, local models, or deterministic providers while handling secrets via the Vault.
- Key Entity:
RootFileConfigpalyra-common/daemon_config_schema - Key Entity:
ModelProvidersrc/model_provider.rs#73-76
Journal Store and Persistence
A SQLite-backed append-only store (JournalStore) that tracks every message, tool execution, and state change. It includes full-text search (FTS) for memory recall and hash-chain integrity for security.
- Key Entity:
JournalStoresrc/journal.rs#63-84 - Key Entity:
JournalEventRecordsrc/journal.rs#63
Scheduler, Routines, and Background Tasks
Thespawn_scheduler_loop handles cron-based jobs and recurring routines. It manages task concurrency policies (e.g., Forbid, Replace, QueueOne) and ensures background maintenance like memory embedding backfills.
- Key Entity:
spawn_scheduler_loopsrc/cron.rs#73 - Key Entity:
CronJobRecordsrc/journal.rs#61
Node Runtime and mTLS Pairing
Handles the identity of external nodes (likebrowserd). It uses a pairing code flow to issue mTLS certificates, ensuring all node-to-node communication is encrypted and authenticated.
- Key Entity:
NodeRuntimeStatesrc/node_runtime.rs - Key Entity:
PairingCodeRecordsrc/channel_router.rs#52
Usage Governance and Access Control
Enforces rate limits, token budgets, and permission checks via theAccessRegistry. It integrates the Cedar policy engine to decide if a specific principal can execute a specific tool.
- Key Entity:
AccessRegistrysrc/access_control.rs - Key Entity:
evaluate_with_configsrc/gateway.rs#23
Data Flow: Request Lifecycle
This diagram illustrates how a request (e.g., a message from the CLI) flows through the daemon’s internal entities. Message Processing Flow Sources: crates/palyra-daemon/src/transport/grpc/auth.rs#163-165, crates/palyra-daemon/src/gateway.rs#188-210, crates/palyra-daemon/src/orchestrator.rs#77-80Resource Constraints and Constants
The daemon enforces strict limits to ensure stability and security:| Constant | Value | Purpose |
|---|---|---|
MAX_JOURNAL_RECENT_EVENTS | 100 | Limit for recent event snapshots |
JOURNAL_WRITE_LATENCY_BUDGET_MS | 25ms | Target latency for DB writes |
MAX_MEMORY_ITEM_BYTES | 16 KB | Maximum size of a single memory entry |
MAX_HTTP_FETCH_BODY_BYTES | 512 KB | Egress tool response limit |