Architecture Overview
The networking stack is divided into three primary functional planes:- Operator Plane (HTTP/WS): Provides the REST and WebSocket APIs used by the Web Console and Desktop Companion via
axum. - Control Plane (gRPC): Facilitates structured communication between the CLI, Browser Daemon, and the Core Daemon using
tonic. - Data & Node Plane (QUIC): Handles high-throughput, mTLS-secured node-to-node communication and event streaming using
quinn.
System Protocol Mapping
| Protocol | Implementation | Primary Use Case | Port / Service |
|---|---|---|---|
| HTTP/1.1+ | axum | Admin API, Static Assets, Webhooks | palyrad (default 8080) |
| gRPC | tonic | Agent Control, Browser Automation | palyra-browserd, palyrad |
| QUIC | quinn | Node Synchronization, Event Streams | node.stream_events |
| WebSocket | tokio-tungstenite | Real-time Chat & A2UI Patches | /console/v1/stream |
QUIC & mTLS Transport
Thepalyra-transport-quic crate provides a hardened wrapper around the quinn library, specifically tailored for the palyrad node architecture. It enforces palyra-quic-v1 as the ALPN protocol crates/palyra-transport-quic/src/lib.rs#14-14 and utilizes rustls for mandatory mutual TLS (mTLS) in node-to-node contexts.
The QuicRuntime handles:
- Connection Limiting: Uses a
tokio::sync::Semaphoreto enforceMAX_CONCURRENT_CONNECTIONS(default 256) crates/palyra-daemon/src/quic_runtime.rs#16-102. - Multiplexed Streams: Supports bi-directional streams for health checks (
node.health) and event propagation (node.stream_events) crates/palyra-daemon/src/quic_runtime.rs#13-14. - Framing: Implements a frame-based protocol with a default limit of 512KB per frame to prevent head-of-line blocking on large payloads crates/palyra-transport-quic/src/lib.rs#13-13.
Node Runtime & Control Plane
Palyra nodes are managed via a dedicated Control Plane that orchestrates enrollment and inventory. Communication in this plane is governed bypalyra-identity, which manages the lifecycle of Ed25519 keypairs and X.509 certificates used for mTLS crates/palyra-identity/src/lib.rs#10-25.
Key components include:
- Identity Manager: Handles certificate rotation and revocation checks via
RevocationIndexcrates/palyra-identity/src/mtls.rs#23-25. - Pairing Handshake: A TOFU (Trust On First Use) mechanism for enrolling new devices and nodes into the daemon’s trust domain crates/palyra-identity/src/lib.rs#18-22.
- Node RPC: A specialized gRPC interface for remote tool execution and resource monitoring.
HTTP & gRPC Services
The daemon integrates several protocol-specific crates to handle operator and integration traffic:- Axum (HTTP): Serves the Admin API and handles OpenAI-compatible completions. It includes middleware for security headers and session management crates/palyra-daemon/Cargo.toml#15-15.
- Tonic (gRPC): Implements the
AgentControlProtocol(ACP) used by the CLI and thebrowser.protoservices used bypalyra-browserdcrates/palyra-daemon/Cargo.toml#49-50. - Tokio-Tungstenite (WS): Powers the real-time update stream for the Web Console, allowing the daemon to push
A2UIpatches to the frontend Cargo.toml#70-70.