4
Architecture
Alphaeus Mote edited this page 2026-10-23 11:52:18 -04:00

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.

flowchart LR
    A["Agent"]
    B["Browser / React console"]
    P["Reverse Proxy :443"]

    A -->|"HTTPS: bootstrap, install"| P
    A <-->|"WSS: NATS session"| P
    B -->|"HTTPS: REST API"| P
    B <-->|"WSS: NATS session"| P

    subgraph Stack ["Private network"]
        UI["React WebUI"]
        API["ASP.NET Core Backend"]
        N["NATS: WebSocket + TCP"]
        DB[("SQLite / Postgres / SQL Server")]
        JS[("JetStream")]
    end

    P -->|"/"| UI
    P -->|"/api/*"| API
    P -->|"/messaging/agent"| N
    P -->|"/messaging/browser"| N

    API <-->|"NATS TCP (internal only)"| N
    API --> DB
    N --- JS

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.