tx9

Isolated, portable agent boxes with Claude Code, Codex, Hermes, and Executor, running on Docker. Each box is a pair of containers on a private network — a free-rein agent container and an isolated Executor container — with all durable state on a named volume that travels as an encrypted, validated backup archive.

Status: experiment, mid-transition. The bash prototypes (smolvm ./box and the compose ./docker/boxd) have been retired in favor of a Go CLI (tx9, this repo, embedding its provisioning and guest assets) that is now implemented and under active development — still experimental, not yet released. See docs/tx9-cli-design.md for the full design and docs/docker-architecture.md for the runtime architecture and its verification history.

Model

tx9 create                      (Go CLI, embedded build assets)
      ▼
 compose-style project per box ─────────────────────────────────┐
 │  ┌───────────────────────┐      ┌─────────────────────────┐  │
 │  │ agent ("linux land")  │      │ executor                │  │
 │  │ claude·codex·hermes   │      │ Executor daemon only    │  │
 │  │ gateway, sudo, free   │      │ dashboard / + MCP /mcp  │  │
 │  │ agent volume = the box│      │ scratch volume          │  │
 │  │ no published ports    │      │ one 0.0.0.0 host port   │  │
 │  └───────────┬───────────┘      └───┬─────────────────────┘  │
 │              │ http://executor:4788 │ bearer-token gated     │
 │              └── private network ───┘                        │
 └──────────────────────────────────────────────────────────────┘
      ▼
 <box>-<timestamp>.tx9          encrypted, validated state archive

The agent volume is the box; containers are disposable; tools are image layers ("upgrade" = rebuild image + recreate containers). Executor state is scratch and does not travel. Networking is always enabled because the agent tools require internet access.

Repository layout

In-box control (hb)

Inside the agent container:

hb status / hb doctor / hb versions
hb down            # durable pause; the reconcile loop won't restart services
hb up
hb gateway-enable --confirm-single-writer I_CONFIRM_NO_OTHER_GATEWAY_USES_THIS_IDENTITY
hb gateway-disable
hb verify-state
hb wire-mcp        # (re)register Executor's authenticated HTTP MCP for claude+codex
hb logs executor

Fresh and restored boxes begin with the Hermes gateway durably disabled so setup and migration cannot create a second Discord writer; enabling it is always an explicit, confirmed step. Executor runs remotely from the agent's perspective (EXECUTOR_HOST=executor): hb checks reachability and wires MCP with the injected bearer token; it never spawns or stops the daemon.

Backup guarantees

Saves quiesce the gateway, checkpoint SQLite, archive agent /data (minus caches, PIDs, locks, and DB sidecars), validate the archive member-by-member (absolute paths, traversal, special files, duplicate members, unsafe symlink/hardlink targets, link cycles), encrypt with GPG AES-256, then decrypt-verify before publishing without overwriting. Restores validate before creating anything, stage-then-promote inside a throwaway container, re-arm the quiesce and gateway-disable markers, mint a fresh executor token, and rewire MCP automatically.

Local validation

make check          # syntax + shellcheck + static contracts + regressions; hermetic
make check-hermes-pin   # network: compare HERMES_INSTALLER_SHA256 against upstream

.depot/workflows/check.yml runs make check on every push and pull request to main via Depot CI.

If an image build fails with "Hermes installer checksum verification failed", upstream rotated install.sh since the pin: run make check-hermes-pin, review the new installer, then update box.env yourself.