palyra-daemon (palyrad) is the central execution engine of the Palyra ecosystem. It acts as the “brain” that orchestrates agentic workflows, manages long-term memory via the Journal, and exposes multiple interface surfaces for users and external systems. It is designed as a multi-tenant, secure-by-default service that handles everything from real-time gRPC streams to background cron routines.
GatewayRuntimeState
TheGatewayRuntimeState is the primary coordinator within the daemon. It maintains the in-memory state of active runs, caches for tool approvals, and handles the lifecycle of the orchestration engine.
- Run Management: Tracks active
RunStateMachineinstances and their transitions crates/palyra-daemon/src/gateway.rs#77-77. - Resource Caching: Implements caching for tool approval decisions crates/palyra-daemon/src/gateway/runtime.rs#145-152, HTTP fetch results crates/palyra-daemon/src/gateway/runtime.rs#155-158, and memory search hits crates/palyra-daemon/src/gateway/runtime.rs#161-164.
- Security Context: Enforces principal and device identification via headers like
x-palyra-principalandx-palyra-device-idcrates/palyra-daemon/src/gateway.rs#86-87.
Daemon Component Interaction
The following diagram illustrates how theGatewayRuntimeState bridges the network interfaces to the underlying persistence and execution layers.
System Component Map
Sources: crates/palyra-daemon/src/gateway.rs#40-82, crates/palyra-daemon/src/transport/http/router.rs#18-133
Network Interfaces
The daemon exposes three distinct API surfaces to accommodate different callers and security requirements.1. gRPC Gateway
The gRPC interface, defined ingateway.proto, is used for high-performance, bidirectional communication. It is the primary interface for the RunStream endpoint, which allows clients to interact with agents in real-time.
- Services: Includes
GatewayService,AuthServiceImpl,CronServiceImpl, andVaultServiceImplcrates/palyra-daemon/src/gateway.rs#41-44. - Authentication: Uses
GatewayAuthConfigto authorize metadata headers crates/palyra-daemon/src/transport/grpc/auth.rs#163-165.
2. HTTP Admin API (/admin/v1)
A restricted surface for system-level operations, typically used by CLI tools or automated infrastructure.
- Endpoints: Status checks, journal inspection, and policy explanation crates/palyra-daemon/src/transport/http/router.rs#19-21.
- Security: Protected by a dedicated admin token and rate-limiting middleware crates/palyra-daemon/src/transport/http/router.rs#127-133.
3. HTTP Console API (/console/v1)
The backend for the Palyra Web Console. It provides a rich set of handlers for session management, agent configuration, and diagnostic tools.
- Scope: Covers everything from
chatandsessionstomemoryandskillscrates/palyra-daemon/src/transport/http/handlers/console/mod.rs#1-28. - Transport: Built using the
axumframework crates/palyra-daemon/src/transport/http/router.rs#1-6.
Subsystem Overviews
Persistence and Journaling
All system events, message transcripts, and state changes are recorded in theJournalStore. This SQLite-backed engine ensures that every action taken by an agent is auditable and recoverable.
- Key Entity:
JournalStorecrates/palyra-daemon/src/journal.rs#80-80. - Features: Full-text search (FTS5), vector embeddings for long-term memory, and hash-chaining for integrity.
- For details, see Journal Store and Persistence.
Model and Embedding Providers
The daemon abstracts LLM interactions through theModelProvider and EmbeddingsProvider traits. This allows Palyra to switch between OpenAI, Anthropic, or local models seamlessly.
- Key Entities:
ModelProvidercrates/palyra-daemon/src/model_provider.rs#74-74,HashMemoryEmbeddingProvidercrates/palyra-daemon/src/journal.rs#71-73. - For details, see Configuration and Model Provider.
Background Tasks and Governance
The daemon includes a background scheduler for cron jobs and routines, alongside a governance engine that tracks token usage and enforces budgets.- Scheduler:
spawn_scheduler_loopcrates/palyra-daemon/src/lib.rs#73-73. - Governance:
usage_governancemodule handles cost limits and smart routing crates/palyra-daemon/src/gateway/runtime.rs#31-31. - For details, see Usage Governance, Diagnostics, and Self-Healing.
Code Entity Map
The following table maps logical architectural concepts to their primary implementation files.| Architectural Concept | Primary Code Entity | File Path |
|---|---|---|
| Execution Engine | GatewayRuntimeState | crates/palyra-daemon/src/gateway.rs |
| State Machine | RunStateMachine | crates/palyra-daemon/src/orchestrator.rs |
| Persistence | JournalStore | crates/palyra-daemon/src/journal.rs |
| HTTP Routing | build_router | crates/palyra-daemon/src/transport/http/router.rs |
| LLM Interface | ModelProvider | crates/palyra-daemon/src/model_provider.rs |
| Secrets Management | Vault | crates/palyra-daemon/src/gateway.rs#28-28 |