palyrad) exposes a multi-faceted HTTP surface built on the Axum framework. This interface serves as the primary control plane for the Web Console, providing RESTful endpoints for administrative tasks, session management, real-time chat orchestration, and diagnostic reporting. It also includes an OpenAI-compatible adapter to allow standard LLM clients to interface directly with Palyra’s managed model providers.
Server Architecture & Routing
The HTTP server is initialized within the daemon’s transport layer. It utilizes a centralized router that partitions functionality into distinct namespaces:/admin/v1, /console/v1, /canvas/v1, and /v1 (OpenAI compatibility) [crates/palyra-daemon/src/transport/http/router.rs#17-134, crates/palyra-daemon/src/transport/http/router.rs#135-210]().
Data Flow: Request to Handler
The server lifecycle follows a standard pipeline:- Middleware: Requests pass through security headers, rate limiting, and authentication guards [crates/palyra-daemon/src/transport/http/router.rs#127-133]().
- Extraction: Axum extractors pull the
AppState, which contains references to theJournalStore,GatewayRuntimeState, andIdentityManager[crates/palyra-daemon/src/lib.rs#53-62](). - Handler Execution: Logic is delegated to domain-specific modules in
transport::http::handlers. - Response: Results are typically wrapped in JSON envelopes defined in the
palyra-control-planecrate to ensure contract stability for the Web Console [crates/palyra-control-plane/src/models.rs#7-29]().
HTTP Transport Entity Map
This diagram maps the logical HTTP services to their corresponding implementation files and Axum handlers. Title: HTTP Transport Service Mapping Sources: crates/palyra-daemon/src/transport/http/router.rs#17-210, crates/palyra-daemon/src/transport/http/handlers/console/mod.rs#1-30Admin V1 API
The Admin API is intended for low-level system management and observability. It provides direct access to theJournalStore and internal runtime state.
- Status & Health: Endpoints like
/admin/v1/statusreturn high-level daemon health, versioning, and resource utilization [crates/palyra-daemon/src/transport/http/router.rs#19-19](). - Journal Inspection: Allows querying recent events via
/admin/v1/journal/recent[crates/palyra-daemon/src/transport/http/router.rs#20-20](). - Run Management: Administrative control over active agent runs, including status checks (
/admin/v1/runs/{run_id}) and cancellation [crates/palyra-daemon/src/transport/http/router.rs#22-24](). - Channel Operations: Detailed management of connectors (Discord, Slack, etc.), including health refreshes, queue draining, and dead-letter replaying [crates/palyra-daemon/src/transport/http/router.rs#25-69]().
Console V1 API (Control Plane)
The Console API is the backend for the Palyra Web Console (apps/web). It implements the control-plane.v1 contract.
Authentication & Session Management
Palyra uses a session-based approach for the console, secured by CSRF tokens and secure cookies.- Login: The
console_login_handlervalidates the principal (requiring anadmin:*prefix) and issues aConsoleSession[crates/palyra-daemon/src/transport/http/handlers/console/auth.rs#19-111](). - Handoff: For desktop-to-web transitions, the
console_browser_handoff_handlergenerates short-lived tokens to bootstrap a session in a new browser environment [crates/palyra-daemon/src/transport/http/handlers/console/auth.rs#127-159]().
Chat Orchestration
Real-time interaction is handled via the/console/v1/chat/message/stream/{session_id} endpoint.
- Authorization: Validates the console session and principal scope [crates/palyra-daemon/src/transport/http/handlers/console/chat.rs#145-145]().
- Context Assembly: Resolves attachments and builds “parameter deltas” which may include context references or memory recall instructions [crates/palyra-daemon/src/transport/http/handlers/console/chat.rs#154-176]().
- Run Initiation: Generates a new
run_idand spawns a background task to drive theRunStream[crates/palyra-daemon/src/transport/http/handlers/console/chat.rs#182-195](). - Streaming: Returns an
NDJSON(Newline Delimited JSON) stream of events (text chunks, tool calls, approvals) to the frontend [crates/palyra-daemon/src/transport/http/handlers/console/chat.rs#198-210]().
Diagnostics & Self-Healing
The/console/v1/diagnostics endpoint aggregates state from every subsystem to provide a comprehensive system snapshot. It collects:
- Model Provider Status: Active configurations and credential health [crates/palyra-daemon/src/transport/http/handlers/console/diagnostics.rs#11-28]().
- Memory Usage: Retention metrics and maintenance schedules [crates/palyra-daemon/src/transport/http/handlers/console/diagnostics.rs#54-57]().
- Subsystem Snapshots: Browser daemon (
browserd) status, skill/plugin inventories, and webhook diagnostics [crates/palyra-daemon/src/transport/http/handlers/console/diagnostics.rs#37-41]().
Canvas & OpenAI Compatibility
Canvas API
The Canvas API (/canvas/v1) supports the “A2UI” (Agent-to-User Interface) system, allowing agents to render sandboxed React components or interactive documents in the web console. It includes specialized rate limiting to prevent abuse from rendered content [crates/palyra-daemon/src/transport/http/router.rs#213-220]().
OpenAI Compatibility Surface
To support existing tools and CLI utilities, Palyra implements a subset of the OpenAI API:- Chat Completions:
/v1/chat/completionsroutes requests through Palyra’s internal model provider registry, applying configured safety filters and context injection [crates/palyra-daemon/src/transport/http/router.rs#232-234](). - Embeddings:
/v1/embeddingsprovides access to the daemon’s configured embedding models [crates/palyra-daemon/src/transport/http/router.rs#235-235]().