palyrad) exposes three distinct network interfaces to facilitate communication between the core orchestration engine, user interfaces, remote execution nodes, and third-party integrations. These interfaces are built on a mix of REST/HTTP for management, gRPC over HTTP/2 for structured service calls, and mTLS-secured RPC over QUIC for distributed node operations.
Network Interface Overview
The transport layer is primarily defined within thepalyra-daemon crate under the transport module crates/palyra-daemon/src/lib.rs#34. It manages the lifecycle of the Axum-based HTTP server and the Tonic-based gRPC server.
| Interface | Protocol | Primary Purpose | Security |
|---|---|---|---|
| Admin/Console API | HTTP/1.1 & 2 | Web Dashboard, CLI management, Canvas UI. | Session Cookies, API Tokens, CSRF protection. |
| Gateway gRPC | gRPC (HTTP/2) | Structured agent interaction, streaming runs. | Static Auth Tokens, mTLS (optional). |
| Node RPC | RPC over QUIC | Remote node orchestration, skill execution. | mTLS (Device Identity), TOFU pairing. |
Transport Architecture
The following diagram illustrates how incoming requests are routed through the various transport handlers to the centralAppState.
Diagram: Transport Routing and Code Entities
Sources: crates/palyra-daemon/src/transport/http/router.rs#17-133, crates/palyra-daemon/src/lib.rs#170-182, crates/palyra-daemon/src/app/state.rs#1-100
Admin and Console HTTP API
The HTTP surface is managed viaaxum and is split into several functional namespaces. The build_router function crates/palyra-daemon/src/transport/http/router.rs#17 defines the routing logic for:
- Admin (
/admin/v1/*): Low-level system status, policy explanation, and skill quarantine crates/palyra-daemon/src/transport/http/router.rs#18-125. - Console (
/console/v1/*): High-level operations for the Web UI, including chat, memory management, and agent configuration crates/palyra-daemon/src/transport/http/router.rs#134-180. - Canvas (
/canvas/v1/*): Ephemeral UI state and A2UI (Agent-to-User Interface) patches. - OpenAI Compatibility (
/v1/chat/completions): A bridge for using Palyra as a drop-in replacement for OpenAI-compatible clients.
gRPC Services and Protocol Buffers
Palyra uses gRPC for high-performance, bidirectional streaming between the daemon and its clients (like the CLI). The schemas are defined in.proto files within the schemas/ directory crates/palyra-daemon/src/lib.rs#170-173.
- Gateway Service: The primary entry point for starting “Runs” and receiving event streams.
- Browser Service: Controls the
palyra-browserdinstance for headless automation. - Auth Service: Manages credential exchange and session validation.
QUIC Transport and Node RPC
The Node RPC interface is the backbone of Palyra’s distributed capabilities. It utilizes thepalyra-transport-quic crate, built on top of quinn, to provide a secure, multiplexed connection between the central daemon and remote execution nodes.
- mTLS Security: Every node connection requires a valid
DeviceIdentitycertificate crates/palyra-daemon/src/lib.rs#142-143. - Node Pairing: A Trust-On-First-Use (TOFU) handshake allows new nodes to be authorized by the daemon.
- Task Dispatch: Used for offloading heavy skill execution or browser automation to remote hardware.
Security and Middleware
All transport interfaces are wrapped in layers of security middleware crates/palyra-daemon/src/transport/http/middleware.rs#1:- Rate Limiting:
admin_rate_limit_middlewareprevents brute-force or DoS attacks on the management API crates/palyra-daemon/src/transport/http/middleware.rs#172-204. - Security Headers:
apply_admin_console_security_headersenforces strict CSP, HSTS, and Frame options crates/palyra-daemon/src/transport/http/middleware.rs#37-52. - Observability: Mutations via the console are automatically tracked via
console_observability_middlewarecrates/palyra-daemon/src/transport/http/middleware.rs#54-85.