palyrad) manages remote execution units (Nodes) and provides a unified administrative interface (Control Plane). This system is built on top of mTLS-secured gRPC communication and a capability-based access control model.
Node Runtime and mTLS RPC
Remote nodes connect to the Palyra daemon using a secure handshake process that establishes mutual TLS (mTLS) identities. TheNodeRuntimeState in the daemon manages the lifecycle of these nodes, including their registration, capability discovery, and pairing requests.
Node Connectivity Architecture
The connection between a node and the daemon follows a strict security protocol:- Pairing: A node initiates a pairing request using a PIN or QR code method crates/palyra-daemon/src/node_runtime.rs#24-30.
- Identity: The
palyra-identitycrate manages the Certificate Authority (CA) and issues device-specific certificates crates/palyra-daemon/src/node_runtime.rs#82-87. - RPC: Communication occurs over gRPC (via
node_rpc.rs), where the daemon dispatches capability requests to specific nodes based on their registered capabilities crates/palyra-daemon/src/node_runtime.rs#151-156.
| Logic Component | Code Entity | File Path |
|---|---|---|
| Node State | NodeRuntimeState | crates/palyra-daemon/src/node_runtime.rs#177-182 |
| Pairing Record | DevicePairingRequestRecord | crates/palyra-daemon/src/node_runtime.rs#106-121 |
| Node Registry | RegisteredNodeRecord | crates/palyra-daemon/src/node_runtime.rs#130-138 |
| mTLS Store | FilesystemSecretStore | crates/palyra-identity/src/store.rs#87-92 |
Control Plane Client
Thepalyra-control-plane crate provides the primary programmatic interface for interacting with a Palyra daemon. It abstracts the HTTP/gRPC transport layers and provides a type-safe ControlPlaneClient used by the CLI, Desktop app, and external integrations.
Client Capabilities
TheControlPlaneClient manages:
- Session Management: Handling CSRF tokens and authentication sessions crates/palyra-control-plane/src/client.rs#67-73.
- Resource Orchestration: Managing browser profiles, agents, and secrets crates/palyra-control-plane/src/client.rs#109-115.
- Configuration: Mutating and validating the daemon’s TOML configuration crates/palyra-control-plane/src/models.rs#164-174.
Access Control Registry
TheAccessRegistry is the central authority for permissions within the daemon. It manages feature flags, API tokens, and Role-Based Access Control (RBAC).
- Roles: Defines
Owner,Admin, andOperatorroles with pre-defined permission sets crates/palyra-daemon/src/access_control.rs#76-80. - API Tokens: Supports scoped tokens with rate limiting and expiration crates/palyra-daemon/src/access_control.rs#151-173.
- Feature Flags: Controls access to experimental features like
team_modeorrbaccrates/palyra-daemon/src/access_control.rs#18-22.
Compatibility Layer
The daemon includes a “Compat API” handler that allows external tools to use Palyra via OpenAI-compatible endpoints crates/palyra-daemon/src/transport/http/handlers/compat.rs#128-132. This layer enforcesAccessRegistry permissions (e.g., compat.chat.create) before proxying requests to the internal orchestrator crates/palyra-daemon/src/transport/http/handlers/compat.rs#110-111.
Access Control Mapping
Sources: crates/palyra-daemon/src/access_control.rs#76-80, crates/palyra-daemon/src/access_control.rs#151-173, crates/palyra-daemon/src/access_control.rs#138-148, crates/palyra-daemon/src/access_control.rs#39-72
Node CLI Commands
Thepalyra CLI provides a dedicated command group for managing distributed nodes.
- Pairing: Commands to generate pairing codes or join a daemon as a node.
- Status: Commands to list registered nodes and their current health/capabilities crates/palyra-cli/tests/daemon_status.rs#19-27.
- Auth: Management of authentication profiles and access tokens crates/palyra-cli/src/commands/auth.rs#4-25.