Node Runtime Architecture
TheNodeRuntimeState manages the lifecycle of registered nodes, pairing requests, and the dispatching of capabilities. It persists state to a JSON file defined by NODE_RUNTIME_STATE_FILE_NAME crates/palyra-daemon/src/node_runtime.rs#20-20.
Key Components
- Device Pairing: Handles the multi-step handshake to associate a new node with the daemon using PIN or QR codes crates/palyra-daemon/src/node_runtime.rs#27-30.
- Capability Dispatch: Orchestrates the execution of tools on remote nodes. Requests are queued in
queued_by_deviceand tracked viainflight_by_request_idcrates/palyra-daemon/src/node_runtime.rs#198-199. - Node Registry: Tracks
RegisteredNodeRecordentries, including platform details, available capabilities, and “last seen” heartbeats crates/palyra-daemon/src/node_runtime.rs#131-139.
Capability Execution Flow
When the daemon needs to execute a tool on a node, it uses theCapabilityDispatchRecord crates/palyra-daemon/src/node_runtime.rs#154-159. The runtime uses oneshot channels to bridge the asynchronous gRPC/QUIC stream with the internal tool execution logic crates/palyra-daemon/src/node_runtime.rs#200-200.
| Entity | Role |
|---|---|
NodeRuntimeState | Central coordinator for node metadata and task queues. |
CapabilityRequestRecord | Persisted record of a tool execution attempt and its outcome. |
DeviceCapabilityView | Snapshot of what a specific node is capable of (e.g., desktop.open_url). |
QUIC Transport Layer
Palyra utilizes a custom transport layer built onquinn and rustls to provide a multiplexed, secure alternative to standard gRPC for node-to-daemon communication.
Protocol Framing
The transport uses a frame-based approach where each message is prefixed with its length. The maximum frame size is governed byDEFAULT_MAX_FRAME_BYTES crates/palyra-transport-quic/src/lib.rs.
Connection Lifecycle
- Binding: The server binds to a
SocketAddrusingbuild_server_endpointcrates/palyra-daemon/src/quic_runtime.rs#67-77. - Handshake: Requires TLS material (
QuicRuntimeTlsMaterial) including CA, Certificate, and Private Key crates/palyra-daemon/src/quic_runtime.rs#19-25. - Serving: The
serve_with_connection_limitfunction manages a semaphore-based limit on concurrent connections (default 256) crates/palyra-daemon/src/quic_runtime.rs#86-91.
Supported Methods
The QUIC runtime currently handles:node.health: Basic connectivity check crates/palyra-daemon/src/quic_runtime.rs#13-13.node.stream_events: A stateful stream for pushing updates to nodes crates/palyra-daemon/src/quic_runtime.rs#14-14.
QUIC Transport Data Flow
Node Runtime to Transport mapping: Sources: crates/palyra-daemon/src/quic_runtime.rs#1-142, crates/palyra-daemon/src/node_runtime.rs#181-194.mTLS-Secured Node RPC
While QUIC is used for performance, a gRPC interface (NodeRpcServiceImpl) provides the primary control plane for node registration and pairing, secured by mandatory mTLS.
Identity and Authentication
TheNodeRpcServiceImpl enforces certificate-bound identity. It extracts the client certificate fingerprint and validates it against the IdentityManager crates/palyra-daemon/src/node_rpc.rs#56-85.
- Revocation: Fingerprints are checked against a revocation list; if a certificate is revoked, the request is denied crates/palyra-daemon/src/node_rpc.rs#91-95.
- Device Binding: The
enforce_cert_bound_devicefunction ensures that thedevice_idin the request matches the identity associated with the mTLS certificate crates/palyra-daemon/src/node_rpc.rs#99-129.
Node RPC Implementation
The service implements thenode.v1 Protobuf schema, handling:
register_node: Updates the node’s last-seen status and capabilities crates/palyra-cli/src/commands/node.rs#208-213.poll_capability: Nodes call this to receive pending tool execution tasks crates/palyra-cli/src/commands/node.rs#39-39.
Node to Daemon Interaction
This diagram bridges the CLI node runner to the Daemon’s RPC implementation. Sources: crates/palyra-daemon/src/node_rpc.rs#38-129, crates/palyra-cli/src/commands/node.rs#187-213.Control Plane Client
TheControlPlaneClient is the primary library used by nodes and the CLI to communicate with the daemon’s HTTP/gRPC interfaces.
- Initialization: Configured with a
base_url,request_timeout, andsafe_read_retriescrates/palyra-control-plane/src/client.rs#15-19. - Session Management: Handles CSRF tokens automatically by intercepting
ConsoleSessionobjects during login or session retrieval crates/palyra-control-plane/src/client.rs#67-73. - Transport: Uses
reqwestwith a cookie store enabled to maintain session affinity crates/palyra-control-plane/src/client.rs#42-46.
Key Client Methods
login: Authenticates a console session crates/palyra-control-plane/src/client.rs#75-83.create_browser_session: Initiates browser automation tasks crates/palyra-control-plane/src/client.rs#179-184.list_nodes: Queries registered execution nodes from the daemon.