The remote-Commander control channel¶
Executor A's job is to start and drive a Commander — a Claude Code session — on a target box, from off the box. The control channel is how the Hub does that: a narrow, least-verbs surface, bound to loopback, fronted by an authenticating proxy, and gated per box by the capability model.
It is deliberately not a general remote-shell. It exposes exactly the verbs needed to run a Commander's lifecycle, and nothing else is served.
Status
The control surface and the web terminal described here are merged on main but dark behind a default-OFF flag, and are not exposed on any network. Building and testing them against a local loopback stand-in is dev-safe; binding the surface live is an operator-only act, gated on the security reviews described at the end of this page.
Six verbs, each mapped to one tier¶
| Verb | Purpose | Tier | Grant needed on box X |
|---|---|---|---|
| deploy | start a Commander (a Claude Code session) | Spawn | Spawn |
| drive | send a prompt to the Commander | Steer | Steer |
| capture | read the Commander's reply | Read | Read |
| status | read session / agent state | Read | Read |
| stop | stop the Commander session | Kill | Kill |
| reset | kill a wedged Commander and redeploy it fresh | Kill | Kill |
Fleet-wide and destructive verbs are explicitly excluded from this surface — fleet enumeration, a fleet kill-switch, deletes, and any cross-box/multi-target verb are not part of the control channel. The surface is the minimum that proves "the Hub can deploy and drive a Commander on a box," and no more.
Served-layer enforcement¶
The exclusion is not just a config allowlist — it is verified at the served
layer. The acceptance probe enumerates the surface the running host-agent actually
answers and asserts it is exactly {deploy, drive, capture, status, stop, reset}
and nothing beyond. This catches the class of bug where two allowlists drift apart
(one config permits a verb the other forbids); the truth is whatever the process
actually serves, so that is what is tested. An unknown or out-of-profile verb is not
silently proxied — it is refused, fail-closed.
Exposure: loopback + forward-auth + proxy-secret¶
The control surface is bound to loopback on the target box and reached only through an authenticating reverse proxy. Three layers compose on every request, and none is the sole boundary — a request must pass all three, fail-closed:
flowchart LR
C([Caller]) -->|HTTPS| P[Reverse proxy<br/>forward-auth]
P -->|proxy-secret header| L[127.0.0.1<br/>control surface]
L --> G{{gate: role floor<br/>+ per-box grant}}
G --> N[hivemind-agent node]
N --> Cmd[Commander]- Transport proof — a proxy-secret. A root-owned secret header proves the request actually arrived through the proxy, not from another process on the same host. Loopback alone cannot tell the proxy from a local attacker; the secret closes that same-host bypass. (Binding to a private network instead of loopback would not close it — a network bind is reachability, not authentication. That was an explicitly-rejected design.)
- Caller identity — forward-auth. The proxy resolves a verified principal through the estate's SSO before the request reaches a verb. No anonymous caller ever reaches the surface.
- Capability — the per-target gate. The role floor, then the per-(principal, box) standing grant. Deny-by-default; every allow and deny audited.
The proxy-secret is root-owned specifically so that the sandboxed agent user cannot read or forge it — the transport proof is outside the AI's reach.
The Commander lifecycle, concretely¶
- deploy (Spawn grant) — the surface emits a spawn targeting box X; the agent node on the box claims it and runs a persistent Commander. The claim binds the machine identity so the live Commander is box-resolvable for every later gate. The box must have its Claude Code auth ready first, or a deploy produces a dead shell rather than a drivable Commander — provisioned by the web terminal below or a pre-provisioned credential.
- drive (Steer grant) — the prompt is delivered and confirmed landed, not fired blind.
- capture (Read grant) — a mis-correlation-safe read returns the reply, so back-to-back prompts cannot get their answers crossed.
- status (Read grant) — session and agent state via robust idle detection rather than fragile screen-scraping.
- stop (Kill grant) — terminate the Commander session.
- reset (Kill grant) — kill a wedged Commander (for example, one that has exhausted its context) and redeploy a fresh one. The re-claim re-binds the machine identity, so the replacement stays box-resolvable.
Web terminal for live visibility¶
Alongside the programmatic verbs, the operator can watch a Commander live and sign into Claude Code interactively through a read-write browser terminal. The recommended tool is a single-binary web terminal launched with a fixed command that attaches exactly one tmux session — it cannot become a general shell — served over WebSocket-over-HTTPS behind the same forward-auth, admin-only, tenant-isolated, running as the sandboxed agent OS user, with keystrokes audited. The fixed-command constraint is the point: the terminal's least-privilege property comes from it being able to do exactly one thing.
Deploy/enable posture¶
Building the control surface and testing it against a local loopback stand-in (nothing on the network) is dev-safe. Binding it live on a network is a different class of act — a new control surface that starts and drives AI sessions is remote-code-execution-class — and it ships behind a gate that only an operator flips, after a secret-and-vulnerability pre-exposure review and a deep security review of the caller-auth composition and the prompt path into the Commander. See How it is built + verified.