Architecture
Everything that crosses the edge is HTTP or HTTPS.
Agents and browsers never talk to NATS directly. Their NATS clients speak
WebSocket to the reverse proxy. In standalone mode, the server's own
/messaging/* relay plays that role instead.
NATS TCP (4222) is never published. The edge proxy is the only externally
reachable route.
Message flow
Each party holds a NATS JWT that limits which subjects it may use:
- Agent → NATS — presence every 30 seconds, inventory, job output,
progress, state, shell output
- NATS → Agent — durable commands (script, inventory, file, shell)
through JetStream, acknowledged explicitly
- Backend — consumes agent messages, persists them, republishes
session-scoped events for browsers
- Browser — subscribes to
browser.session.* only; the only thing it
publishes is shell input
How enrollment works
The agent derives a deterministic ClientId from hardware identity.
It generates a User NKey locally — the seed never leaves the device — and
POSTs the bootstrap token. The backend consumes the token, binds the
device, and returns a scoped NATS user JWT.
Reconnects need no token. A device offline past the orphan window simply
re-enrolls with a fresh token and keeps its history.
Deployment shapes
| Shape |
What runs |
| Docker Compose |
EXECUTER-{NATS,API,WEB}-00001 containers on a private bridge, one edge proxy in front |
| Standalone binary / MSI |
One ExecuteR-Server process: static WebUI, API, /messaging/* relay, and a supervised loopback-only nats-server sidecar |
See Installation for both, and Scaling and HA
for the load-balanced, multi-replica topology. Full sequence diagrams live in
docs/sequences.md in the repository.