controlclaw 0.0.0-stage → 0.9.4

package/README.md

@@ -1,3 +1,378 @@
-# Temporary Holding Version
+# controlclaw
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Connects a machine that runs OpenClaw to a ControlClaw firewall. After `connect`, OpenClaw's traffic
+goes through the firewall, and the vm-agent lets the firewall manage OpenClaw's models and channels.
+
+```bash
+controlclaw doctor                  # what this machine can do
+# on the firewall: sudo -u controlclaw mitm-agent pair-code --name laptop   → 4F7K-92QD-XM3P
+sudo controlclaw connect --mode host --firewall http://fw.example.com:8801 --vm-agent ./vm-agent
+# Pairing code from the firewall: (type 4F7K-92QD-XM3P; it is not shown)
+controlclaw status
+sudo controlclaw disconnect         # undo all of it
+```
+
+Linux only for now.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `doctor [--json]` | Shows the OS, root access, nftables, Docker, redsocks, DNS, Chrome, WireGuard and the vm-agent. Shows OpenClaw's CLI, version, config and how it runs. Says which modes this machine can do and how much each protects. |
+| `connect --mode docker\|host\|proxy --firewall <url>` | Pairs with the firewall, then installs the vm-agent, the firewall's CA and the capture for the mode, and checks that it works. |
+| `disconnect` | Undoes everything `connect` did and puts back what it changed. |
+| `status [--json]` | Shows whether the capture, the vm-agent, and the firewall's proxy and DNS are up. Exits 1 if one is not. |
+
+Options for `connect`:
+
+| Option | Default | What it is |
+| --- | --- | --- |
+| `--firewall <url>` | | The firewall's pairing address, such as `http://fw.example.com:8801`. Its host is also the last default for `--proxy` and `--dns`. |
+| (asked) | | The one-time code from the firewall (`mitm-agent pair-code`), typed when `connect` asks. It brings the firewall's CA and key, and the agent's id. |
+| `--code -` / `--code-file <file>` | | The code from stdin, or from a file (keep it 0600). `--code <code>` is refused: every user of the machine can read a command line. |
+| `--name <name>` | this machine's hostname | The agent's name on the firewall, when the code has none (`pair-code --name` wins). |
+| `--ca <file>` | | Without a code: the firewall's CA certificate (PEM). The firewall re-signs HTTPS with it. |
+| `--firewall-key <pem>` | none | Without a code: the firewall's public key, as a file or the PEM itself. Without it the vm-agent answers nothing. |
+| `--proxy <host:port>` | what pairing says, else the firewall's host, port 8080 | The firewall's proxy. |
+| `--dns <ip>` | what pairing says, else the firewall's host | The firewall's DNS server (host and docker modes). |
+| `--user <name>` | found | The user OpenClaw runs as. By default the CLI uses the owner of the running gateway, or else the one user with `~/.openclaw/openclaw.json`. |
+| `--vm-agent <path>` | `$CC_VM_AGENT`, then PATH | The vm-agent binary. There is no release to download yet. |
+
+## Pairing
+
+On the firewall, as its user, make a code for one machine:
+
+```bash
+sudo -u controlclaw mitm-agent pair-code --name laptop      # or: docker compose exec -u controlclaw firewall mitm-agent pair-code
+```
+
+It prints a code such as `4F7K-92QD-XM3P`. It works once, within 10 minutes (`--ttl` up to 60).
+At most 20 codes wait at a time. The admin API makes them too (`POST /api/pairing/codes`).
+
+What only the admin decides, on the code:
+- `--address <ip>`: the address the proxy will see the machine at, when it is not the one pairing
+  comes from (a NAT, a container on the firewall's machine). Without it, the agent's address is the
+  one its request comes from, and that must be the address the machine says it has.
+- `--replace`: the machine may take the place of an agent already at its address. Without it,
+  pairing at an address that has an agent is refused.
+
+`connect` checks first that the machine can do the mode, so a code is not spent on a machine
+that cannot. Then it pairs:
+- it makes the vm-agent's key pair;
+- it sends the public half to the firewall's `/pair` (port 8801);
+- the firewall records the agent (its id, name, key, and the address the proxy will see it at);
+- the firewall answers with its own public key, its CA, the agent's id and the proxy's and DNS
+  addresses.
+
+`connect` writes the key and the id into the vm-agent's config, and installs the CA. It prints the
+CA's SHA-256, which the firewall's log shows at start, so you can compare them. The proxy knows the
+agent at its next sync, within a minute.
+
+Where the firewall calls the vm-agent (to set a bot or a model, or for the emergency stop): pairing
+tells the firewall (`agent_listen`), and the vm-agent listens there for the firewall's address alone
+(`allow_from`; any other connection is closed). The calls are plain HTTP with the firewall's signed
+tokens, as the SaaS sends them over HTTPS.
+
+| Mode | The vm-agent listens on | Who may connect |
+| --- | --- | --- |
+| host, proxy, docker, the firewall in a container on this machine (behind one of its Docker bridges, or published on a bridge's address such as `172.17.0.1`) | this machine's address on that bridge, port 3100 | the address the firewall calls from (pairing's `calls_from`: its container's) |
+| host, proxy, the firewall installed on this machine itself (`install.sh`) | loopback only: the vm-agent would listen on the firewall's own address, which pairing refuses | nobody |
+| host, proxy, docker, the firewall elsewhere | loopback only: the firewall does not call it (plain HTTP across a network) | nobody |
+| remote | this machine's tunnel address, port 3100 | the firewall's tunnel address |
+| `up --local` | `172.31.252.1:3100`, this machine on the `outside` network | the firewall's container (`172.31.252.2`) |
+
+Gotchas:
+- With the firewall on another machine, use `--mode remote` for bots, models and the emergency stop:
+  the other modes capture traffic, but the firewall cannot reach the vm-agent there. `connect` says so.
+- Agents paired before this release have no address for the firewall's calls: run `connect` again.
+- `allow_from` is the firewall container's address at pairing. The Docker setup in
+  `standalone/docker/compose.yaml` gives the firewall a fixed one (`172.31.249.2`); a firewall
+  started with a plain `docker run` on Docker's default bridge can get another address when it is
+  recreated: run `connect` again then.
+- MCP servers and app connections go to the firewall's gates directly (3940 and 3900, the
+  firewall's default ports): host and remote capture let OpenClaw's user reach them on the proxy's
+  address, docker capture relays them in its gate container (to a firewall whose gates are on an
+  address it reaches: not `standalone/docker/compose.yaml`'s, which does not publish them). Not in proxy mode (everything goes
+  through the proxy there, which never connects to the firewall itself), and app connections not for
+  an OpenClaw in a container yet.
+- The emergency stop cannot start again an OpenClaw that was started by hand (not systemd, Docker
+  or pm2): start it yourself after the release.
+- `allow_from` is the firewall's address as `connect` dialled it. When the firewall reaches this
+  machine from another address (a NAT, a port forward, a second network), every call is closed:
+  the vm-agent logs `closed a connection from <ip>`. Set `firewall.allow_from` in the config by hand.
+- OpenClaw can still ask the proxy for the vm-agent's address; it then arrives from the firewall's.
+  An egress rule decides, as for any address, and the vm-agent still wants the firewall's signed
+  token.
+
+How the code is safe on plain HTTP:
+- The code is never sent. The request carries an HMAC made with it. The firewall's answer carries an
+  HMAC made with it too, and the answer must repeat a random value from the request.
+  `connect` takes the firewall's key and CA only from such an answer. Someone in the middle sees two
+  HMACs, and 60 bits cannot be tried offline within the code's lifetime.
+- Guessing online is limited to ten wrong codes a minute from one address; after that the endpoint
+  answers 429 for the rest of the minute. There is no limit over all addresses, which anyone could
+  use to block every pairing: even a million guesses a minute for 10 minutes find a 60-bit code with
+  odds of about 1 in 10^11.
+- Once a code has matched, any refusal spends it (make a new one) and counts as a wrong try, so a
+  refusal never tells a guesser that a code was right.
+- The firewall keeps the plain code until it is used or expires, in its database, which only its
+  user can read.
+- The request says the machine's own address toward the firewall, under the HMAC. A request that
+  arrives from another address is refused: someone who copied it on the way cannot pair from their
+  own machine. Behind a NAT or a reverse proxy the two differ, so the admin names the address on
+  the code (`--address`). The CLI pairs over the IPv4 address it measured its own address toward
+  (for `http://`), so the two match.
+- The agent cannot choose its address, and cannot take another agent's place unless the code says
+  `--replace`. OpenClaw on that machine (in host mode it still has the internet until the capture
+  is in) could read a code from a command line and pair first; it would get the same address and
+  nothing more, and the real `connect` would then fail. That is why the code is never taken from
+  the command line.
+- Two machines behind one NAT look like one to the proxy. Give each its own address the proxy sees
+  (WireGuard remote mode will do that).
+- The address must be one the proxy can see an agent at: not loopback, unspecified, multicast,
+  broadcast or the firewall's own.
+- As root, `connect` writes nothing into a folder a user owns (OpenClaw's home: the vm-agent's
+  keys, the systemd drop-in) and follows no link a user owns: those writes, and their undo, run as
+  that user. A root folder on the way that the group or everyone may write to (a shared project
+  folder) stops `connect`, which says which folder to `chmod go-w`.
+
+Unpairing: pairing leaves a random secret in `connect.json` (the firewall keeps only its hash).
+`disconnect`, and a `connect` that fails after pairing, send it to the firewall's `/unpair`, which
+forgets the agent, so the machine can pair again later without `--replace`. When the firewall cannot
+be reached, they say so; remove the agent there by hand (`PUT /api/agents`).
+
+## Modes
+
+| Mode | How | Protection |
+| --- | --- | --- |
+| `docker` | OpenClaw's container moves to a network with no way out except the firewall. | Strong: the container cannot reach the network without the firewall. |
+| `host` | nftables catch every packet from OpenClaw's user. | Limited: anyone with root or sudo on the machine can remove the rules. |
+| `proxy` | OpenClaw's own proxy setting. | Lets you see OpenClaw's own requests and block them. Shell commands and other programs go around it. |
+| `remote` | WireGuard to the firewall, then host mode's rules through the tunnel. | Like host mode on the machine (root or sudo can remove the rules), from any network, with the tunnel address as its identity. |
+
+### docker (needs root, Docker 28 and Compose 2.24.4 or newer)
+
+For an OpenClaw started with Docker Compose, for example OpenClaw's own `docker-compose.yml`.
+`connect` stops in these cases:
+- other services of that Compose project run with the gateway: the gateway leaves its network, so
+  they would lose it;
+- the gateway could get out on its own:
+  - it mounts a container runtime's socket (`docker.sock`, containerd, podman) or a folder that holds
+    one (`/`, `/run`, `/var`, a user's `/run/user/<uid>` for rootless Docker or podman);
+  - it is `privileged`;
+  - it has `NET_ADMIN`, `NET_RAW` or `SYS_ADMIN`;
+  - it uses the host's network.
+
+  The error says which; remove that from its compose file first.
+
+- It writes an override, `/etc/controlclaw/docker/compose.controlclaw.yml`, and runs
+  `docker compose ... up -d` for the gateway service only. Your compose files are not changed.
+- The gateway container goes onto a new network, `<project>_controlclaw`, with `internal: true`.
+  Its bridge gives this machine no address (`gateway_mode_ipv4: isolated`, Docker 28): an internal
+  network otherwise still lets its containers reach every service of the host that listens on
+  `0.0.0.0` (sshd, a resolver, a dev server). `status` checks it.
+  It has no route out.
+- A small `controlclaw-gate` container (socat) sits on that network and on the normal one. It sends
+  port 8080 to the firewall's proxy and port 53 to the firewall's DNS. It also publishes the ports
+  the gateway published before, such as the Control UI on 18789. Docker publishes no ports for a
+  container that is only on an internal network, so the gate has to.
+- The gateway gets `OPENCLAW_PROXY_URL`, `HTTP(S)_PROXY` and `NODE_USE_ENV_PROXY=1`. The CA is
+  added in two ways:
+  - `NODE_EXTRA_CA_CERTS`;
+  - a CA bundle mounted over `/etc/ssl/certs/ca-certificates.crt`: the image's own bundle plus the
+    firewall's CA.
+- Anything that ignores the proxy (a direct IP, another DNS server, UDP) has nowhere to go.
+- After a reboot, Docker brings both containers back the same way.
+- `docker compose up -d` in the project's folder (an OpenClaw update, say) keeps the capture:
+  `connect` adds `COMPOSE_FILE=<your files>:<the override>` to the project's `.env`, and
+  `disconnect` takes it out.
+  - If your `.env` already sets `COMPOSE_FILE` or `COMPOSE_PATH_SEPARATOR`, it is left alone and
+    `connect` tells you to add the override yourself.
+  - Run with `-f` and without the override, the gateway goes back on its open network. `status`
+    shows it.
+
+If the firewall runs on the same machine, it must listen where containers can reach it, such as
+the `docker0` address (`172.17.0.1`), and `--proxy` and `--dns` must name that address. `connect`
+refuses `127.0.0.1`: inside the gate it means the gate itself.
+
+The network uses `172.31.250.0/24`. If another Docker network already uses it, `connect` stops.
+
+### host (needs root and systemd)
+
+For an OpenClaw installed on the machine, for example with the official installer. It runs as a
+systemd user unit.
+
+- `/etc/controlclaw/capture/capture.nft` holds the rules for OpenClaw's uid only:
+  - TCP goes to redsocks, which hands it to the firewall's proxy;
+  - DNS (port 53, UDP and TCP) goes to the firewall, whatever server was asked, except
+    systemd-resolved's own stub (127.0.0.53), which itself asks only the firewall (below). A query
+    from 127.x sent on to another machine would be dropped as martian;
+  - IPv6, ICMP and other UDP are refused;
+  - on the machine itself (127.0.0.0/8, ::1) only these TCP ports are allowed:
+    - redsocks and the vm-agent (3100);
+    - OpenClaw's own, derived from the gateway port as OpenClaw 2026.10 does: the gateway, browser
+      control (+2), the extension relays (+3 to +10) and the default browser profile's CDP (+11),
+      so 18789–18800 by default;
+    - the CDP port each other browser profile has in OpenClaw's config. If that config is not
+      plain JSON (JSON5), its profiles cannot be read, so the whole range OpenClaw uses (to +110)
+      stays open.
+
+    Anything else listening there is refused, so that sshd with the user's keys, a local proxy or a
+    resolver on `::1` cannot be a way out. A root program that listens on one of those ports would
+    still be reachable. A browser profile made after `connect` gets a new CDP port, which is refused
+    until you run `disconnect` and `connect` again.
+
+    OpenClaw's Codex relay (the ChatGPT/Codex provider) listens on a random port and does not work in
+    host mode. Use docker mode for it.
+- `controlclaw-capture.service` loads the rules at boot, before the network is up. It does not wait
+  for the firewall. If the firewall is down, OpenClaw cannot reach anything.
+- `nftables.service` flushes the whole ruleset on start, restart, reload and stop. So ours loads
+  after it at boot, and a drop-in (`nftables.service.d/controlclaw.conf`) has it load ours again
+  after each of those. Anything else that flushes the ruleset (`nft flush ruleset`, `nft -f` of a file that
+  flushes) removes it; `status` shows when the table is missing.
+- `controlclaw-redsocks.service` runs redsocks under its own user. `apt-get install redsocks` runs
+  if it is missing, and `disconnect` removes it again.
+- The CA is added to the system store, to OpenClaw's service (a drop-in that sets
+  `NODE_EXTRA_CA_CERTS`) and to Chrome's stores, if Chrome and `certutil` are installed. OpenClaw is
+  restarted so it reads it.
+
+resolved also gets `LLMNR=no` and `MulticastDNS=no`, and its user may not send to ports 5353 and
+5355: otherwise a single-label or `.local` name would go onto the local network.
+
+**The whole machine's DNS depends on the firewall.** Most programs look names up through
+systemd-resolved, not port 53, so `connect` points resolved at the firewall
+(`/etc/systemd/resolved.conf.d/controlclaw.conf`). It also allows resolved to ask only the firewall:
+not a DNS server a network link got from DHCP, and not DNS over TLS. If the firewall stops, DNS stops for every
+program on the machine, not only OpenClaw. `doctor` says so before you connect, and `status` shows
+it when the firewall's DNS does not answer.
+
+Host mode refuses to run in these cases:
+- OpenClaw runs as root. The rules would then catch every root program. Run OpenClaw as its own user.
+- OpenClaw's user is in the `docker` group (or `lxd`, `incus`, `libvirt`, `podman`). It could start a
+  container whose traffic dockerd sends, not the user, so the rules would never see it. Remove the
+  user from the group (`gpasswd -d <user> docker`), or use docker mode. If the user's groups cannot
+  be read (`id -nG` fails), host mode refuses too.
+- systemd-resolved runs but has no `systemd-resolve` user: its queries could not be limited to the
+  firewall's DNS.
+
+### remote (needs root, systemd, and a firewall with WireGuard)
+
+For a machine that reaches the firewall over the internet: another cloud, a home server. The firewall
+runs WireGuard (`install.sh --wireguard`). Pair with a code; `--ca` is refused here.
+
+```bash
+sudo controlclaw connect --mode remote --firewall http://fw.example.com:8801 --vm-agent ./vm-agent
+```
+
+- Before pairing, `connect` makes this machine's WireGuard key pair. Pairing sends the public half,
+  and the firewall answers with a tunnel address (its identity at the proxy, such as `10.77.0.2`),
+  its own WireGuard key and endpoint, and its tunnel address (`10.77.0.1`).
+- `/etc/wireguard/cc-wg0.conf` and `cc-wg0.key` (root only), brought up by `wg-quick@cc-wg0` before
+  anything else, and `connect` waits (up to about 45 seconds) for the firewall's first answer. When
+  none comes (UDP to its endpoint blocked), it stops and undoes all of it. Only the
+  firewall's tunnel address goes into the tunnel: the machine's other traffic keeps its routes.
+  `wireguard-tools` is installed if missing, and removed by `disconnect`.
+- Then the same capture as host mode, with the firewall at its tunnel address: redsocks to
+  `10.77.0.1:8080`, DNS to `10.77.0.1`, resolved pointed there. Two more rules in the table:
+  - after routing, nothing for the firewall's tunnel address leaves by another interface. With the
+    tunnel down, OpenClaw's traffic, its DNS and resolved's queries go nowhere: they never leave in
+    clear on the public interface;
+  - the vm-agent listens on this machine's tunnel address, and only the tunnel reaches it (and
+    there only the firewall's end, `allow_from`);
+  - what goes into the tunnel leaves from this machine's tunnel address (DNS that OpenClaw sends to
+    another server is DNATed into the tunnel, and the firewall takes only that address from it);
+  - nothing forwarded goes into the tunnel: a container on this machine (which Docker masquerades)
+    would otherwise reach the firewall as this agent.
+  The rules judge only OpenClaw's user's packets; the kernel's own (WireGuard's UDP) are not refused.
+- Behind a NAT it works as it is: over WireGuard the identity is the tunnel address, not the address
+  pairing comes from. (A request copied on the way and replayed elsewhere would register a key whose
+  private half only this machine has.)
+- `status` shows the tunnel and its last handshake.
+- `--proxy` and `--dns` are refused: they would send the capture outside the tunnel, in clear.
+- A machine set up again from scratch (its `connect.json` lost) gets a new WireGuard key and a new
+  tunnel address. The old peer stays on the firewall until the admin removes that agent (`PUT
+  /api/agents`, or the panel): `disconnect` removes it only when it still has the record.
+- The limits of host mode apply: OpenClaw's own user, not root, not in the docker group, no sudo.
+
+### proxy (no root needed)
+
+For any OpenClaw on the machine, also on a machine without root.
+
+- It sets OpenClaw's managed proxy: `proxy.enabled`, `proxy.proxyUrl` (the firewall's proxy) and
+  `proxy.loopbackMode: gateway-only`. `disconnect` removes the setting again.
+- `connect` stops if OpenClaw already has a proxy setting, so that `disconnect` never loses one. It
+  reads the setting from OpenClaw's config file, because `openclaw config get` hides the URL. If that
+  file is not plain JSON (JSON5 with comments), `connect` stops too.
+- `proxy.tls.caFile` is not used: it only verifies an `https://` proxy. To trust the firewall's CA,
+  OpenClaw's service gets `NODE_EXTRA_CA_CERTS`.
+- It is part of OpenClaw's config, so it stays after a reboot. When the proxy is down, OpenClaw's
+  requests fail; they do not go out directly.
+- `status` runs `openclaw proxy validate`.
+
+## up --local: the firewall and OpenClaw on one machine
+
+```bash
+sudo controlclaw up --local --firewall-image controlclaw-firewall:dev-amd64 --vm-agent ./vm-agent
+```
+
+Two containers in a Compose project, `controlclaw-local`, in `/opt/controlclaw-local` (`--dir`):
+
+- **OpenClaw** (`ghcr.io/openclaw/openclaw:2026.10.9`, `--openclaw-image`) is only on an internal
+  network, `agents` (`172.31.251.0/24`, OpenClaw at `.10`), whose one other member is the firewall
+  (`.2`). Its proxy and DNS are the firewall's, with the CA in Node and in the system store (as in
+  docker mode). It has no other way out: the network's bridge gives this machine no address either
+  (`gateway_mode_ipv4: isolated`, so Docker 28 or newer), so this machine's own services are out of
+  its reach.
+- **The firewall** (the image from `standalone/docker/build.sh`; none is published yet) is also on
+  `outside` (`172.31.252.0/24`). Its panel (8800) and pairing (8801) listen there only, so OpenClaw
+  cannot reach them. It publishes, on this machine's loopback only, OpenClaw's gateway (18789,
+  `CC_FORWARD`: Docker publishes nothing from an internal network), its panel, pairing and pages.
+- It pairs itself:
+  - a code from the firewall with OpenClaw's address on it;
+  - pairing over the loopback;
+  - the vm-agent on this machine, as root, for the container, with the firewall's key and the
+    agent's id. It listens on this machine's side of `outside` (`172.31.252.1:3100`, after Docker
+    starts), where the firewall calls it, and takes connections from the firewall's container only.
+    OpenClaw, on `agents` only, has no route there of its own.
+- OpenClaw is set up with a gateway token (in `.env`, 0600) on first run. Its Control UI's allowed
+  origins are set to `http://127.0.0.1:18789` and `http://localhost:18789` at each run: OpenClaw sees
+  the browser through the firewall's relay and accepts the page only from an origin it is told.
+- It prints OpenClaw's address with its token, the panel's address, and the panel's first-run setup
+  token. From another machine: `ssh -L 8800:127.0.0.1:8800 -L 18789:127.0.0.1:18789 <machine>`.
+- The firewall starts with every request blocked: allow your model provider in the panel first.
+- `disconnect` stops the containers (`compose down`), unpairs, and removes the vm-agent and the files
+  it wrote. OpenClaw's data (`openclaw/`, `openclaw-secrets/`) and the firewall's volume stay; `up
+  --local` again picks them up.
+- It needs root, Docker 28 and Compose 2.24.4 or newer. The two networks' subnets must be free.
+
+## What disconnect does
+
+`connect` writes each step to `/etc/controlclaw/connect.json` (`~/.config/controlclaw/` without
+root). After a `connect` with sudo, run `disconnect` and `status` with sudo too; without it they say
+so. `disconnect` undoes the steps in reverse:
+
+- it puts back each file it changed, and removes the files and folders it created;
+- it stops and removes the units;
+- it restores OpenClaw's settings;
+- it restarts OpenClaw last.
+
+If `connect` fails halfway, it undoes itself the same way. When a step fails, it stays in
+`connect.json` and the rest still run, so you can run `disconnect` again once the cause is fixed. A
+step that can never work again (its file is gone) is given up with `disconnect --force`, which then
+lists what to check by hand.
+
+A file `connect` changed (a project's `.env`) gets its content, mode and owner back. If the vm-agent
+binary was already at `/usr/local/bin/controlclaw-vm-agent`, it is used where it is and left there.
+Someone else's binary there is set aside as `.before-controlclaw` and put back; if such a file is
+there already (from a connect whose record was lost), `connect` stops rather than overwrite it.
+
+## Gotchas
+
+- **The CA needs a restart.** Node reads `NODE_EXTRA_CA_CERTS` only when it starts. `connect` restarts
+  OpenClaw. If OpenClaw runs with pm2 or as a plain process, add the variable to how you start it.
+- **sudo.** If OpenClaw's user can use sudo, then in host mode OpenClaw, or its agent, can remove the
+  rules. `doctor` warns about it.
+- **The vm-agent runs as OpenClaw's user** in host and proxy mode, and as root for Docker. See
+  [`rust/bins/vm-agent/UNMANAGED.md`](../../rust/bins/vm-agent/UNMANAGED.md).
+- **The firewall must serve DNS** on port 53 for host and docker mode. Without it, `connect` still
+  runs, but `status` shows the DNS check failing.