On-prem agents

The on-prem boundary is outbound-only. An enrolled agent polls the control plane, reports health and executes a small typed command allowlist. No inbound port or arbitrary shell is required.

Enrollment and heartbeat

operator creates one-time token (plaintext shown once)
             |
             v
agent -> POST /agents/enroll: token, host facts, capabilities, public key
             |
             v
server hashes and validates token -> registers agent key + capability set
             |
             v
agent -> heartbeat / poll -> signed command envelope -> signed result

Enrollment tokens are random, hashed at rest, expiring and single-use. The current API allows a token TTL from 5 minutes to 7 days. Heartbeats carry CPU, memory, disk, load, uptime, version, OS, architecture and hostname. Five minutes without a heartbeat causes the worker to mark the node offline and raise an alert.

Command boundary

Command	Risk	Capability / behavior
inspect, metrics, healthcheck	0	Read-only host checks
list	0	Typed target kind such as containers, pods, services or processes
logs	0	Docker capability, max 200 lines
start, stop, restart	2	Typed container, service or VM target
deploy	2	Typed application ID and config object

Parameters are schema-validated, commands are capability-gated against enrollment declarations, and unknown command types are rejected before reaching the host. The agent uses argument-array execution, never a shell string or eval.

Signing and lifecycle

Every envelope is HMAC-SHA256 signed over stable JSON excluding the signature. The server checks the signature and that the agent key belongs to a registered, non-revoked agent. Commands move through QUEUED -> SENT -> ACKNOWLEDGED -> RUNNING -> SUCCEEDED | FAILED | TIMED_OUT; cancellation is immediate before running and cooperative while running. Every command and result is tenant-scoped audit evidence.

Revocation stops new commands. Mutual TLS and Ed25519 identity signatures are roadmap hardening, not current protocol requirements. Demo agent mode can self-approve and use a local JSONL loopback when the control plane is unavailable; that loopback is simulated and is not live agent execution.