palyrad manages the entry points for all external and internal communications. It provides a multi-stack interface consisting of an Axum-based HTTP router for the web dashboard and administrative tools, and a Tonic-based gRPC server for high-performance agent communication, node synchronization, and browser automation control.
System Architecture
The transport layer is initialized during the daemon bootstrap process, where it binds to specific sockets defined in theLoadedConfig. It bridges the “Code Entity Space” of internal services (like GatewayRuntimeState) to the “Natural Language Space” of network protocols.
Transport Layer Overview
This diagram illustrates how external requests flow through the transport components into the core logic. Sources: crates/palyra-daemon/src/transport/http/router.rs#17-133, crates/palyra-daemon/src/app/runtime.rs#42-84, crates/palyra-daemon/src/lib.rs#162-164Axum HTTP Router
The HTTP router is constructed viabuild_router and is divided into several logical namespaces. Each namespace has specific security requirements and middleware chains.
Route Namespaces
| Namespace | Base Path | Purpose |
|---|---|---|
| Admin | /admin/v1/* | System-level diagnostics, journal inspection, and channel management. |
| Console | /console/v1/* | Backend for the React-based Web Dashboard (Agents, Chat, Config). |
| Canvas | /canvas/v1/* | Rendering surface for agent-to-UI (A2UI) artifacts. |
| Compat | /compat/v1/* | OpenAI-compatible API surface for external LLM clients. |
| Web UI | /* | Static asset serving for the built Web Dashboard. |
HTTP Middleware and Security
The HTTP stack implements several layers of protection:- Security Headers:
apply_admin_console_security_headersenforcesno-store,nosniff, andframe-ancestors 'none'to prevent clickjacking and caching of sensitive data crates/palyra-daemon/src/transport/http/middleware.rs#37-52. - Rate Limiting:
admin_rate_limit_middlewareuses an IP-based bucket system (AdminRateLimitEntry) to prevent brute-force attacks on administrative endpoints crates/palyra-daemon/src/transport/http/middleware.rs#172-204. - CSRF & Session: Console routes use
console_session_cookie_refresh_middlewareto manageSET_COOKIEheaders and validateConsoleSessionobjects stored inAppStatecrates/palyra-daemon/src/transport/http/middleware.rs#87-107.
gRPC Services
The daemon exposes Protobuf-defined services via Tonic. These are used for low-latency, bi-directional streaming (e.g.,RunStream) and secure node-to-node communication.
Key Services
- GatewayService: The primary interface for agents to interact with the orchestration engine.
- NodeService: Manages multi-node synchronization and pairing crates/palyra-daemon/src/lib.rs#21-22.
- BrowserService: Provides the interface for controlling headless browser automation crates/palyra-daemon/src/app/runtime.rs#86-98.
Authentication Flow
Every gRPC request is intercepted to extract aRequestContext. The authorize_headers function validates the palyra-principal, palyra-device-id, and optional palyra-admin-token against the GatewayAuthConfig crates/palyra-daemon/src/lib.rs#162-164.
ControlPlaneClient
TheControlPlaneClient (defined in palyra-control-plane) is the primary consumer of the HTTP API, used by the CLI and Desktop applications to interact with the daemon.
Client Implementation Details
The client manages the lifecycle of the session, including the CSRF token and cookie store.- Session Management:
get_session()callsconsole/v1/auth/sessionto initialize thecsrf_tokencrates/palyra-control-plane/src/client.rs#67-73. - Browser Handoff:
create_browser_handoff()allows the Desktop app to generate a short-lived token that logs the user into the web dashboard automatically crates/palyra-control-plane/src/client.rs#85-91. - Request Retries: Implements
safe_read_retriesfor GET requests to handle transient network issues crates/palyra-control-plane/src/client.rs#15-19.
Data Flow: Web Console Authentication
The following diagram maps the authentication flow from the React UI components to the Rust backend handlers.Key Entities in Auth Flow
ConsoleAuthScreen: The UI component for manual login apps/web/src/console/components/layout/ConsoleAuthScreen.tsx#16-22.console_login_handler: Validates the admin token and principal, then issues a session crates/palyra-daemon/src/transport/http/handlers/console/auth.rs#19-111.ConsoleSession: A struct containing the hashed session token andRequestContextcrates/palyra-daemon/src/app/state.rs#154-160.issue_console_session: Generates the cryptographically secure tokens crates/palyra-daemon/src/transport/http/handlers/console/auth.rs#101.