vm-control/docs/NODE_AGENT_CONTRACT.md

Node Agent Contract

This document defines the API contract between VaultMesh Node Agents and the Command Center.

Heartbeat Endpoint

Request

POST /api/agent/heartbeat
Content-Type: application/json

Heartbeat Schema

{
  "node_id": "UUID v4",
  "hostname": "string",
  "os_profile": "string",
  "cloudflare_ok": "boolean",
  "services_ok": "boolean",
  "vaultmesh_root": "string",
  "timestamp": "ISO 8601 / RFC 3339"
}

Field Definitions

Field	Type	Description
node_id	UUID v4	Unique identifier for this node. Should persist across reboots.
hostname	String	System hostname (from hostname::get() or /etc/hostname)
os_profile	String	VaultMesh profile name: ArchVault, DebianVault, etc.
cloudflare_ok	Boolean	true if cloudflared service is active
services_ok	Boolean	true if VAULTMESH_ROOT exists and is healthy
vaultmesh_root	String	Path to VAULTMESH_ROOT (e.g., /var/lib/vaultmesh)
timestamp	RFC 3339	UTC timestamp when heartbeat was generated

Response

Success (200 OK):

{
  "status": "ok"
}

Error (4xx/5xx):

{
  "error": "description"
}

Environment Variables

The node agent is configured via environment variables, typically set in /etc/vaultmesh/agent.env.

Variable	Required	Default	Description
VAULTMESH_NODE_ID	No	Auto-generated UUID v4	Persistent node identifier
VAULTMESH_CC_URL	No	http://127.0.0.1:8088	Command Center base URL
VAULTMESH_OS_PROFILE	No	ArchVault	OS profile name to report
VAULTMESH_ROOT	No	/var/lib/vaultmesh	Path to check for services_ok
VAULTMESH_HEARTBEAT_SECS	No	30	Seconds between heartbeats
RUST_LOG	No	info	Log level (trace, debug, info, warn, error)

Example /etc/vaultmesh/agent.env

VAULTMESH_NODE_ID=550e8400-e29b-41d4-a716-446655440000
VAULTMESH_CC_URL=https://cc.vaultmesh.example
VAULTMESH_OS_PROFILE=ArchVault
VAULTMESH_ROOT=/var/lib/vaultmesh
VAULTMESH_HEARTBEAT_SECS=30
RUST_LOG=info

Node Registration

Nodes self-register on first heartbeat. There is no explicit registration endpoint.

When the Command Center receives a heartbeat with a new node_id, it creates a new entry. Subsequent heartbeats update the existing entry.

Node ID Persistence

For consistent tracking, the VAULTMESH_NODE_ID should be persisted. Options:

1. Environment file: Set in /etc/vaultmesh/agent.env
2. Machine ID: Could derive from /etc/machine-id
3. Auto-generated: If not set, agent generates a new UUID on each start (not recommended for production)

Recommended: Generate a UUID once during node bootstrap and store in agent.env:

# During node bootstrap
echo "VAULTMESH_NODE_ID=$(uuidgen)" >> /etc/vaultmesh/agent.env

Health Checks

cloudflare_ok

The agent runs:

systemctl is-active --quiet cloudflared

Returns true if exit code is 0 (service active).

services_ok

The agent checks if VAULTMESH_ROOT exists and is a directory:

std::path::Path::new(vaultmesh_root).is_dir()

Future versions may add additional checks:

• Disk space
• Key services running
• ProofChain integrity

Error Handling

Network Errors

If the agent cannot reach the Command Center:

• Log error at WARN/ERROR level
• Sleep for heartbeat interval
• Retry on next cycle

No exponential backoff in V1. The agent will retry every VAULTMESH_HEARTBEAT_SECS seconds indefinitely.

Invalid Response

If CC returns non-2xx status:

• Log warning with status code
• Continue normal operation
• Retry on next cycle

Security Considerations

Transport Security

• Agent should connect to CC via HTTPS (Cloudflare Tunnel)
• reqwest configured with rustls-tls (no OpenSSL dependency)

Authentication (Future)

V1 has no agent authentication. Future versions may add:

• Signed JWTs
• Shared secrets
• mTLS

Data Sensitivity

Heartbeat data is low-sensitivity:

• No secrets or credentials
• No PII
• No file contents

The vaultmesh_root path and hostname are the most identifying fields.