Node Runtime Architecture
TheNodeRuntimeState acts as the central orchestrator within the daemon for managing remote device lifecycles, pairing requests, and capability dispatching crates/palyra-daemon/src/node_runtime.rs#208-213. It maintains a registry of RegisteredNodeRecord entities representing active and historical node connections crates/palyra-daemon/src/node_runtime.rs#131-139.
Data Flow: Capability Invocation
When a tool or skill requires a node-hosted capability, the following flow occurs:- Queueing: A
CapabilityDispatchRecordis created and added to thequeued_by_devicemap crates/palyra-daemon/src/node_runtime.rs#198-199. - Polling/Streaming: The remote node, connected via
NodeServiceClient, receives the request through theRegisterNodestream or a poll mechanism crates/palyra-cli/src/commands/node.rs#207-215. - Execution: The node executes the local logic (e.g.,
desktop.open_url) and returns aLocalCapabilityResultcrates/palyra-cli/src/commands/node.rs#107-111. - Completion: The daemon receives the result, resolves the waiting
oneshot::Sender, and updates theCapabilityRequestRecordstate toSucceededorFailedcrates/palyra-daemon/src/node_runtime.rs#181-194.
Node Host Process
Thepalyra node CLI command manages a background host process that handles the connection to the daemon. It stores configuration in node-host.json and tracks process metadata in node-host-process.json crates/palyra-cli/src/commands/node.rs#31-37.
Sources: crates/palyra-daemon/src/node_runtime.rs#1-213, crates/palyra-cli/src/commands/node.rs#1-215
QUIC Transport Layer
Palyra utilizes a custom QUIC transport implementation for high-performance, multiplexed communication between nodes and the daemon. This layer is built on top of thequinn library and enforces rustls-based security.
Protocol Specification
- Protocol Version: 1 crates/palyra-transport-quic/src/lib.rs#12.
- ALPN:
palyra-quic-v1crates/palyra-transport-quic/src/lib.rs#14. - Framing: Data is exchanged in length-prefixed frames with a default maximum size of 512KB crates/palyra-transport-quic/src/lib.rs#13.
QUIC Runtime Server
TheQuicRuntime in the daemon manages the lifecycle of QUIC connections. It implements a connection semaphore to limit global concurrency to 256 simultaneous connections crates/palyra-daemon/src/quic_runtime.rs#16-91.
| Method | Description |
|---|---|
node.health | Returns the health status of the node and whether mTLS is required crates/palyra-daemon/src/quic_runtime.rs#166-179. |
node.stream_events | Initiates a unidirectional stream of events from the daemon to the node crates/palyra-daemon/src/quic_runtime.rs#180-197. |
Transport Configuration
TheQuicTransportLimits struct defines the operational parameters for the QUIC stack, including a 10-second handshake timeout and a 30-second idle timeout crates/palyra-transport-quic/src/lib.rs#17-35.
Sources: crates/palyra-transport-quic/src/lib.rs#1-118, crates/palyra-daemon/src/quic_runtime.rs#1-122
Node Enrollment and Pairing
Nodes must undergo a secure pairing handshake before they can invoke capabilities. This process establishes the mTLS identity used for subsequent RPC calls.Pairing Flow
- Initiation: A
PairingSessionis started via theIdentityManagercrates/palyra-identity/src/pairing.rs#121-132. - Challenge/Response: The node provides a PIN or QR token. The daemon validates this against
active_pairing_codescrates/palyra-daemon/src/node_runtime.rs#144-151. - Material Issuance: Upon successful verification, the daemon issues an
IssuedCertificatecontaining a client certificate signed by the Gateway CA crates/palyra-identity/src/ca.rs#64-78. - Storage: The node stores this certificate and its private key locally (e.g.,
node-mtls-client.json) to authenticate future requests crates/palyra-cli/src/commands/node.rs#38-72.
Security Enforcement: mTLS
TheNodeRpcServiceImpl enforces certificate-bound device identity. Every gRPC request is inspected for a peer certificate; the SHA256 fingerprint of this certificate must map to a valid device_id in the IdentityManager crates/palyra-daemon/src/node_rpc.rs#56-129.
Node Identity Components
| Component | Responsibility |
|---|---|
IdentityManager | Manages CA operations, pairing sessions, and revocation crates/palyra-identity/src/pairing.rs#18-22. |
RevocationIndex | Tracks revoked certificate fingerprints to block compromised nodes crates/palyra-identity/src/mtls.rs#23-25. |
DeviceIdentity | Represents the Ed25519 keypair and metadata of the remote node crates/palyra-identity/src/device.rs#11-20. |
Implementation Mapping
Node RPC and Runtime Logic
This diagram bridges the RPC service definitions to the internal runtime state management. Sources: crates/palyra-daemon/src/node_rpc.rs#38-129, crates/palyra-daemon/src/node_runtime.rs#196-213QUIC Transport Stack
This diagram illustrates the relationship between the low-level transport crate and the daemon’s runtime. Sources: crates/palyra-transport-quic/src/lib.rs#120-176, crates/palyra-daemon/src/quic_runtime.rs#62-142Capability Registry
Nodes advertise specific capabilities during theregister_node call. The following capabilities are standard in the Palyra CLI node host:
| Capability Name | Description | Local Mediation Required |
|---|---|---|
echo | Connectivity test | No |
system.health | Resource usage and status | No |
system.identity | Device metadata | No |
desktop.open_url | Opens a URL in the default browser | Yes |
desktop.open_path | Opens a file or directory | Yes |