Skip to main content
The HTTP Transport Layer in palyrad provides the primary web-based interface for management, agent interaction, and system diagnostics. Built on the Axum framework, it organizes functionality into distinct route groups catering to different consumers: the React-based Web Console, administrative CLI tools, and OpenAI-compatible API clients.

​
AppState and Router Construction

The HTTP server is initialized by building an AppState which acts as the shared context for all request handlers. This state holds references to core subsystems like the GatewayRuntimeState, JournalStore, and IdentityManager crates/palyra-daemon/src/app/runtime.rs#42-83. The router is constructed in build_router, which partitions the API into four major namespaces crates/palyra-daemon/src/transport/http/router.rs#17-150:
Route GroupBase PathPurpose
Admin API/admin/v1/Low-level system management, channel debugging, and skill quarantine.
Console API/console/v1/Backs the Web UI; handles sessions, chat, and resource management.
Canvas API/canvas/v1/Specialized endpoints for A2UI (Agent-to-User Interface) interactive components.
Compat API/v1/OpenAI-compatible surface for chat completions and model listing.

​
System Flow: Request to Handler

The following diagram illustrates how an inbound HTTP request is routed through middleware to the specific domain logic. HTTP Request Dispatch Flow Sources: crates/palyra-daemon/src/transport/http/router.rs#17-150, crates/palyra-daemon/src/app/runtime.rs#42-83

​
Route Groups and Handlers

​
Admin API (/admin/v1/)

The Admin API is used primarily for system-level introspection and recovery. Key handlers include:

​
Console API (/console/v1/)

This group supports the apps/web frontend. It is heavily focused on session-based operations:

​
OpenAI Compatibility Layer (/v1/)

Palyra implements a subset of the OpenAI API to allow existing tools to connect seamlessly. Sources: crates/palyra-daemon/src/transport/http/router.rs#18-134, crates/palyra-daemon/src/transport/http/handlers/console/agents.rs#44-147, crates/palyra-daemon/src/transport/http/handlers/compat.rs#128-175

​
Middleware and Security

The transport layer enforces several security and resource constraints via Axum middleware:
  1. Rate Limiting: Separate buckets are maintained in AppState for Admin, Canvas, and Compat APIs. Limits are enforced per IP address or per API token crates/palyra-daemon/src/app/runtime.rs#62-66.
  2. CSRF & Session Cookies: The Console API uses authorize_console_session to validate session cookies and CSRF tokens for state-changing (POST/PUT) requests crates/palyra-daemon/src/transport/http/handlers/console/diagnostics.rs#10-11.
  3. Security Headers: The admin_console_security_headers_middleware injects Content-Security-Policy, X-Frame-Options, and Strict-Transport-Security to protect the Web UI crates/palyra-daemon/src/transport/http/router.rs#131-133.
  4. Body Limits: A global HTTP_MAX_REQUEST_BODY_BYTES is enforced to prevent DoS via large payloads crates/palyra-daemon/src/transport/http/router.rs#126.
Sources: crates/palyra-daemon/src/transport/http/router.rs#126-133, crates/palyra-daemon/src/app/runtime.rs#62-66

​
Web UI Serving

The daemon includes a built-in handler for serving the React dashboard (apps/web). The web_ui_entry_handler resolves assets from the local filesystem or an environment-specified directory crates/palyra-daemon/src/transport/http/handlers/web_ui.rs#16-34. Code Entity Association: Transport to State Sources: crates/palyra-daemon/src/app/runtime.rs#42-83, crates/palyra-daemon/src/transport/http/router.rs#17-150, crates/palyra-control-plane/src/client.rs#40-91

​
Control Plane Client

The palyra-control-plane crate provides a Rust-native ControlPlaneClient used by the CLI and desktop app to interact with the HTTP API. It manages: Sources: crates/palyra-control-plane/src/client.rs#33-83, crates/palyra-control-plane/src/models.rs#177-190