Multi-Transport Architecture
Thepalyrad daemon acts as a unified gateway hub, multiplexing multiple protocols over configured network interfaces crates/palyra-daemon/src/lib.rs#1-10. The architecture is centered around a shared GatewayRuntimeState, which acts as the source of truth for all transport handlers crates/palyra-daemon/src/gateway/runtime.rs#1-12.
Transport Topology
The following diagram illustrates how external clients interact with the daemon’s internal subsystems through various transport protocols. Transport to Code Entity Mapping Sources: crates/palyra-daemon/src/lib.rs#1-33, crates/palyra-daemon/src/transport/http/router.rs#1-25, crates/palyra-daemon/src/gateway/runtime.rs#1-12.HTTP Surface (Axum)
The HTTP surface is implemented using theaxum framework and is partitioned into several functional namespaces crates/palyra-daemon/src/transport/http/router.rs#24-25.
API Routing Table
| Namespace | Path Prefix | Primary Purpose | Key Handlers |
|---|---|---|---|
| Console API | /console/v1 | Powers the React web dashboard. | console_diagnostics_handler, console_models_discover_handler |
| Admin API | /admin/v1 | Low-level daemon management and state repair. | admin_status_handler, admin_state_repair_handler |
| Compat API | /v1 | OpenAI-compatible completions and models endpoints. | compat::completions_handler |
| Realtime | /realtime/v1 | WebSocket/SSE streams for live agent updates. | realtime::stream_handler |
| Canvas | /canvas/v1 | State management for the interactive A2UI canvas. | canvas::patch_handler |
HTTP Middleware
Palyra employs a layered middleware stack to enforce security and observability invariants crates/palyra-daemon/src/transport/http/router.rs#19-21:- Authentication: Validates session cookies or bearer tokens against the
AuthProfileRegistrycrates/palyra-daemon/src/transport/http/handlers/console/diagnostics.rs#74. - CSRF Protection: Enforces Double-Submit Cookie patterns for state-changing operations crates/palyra-daemon/src/transport/http/handlers/console/models.rs#121.
- Rate Limiting: Protects sensitive endpoints (e.g., auth connect) from brute-force attempts.
- Redaction: Automatically redacts secrets from JSON responses using
redact_console_diagnostics_valuebefore they leave the transport layer crates/palyra-daemon/src/transport/http/handlers/console/diagnostics.rs#86-92.
gRPC Services
The daemon exposes structured services via Protobuf definitions located inschemas/proto/palyra/v1/. These are served using the tonic library crates/palyra-daemon/src/lib.rs#1-4.
Key gRPC Service Definitions
- Gateway Service (
gateway.v1): The primary interface for session management, run execution, and agent interaction. - Memory Service (
memory.v1): Provides high-performance access to the RAG (Retrieval-Augmented Generation) index and memory lifecycle operations crates/palyra-daemon/src/gateway/runtime.rs#105-110. - Browser Service (
browser.v1): Used by thepalyra-browserdsidecar to report page snapshots, logs, and element captures back to the daemon schemas/generated/rust/protocol_stubs.rs#61-88. - Auth Service (
auth.v1): Manages theAuthProfilelifecycle, including credential rotation and health checks schemas/generated/rust/protocol_stubs.rs#7-26.
QUIC Transport
The QUIC transport is used primarily for node-to-node communication and high-throughput worker telemetry crates/palyra-daemon/src/lib.rs#25-27. It is implemented incrates/palyra-transport-quic and integrated via the quic_runtime.rs in the daemon crates/palyra-daemon/src/quic_runtime.rs.
- Identity & Security: QUIC connections require mTLS using certificates managed by the
palyra-identitycrate. - Multiplexing: Leverages QUIC streams to prevent head-of-line blocking between concurrent tool execution logs and agent state updates.