palyrad) and remote nodes (typically managed via palyra node CLI commands). The system tracks an inventory of registered devices and instances, facilitating remote tool execution through a capability-based dispatch model.
Architecture Overview
The node system is split between the Node Runtime (state management and persistence) and the Node RPC Service (the gRPC interface).Core Components
| Component | Responsibility | File Reference |
|---|---|---|
NodeRuntimeState | Manages persistence of registered nodes, active pairing codes, and in-flight capability requests. | crates/palyra-daemon/src/node_runtime.rs#177-182 |
NodeRpcServiceImpl | Implements the NodeService Protobuf contract, handling registration and event streaming. | crates/palyra-daemon/src/node_rpc.rs#38-43 |
InventoryDeviceRecord | Represents a physical or virtual device in the persistent inventory. | crates/palyra-daemon/src/node_runtime.rs#130-138 |
CapabilityDispatch | Handles the queuing and execution of remote tasks (capabilities) on specific nodes. | crates/palyra-daemon/src/node_runtime.rs#151-156 |
Node Connectivity & mTLS
Security is enforced via mandatory mTLS. TheNodeRpcServiceImpl extracts the client certificate fingerprint from the gRPC TlsConnectInfo and validates it against the IdentityManager to ensure the device is paired and not revoked crates/palyra-daemon/src/node_rpc.rs#56-97.
System Data Flow: Capability Execution
The following diagram illustrates the flow from a tool invocation to remote execution on a Node. Node Capability Dispatch Flow Sources: crates/palyra-daemon/src/node_runtime.rs#151-170, crates/palyra-daemon/src/node_rpc.rs#35-54Node Inventory & Registration
Nodes must register with the daemon to be considered “available” for capability dispatch. The registration includes platform metadata and a list of supported capabilities (e.g.,shell.execute, filesystem.read).
Data Structures
ThePersistedNodeRuntimeState is stored in node-runtime.v1.json crates/palyra-daemon/src/node_runtime.rs#19-22 and tracks:
- Active Pairing Codes: Temporary PIN or QR codes used for TOFU (Trust On First Use) pairing crates/palyra-daemon/src/node_runtime.rs#48-54.
- Registered Nodes: Known devices, their platforms, and last-seen timestamps crates/palyra-daemon/src/node_runtime.rs#130-138.
- Pairing Requests: The history of device pairing attempts and their approval status crates/palyra-daemon/src/node_runtime.rs#106-121.
CLI Node Management
Thepalyra node command group in palyra-cli manages the local node lifecycle, including installation as a background process and pairing with a daemon.
Key CLI Commands
run: Runs a node in the foreground, performing auto-pairing if necessary crates/palyra-cli/src/commands/node.rs#120-134.install: Configures the node and optionally starts it as a background process crates/palyra-cli/src/commands/node.rs#139-161.status: Reports the current node configuration, PID, and certificate expiry crates/palyra-cli/src/commands/node.rs#135-138.
Node Host Configuration
The CLI maintains a localnode-host.json file containing the device_id, grpc_url, and paths to the identity store crates/palyra-cli/src/commands/node.rs#48-56.
Implementation Details: NodeRpcServiceImpl
The gRPC service implementation handles the complexity of mapping mTLS identities to logical devices.
Certificate Enforcement
Theenforce_cert_bound_device function is the primary security gate for node operations. It ensures that the device_id provided in the gRPC request matches the device_id bound to the client’s mTLS certificate fingerprint crates/palyra-daemon/src/node_rpc.rs#99-129.
Pairing Approval Flow
When a new node attempts to pair via a PIN code, the RPC service creates anApprovalCreateRequest crates/palyra-daemon/src/node_rpc.rs#187-200. This triggers a human-in-the-loop approval in the Palyra Console. Only after the ApprovalSubjectType::Pairing is approved can the node complete the handshake and receive its mTLS credentials.
Pairing State Machine
| State | Description |
|---|---|
PendingApproval | Node has submitted a hello with a valid PIN, waiting for administrator approval. |
Approved | Administrator has approved the pairing; node can now fetch its certificate. |
Completed | Handshake finished; node is fully registered. |
Rejected | Administrator denied the pairing request. |