Skip to main content
The Palyra transport layer provides the communication infrastructure for the palyrad daemon. It handles administrative HTTP traffic, gRPC service execution for internal and external clients, and a custom QUIC-based protocol for node-to-node communication. The layer is responsible for routing, authentication, rate limiting, and protocol versioning across all interfaces.

​
HTTP Architecture (Axum)

The HTTP surface is implemented using the axum framework and is partitioned into several functional namespaces. The primary entry point for building the router is build_router in crates/palyra-daemon/src/transport/http/router.rs 17-17.

​
Router Structure

The router is composed of several sub-routers, each serving a specific consumer:
NamespacePurposeKey Handlers
/admin/v1Low-level daemon management, status, and channel control.admin_status_handler, admin_run_cancel_handler 19-24
/console/v1Backend for the React operator dashboard.console_access_snapshot_handler, console_chat_run_handler 135-188
/canvas/v1Real-time agent UI state and tool interaction.canvas_state_handler, canvas_token_verify_handler 381-395
/v1 (OpenAI)Compatibility layer for OpenAI-compliant LLM clients.compat_chat_completions_handler, compat_models_handler 420-435
/* (Web UI)Serves the static assets for the React dashboard.web_ui_entry_handler 16-16

​
Web UI Asset Serving

The daemon serves the operator dashboard directly. The web_ui_entry_handler resolves the root directory by checking the PALYRA_WEB_DIST_DIR environment variable or searching relative to the executable path 125-148. It includes a fallback missing_web_ui_response that renders a diagnostic page if assets are not found 36-111. Sources:
  • crates/palyra-daemon/src/transport/http/router.rs:17-450()
  • crates/palyra-daemon/src/transport/http/handlers/web_ui.rs:16-148()

​
gRPC Services and Protocol Stubs

Palyra uses gRPC for high-performance, typed communication between the CLI, the daemon, and the browser automation service (palyra-browserd).

​
Service Definitions

The services are defined in Protobuf and generated into multiple languages (Rust, Kotlin, Swift) via scripts/protocol/generate-stubs.sh 1-1.
  • GatewayService: Core daemon operations (Runs, Approvals, Vault).
  • BrowserService: Headless browser control (Navigate, Click, Screenshot) 126-150.
  • AuthService: Profile and credential management 52-58.

​
Data Flow: gRPC to Code Entities

The following diagram illustrates how a gRPC request is handled by the transport layer and mapped to the AppState. Title: gRPC Request Flow and State Mapping Sources:
  • schemas/generated/rust/protocol_stubs.rs:1-200()
  • crates/palyra-daemon/src/app/state.rs:29-59()
  • crates/palyra-daemon/src/lib.rs:163-165()

​
QUIC Transport for Node Communication

The daemon implements a QUIC-based transport for secure, multiplexed communication between Palyra nodes. This is primarily used for streaming events and health checks where mTLS is required.

​
Implementation Details

The QUIC runtime is managed in crates/palyra-daemon/src/quic_runtime.rs. It uses the quinn crate and enforces a global concurrency limit of 256 connections 16-16.
  • TLS Material: Requires a CA certificate, server certificate, and private key. It supports mandatory client authentication (mTLS) 19-25.
  • Frame Protocol: Uses a frame-based approach via read_frame and write_frame from the palyra-transport-quic crate 4-7.
  • Methods:
    • node.health: Verifies node connectivity and mTLS status 166-179.
    • node.stream_events: Provides a multiplexed stream of system events 180-197.
Sources:
  • crates/palyra-daemon/src/quic_runtime.rs:13-197()
  • crates/palyra-daemon/src/app/runtime.rs:100-118()

​
Middleware and Security

The transport layer applies multiple layers of middleware to ensure security and stability.

​
HTTP Middleware Stack

As defined in router.rs, the following layers are applied:
  1. Rate Limiting: admin_rate_limit_middleware and compat_api_rate_limit_middleware use IP-based and token-based tracking in AppState 129-130, 441-444.
  2. Security Headers: admin_console_security_headers_middleware injects CSP and HSTS headers 131-133.
  3. Body Limits: Enforced via DefaultBodyLimit::max(HTTP_MAX_REQUEST_BODY_BYTES) 126-126.

​
Authentication and Context

For gRPC and Console HTTP requests, the system extracts a RequestContext containing:
  • Principal: The identity of the caller.
  • Device ID: Unique identifier for the source device.
  • Channel: Optional source channel (e.g., Discord) 78-83.
Title: HTTP Middleware and Handler Association Sources:
  • crates/palyra-daemon/src/transport/http/router.rs:126-133()
  • crates/palyra-daemon/src/app/state.rs:78-83()
  • crates/palyra-daemon/src/app/runtime.rs:62-66()

​
Cross-Language Support

To facilitate the development of clients in different ecosystems, the transport layer’s contracts are exported as stubs.
LanguageFile PathUsage
Rustschemas/generated/rust/protocol_stubs.rsUsed by palyrad and palyra-cli.
Kotlinschemas/generated/kotlin/ProtocolStubs.ktUsed by Android or JVM-based integrations.
Swiftschemas/generated/swift/ProtocolStubs.swiftUsed by the macOS desktop application.
Sources:
  • schemas/generated/kotlin/ProtocolStubs.kt:4-126()
  • schemas/generated/swift/ProtocolStubs.swift:3-250()