palyrad) acts as the orchestrator, the Node Runtime allows external devices (Nodes) to enroll, maintain a heartbeat, and execute specialized capabilities (e.g., system health checks, opening URLs) on behalf of the daemon.
Node Runtime Implementation
TheNodeRuntimeState manages the lifecycle of remote nodes, including their enrollment (pairing), heartbeats, and the dispatching of capability requests.
Key Components
NodeRuntimeState: The central coordinator for node metadata and in-flight capability requests. It persists state tonode-runtime.v1.jsoncrates/palyra-daemon/src/node_runtime.rs#20-20.RegisteredNodeRecord: Tracks a node’s platform, capabilities, and “last seen” timestamps crates/palyra-daemon/src/node_runtime.rs#131-139.CapabilityDispatchRecord: Represents a specific task (e.g.,desktop.open_url) sent to a node for execution crates/palyra-daemon/src/node_runtime.rs#154-159.
Data Flow: Capability Dispatch
When the daemon needs a node to perform an action, it uses a mailbox-style dispatch system:- The request is queued in
CapabilityRuntimeStatecrates/palyra-daemon/src/node_runtime.rs#197-201. - The Node, via its long-polling or streaming RPC connection, receives the
CapabilityDispatchRecord. - The Node executes the task and returns a
CapabilityExecutionResultcrates/palyra-daemon/src/node_runtime.rs#162-166.
Node RPC Service
TheNodeRpcServiceImpl provides the gRPC interface defined in node.proto. It handles the low-level communication between the daemon and remote nodes.
Security & mTLS
The RPC layer enforces strict identity verification:peer_certificate_fingerprint: Extracts the SHA-256 fingerprint from the mTLS certificate crates/palyra-daemon/src/node_rpc.rs#56-97.enforce_cert_bound_device: Ensures thedevice_idprovided in the request matches the identity bound to the mTLS certificate crates/palyra-daemon/src/node_rpc.rs#99-129.
Primary RPC Methods
RegisterNode: Nodes call this to announce their presence and capabilities crates/palyra-cli/src/commands/node.rs#207-213.Events: A server-side streaming endpoint where the daemon pushes capability requests to the node crates/palyra-daemon/src/node_rpc.rs#247-260.
Node Host Sidecar
Thepalyra node CLI command implements the Node Host, a sidecar process that runs on the target machine.
Lifecycle Management
The Node Host supports several operational modes:run: Runs the node in the foreground crates/palyra-cli/src/commands/node.rs#134-148.install: Sets up the configuration and pairing material crates/palyra-cli/src/commands/node.rs#153-175.start/stop/restart: Manages the node as a background process crates/palyra-cli/src/commands/node.rs#176-182.
Built-in Capabilities
Nodes come with a set of standard capabilities defined inNODE_CAPABILITY_DESCRIPTORS crates/palyra-cli/src/commands/node.rs#119-125:
echo: Connectivity test.system.health: Resource usage and uptime.desktop.open_url: Requires local mediation (user approval on the node side).
Control Plane Client
Thepalyra-control-plane crate provides the ControlPlaneClient, which is used by the Web Console and CLI to interact with the daemon’s Admin API.
Contract & Models
ContractDescriptor: Ensures version compatibility between the client and the daemon crates/palyra-control-plane/src/models.rs#62-62.DeploymentPostureSummary: Provides a high-level view of the daemon’s security and network configuration crates/palyra-control-plane/src/models.rs#61-74.
Inventory Management
The Control Plane facilitates “Inventory” management, allowing operators to view all registered devices and their trust states. Inventory Data Flow Sources: apps/web/src/console/hooks/useInventoryDomain.ts#83-110, crates/palyra-daemon/src/transport/http/handlers/console/inventory.rs#14-40, crates/palyra-control-plane/src/client.rs#67-73Enrollment & Pairing
Node enrollment follows a Trust-On-First-Use (TOFU) pattern mediated by a pairing code.- Initiation: The node generates a
DeviceIdentityand requests pairing using aPinorQrmethod crates/palyra-daemon/src/node_runtime.rs#27-30. - Approval: The daemon creates an
ApprovalPromptRecordcrates/palyra-daemon/src/node_rpc.rs#187-210. - Material Exchange: Once approved, the node receives a
DevicePairingMaterialRecordcontaining the mTLS client certificate and the Gateway CA certificate crates/palyra-daemon/src/node_runtime.rs#80-88. - Finalization: The node stores this material in its
identity_store_dirand uses it for all subsequent gRPC calls crates/palyra-cli/src/commands/node.rs#48-53.