palyrad) orchestrates tasks executed by remote nodes over mTLS-secured gRPC channels.
Node Runtime Management
TheNodeRuntimeState is the central coordinator for tracking registered nodes, pending pairing codes, and in-flight capability dispatches. It persists its state to a JSON file named node-runtime.v1.json within the daemon’s state root crates/palyra-daemon/src/node_runtime.rs#19-20.
Key Data Structures
RegisteredNodeRecord: Tracks a node’sdevice_id, platform, reported capabilities, and heartbeat timestamps crates/palyra-daemon/src/node_runtime.rs#130-138.DevicePairingRequestRecord: Captures the state of a pairing attempt, including the associatedapproval_idfrom the journal and the resulting mTLS material crates/palyra-daemon/src/node_runtime.rs#106-121.CapabilityDispatchRecord: Represents a request sent to a node to execute a specific function, including input JSON and payload constraints crates/palyra-daemon/src/node_runtime.rs#151-156.
Capability Dispatch Flow
Capabilities are dispatched to nodes via a queue-based system. When a capability is requested, it is added toCapabilityRuntimeState.queued_by_device crates/palyra-daemon/src/node_runtime.rs#166-170. The node retrieves these tasks via a long-polling or streaming gRPC call, executes them locally, and returns a CapabilityExecutionResult crates/palyra-daemon/src/node_runtime.rs#159-163.
Sources: crates/palyra-daemon/src/node_runtime.rs#177-207
Node RPC Service and Security
TheNodeRpcServiceImpl provides the gRPC interface for nodes to interact with the daemon. It enforces strict security through Mutual TLS (mTLS) and device-to-certificate binding.
mTLS Enforcement and Identity
The service extracts the peer certificate fingerprint from the TLS connection metadata crates/palyra-daemon/src/node_rpc.rs#60-85.- Revocation Check: The fingerprint is checked against the
IdentityManagerto ensure the certificate has not been revoked crates/palyra-daemon/src/node_rpc.rs#91-95. - Device Binding:
enforce_cert_bound_deviceensures that thedevice_idclaimed in the gRPC request matches thedevice_idbound to the client certificate during the pairing process crates/palyra-daemon/src/node_rpc.rs#99-129.
Node Registration
Nodes callRegisterNode to announce their presence and capabilities. The daemon validates the device_id and records the node’s platform and available tools crates/palyra-daemon/src/node_rpc.rs#210-240.
Sources: crates/palyra-daemon/src/node_rpc.rs#38-54, crates/palyra-daemon/src/node_rpc.rs#56-129
mTLS-Enforced Node Pairing
Pairing is the process of establishing a trust relationship between a new node and the daemon. It follows a multi-step handshake that results in the issuance of a client certificate.Pairing Sequence
- Code Minting: An operator generates a PIN or QR code via the console or CLI crates/palyra-daemon/src/node_runtime.rs#240-260.
- Initial Hello: The node sends a
DevicePairingHellocontaining itsdevice_idand a proof derived from the pairing code crates/palyra-daemon/src/node_rpc.rs#250-280. - Approval Workflow: The daemon creates an
ApprovalPromptRecordof typeDevicePairingcrates/palyra-daemon/src/node_rpc.rs#194-205. - Material Issuance: Once approved, the daemon generates a client certificate for the node. The node retrieves this “pairing material” (certificate and CA PEM) to configure its local mTLS transport crates/palyra-daemon/src/node_runtime.rs#79-87.
Node Pairing Flow Diagram
The following diagram illustrates the transition from a pairing code to a secured mTLS connection. Sources: crates/palyra-daemon/src/node_rpc.rs#187-208, crates/palyra-identity/src/pairing/manager.rs#14-39, crates/palyra-daemon/src/node_runtime.rs#79-103Console Inventory and Device Management
The Web Console provides a unified view of all connected hardware and virtual instances through the Inventory Section.Inventory Surface
TheInventorySection in the React frontend aggregates data from multiple daemon endpoints to show:
- Device Presence: Whether a device is “Online”, “Stale”, or “Offline” based on heartbeat age apps/web/src/console/sections/InventorySection.tsx#127-130.
- Trust State: The current validity of the device’s mTLS credentials apps/web/src/console/sections/InventorySection.tsx#128.
- Capabilities: A summary of tools provided by the node crates/palyra-daemon/src/transport/http/handlers/console/inventory.rs#118-122.
Administrative Actions
Operators can perform lifecycle operations on devices:- Rotate: Forces the issuance of a new client certificate crates/palyra-daemon/src/transport/http/handlers/console/devices.rs#35-58.
- Revoke: Immediately invalidates a device’s certificate and adds its fingerprint to the revocation list crates/palyra-daemon/src/transport/http/handlers/console/devices.rs#60-86.
- Remove: Deletes the device record and its pairing history crates/palyra-daemon/src/transport/http/handlers/console/devices.rs#88-127.
CLI Node Commands
Thepalyra CLI includes a node subcommand group for managing local node instances and performing headless pairing.
Primary Commands
node run: Starts a node in the foreground. It automatically handles pairing if a code is provided, then enters a loop to register and process capabilities crates/palyra-cli/src/commands/node.rs#120-134.node install: Configures a node to run as a background process, persisting configuration tonode-host.jsoncrates/palyra-cli/src/commands/node.rs#139-161.node status: Displays the health, PID, and certificate expiration of the locally installed node crates/palyra-cli/src/commands/node.rs#135-138.
Node Lifecycle Implementation
The CLI manages the node process using platform-specific logic. On Windows, it usesDETACHED_PROCESS and CREATE_NO_WINDOW flags to run the node without a terminal window crates/palyra-cli/src/commands/node.rs#42-45. It redirects logs to node-host.stdout.log and node-host.stderr.log for troubleshooting crates/palyra-cli/src/commands/node.rs#36-37.