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, released, and under active development, though still experimental. See docs/tx9-cli-design.md for the full design and docs/docker-architecture.md for the runtime architecture and its verification history.

For a stable HTTPS Executor origin and OAuth callbacks over a tailnet, see Tailscale HTTPS for Executor.

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 configurable 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

The host CLI exposes the safe gateway lifecycle directly:

tx9 gateway status <box>
tx9 gateway enable <box> --confirm-single-writer
tx9 gateway disable <box>

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. Do not use hermes gateway run as the persistent TX9 lifecycle: it is foreground work and exits with its terminal. 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

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