tx9 CLI — design

Status: implemented and evolving. The initial 12 decisions were settled on 2026-07-04; this document now records the shipped Go CLI plus later command surface additions. The deleted bash prototypes that informed it (./box on smolvm, ./docker/boxd on compose) remain available in git history (9350212 and earlier).

What tx9 is

A single Go binary installed on a machine ("tx9") that creates and manages hermes boxes — the two-container agent/executor pairs described in docker-architecture.md. No repo checkout, no ./docker/boxd, no compose plugin. The CLI is the product; the repo is its source.

curl -fsSL https://tx9.col-agents.com/install | bash
tx9 create

The 12 decisions

Command surface

Running tx9 with no arguments prints an ASCII overview of configured boxes (state, image version, dashboard URL, container CPU/RAM, and volume usage/budgets), followed by the command list. It exits successfully when the Docker overview can be read. tx9 help remains Docker-independent.

create, import, and box-specific upgrade accept the shared --executor-web-base-url, --executor-publish, and --executor-dns options. Their resolved values are persisted per box and reused on future upgrades. --clear-executor-config returns a box to the default dynamic HTTP exposure. The same commands also accept --agent-cpus, --agent-memory, --executor-cpus, --executor-memory, --agent-volume-budget, and --executor-volume-budget; omitted values keep the defaults or the box's current allocation, as appropriate.

Fixed contracts (carried from the verified bash draft)

These were dry-run- and QA-verified in the boxd prototype and must survive the port:

• Topology: agent container (no published ports, volume = the box, sudo, IPv6 disabled via sysctl) + executor container (daemon only, --hostname 0.0.0.0 --port 4788 --auth-token <token>, one published host port (all interfaces/automatic by default, optionally fixed and loopback-only), scratch volume) + per-box private network. Labels (tx9=1, tx9.box=<name>, tx9.version=<v>) on every object.
• Token: 256-bit random per box, minted at create/import, injected as BOXD_EXECUTOR_TOKEN (outranks any restored on-disk executor-mcp.env — real bug found in dry run) and EXECUTOR_HOST=executor. hb wire-once re-wires when token or URL is stale.
• Archive safety: the member-by-member validator (absolute paths, traversal, special files, duplicates, link targets/cycles/nesting) ported from bash+python to Go. Validate before create on import; validate after tar on backup. Restores stage-then-promote in a throwaway container and re-arm quiesce + gateway-disabled markers.
• External host mounts: per-box bind mounts are host-local desired state, persisted in ~/.tx9/boxes/<name>.env and reapplied during upgrades. Their targets stay below /mnt so backups of /data never traverse NAS or other external content. Mount sources are preflighted before container removal; --require-mountpoint refuses to bind an empty underlying directory when a host share is offline. Required non-root source GIDs are added to the agent container automatically.
• Resources: container limits are per-box desired state, with current defaults of 4 CPU/8 GiB for the agent and 2 CPU/2 GiB for Executor. Live changes survive upgrades and agent recreation. Local named volumes remain unbounded host-backed storage; recorded volume budgets are advisory and never labeled as enforced quotas.
• Observability: tx9-owned process output is redacted, rotated, and stored on the producing component's own volume. Host-side queries merge these streams with tolerant readers for the native Codex/Claude JSONL and Hermes SQLite histories. Executor data is never mounted into the agent container. This provides complete tx9-owned runtime output, not an independent audit trail for operations that Executor does not emit to any durable sink.
• Portable custom services: direct executable regular-file children of ${XDG_CONFIG_HOME:-$HOME/.config}/hermes-box/services.d are supervised as the agent. Names are limited to [a-z0-9][a-z0-9_-]{0,62}. The absolute file path is passed as argv directly, never sourced or evaluated; scripts stay foreground and should exec their daemon. Each service has an independent tx9-logs capture and bounded restart loop under source service-<name>. Runtime PID/lock state stays outside /data, while the definitions and logs remain on /data and therefore travel in backups. hb services reports status and ignored entries; hb services-reload reconciles immediately in addition to the normal 20-second loop. Quiesce synchronously stops every custom service and blocks restart until hb up/hb resume; Hermes gateway enable/disable is independent. Drop-ins run with the agent's ordinary access and are trusted executable code, not a sandbox boundary.
• Gateway single-writer: restored boxes never auto-enable the Hermes gateway. tx9 gateway enable <box> --confirm-single-writer delegates to hb gateway-enable and stays the only host-side path.
• Executor public origin: create/import/upgrade optionally persist an exact EXECUTOR_WEB_BASE_URL, fixed host publish address, and container DNS list. This supports HTTPS reverse proxies such as Tailscale Serve without losing the callback origin or proxy target on the next container recreation.
• Entrypoints: agent PID-1 = hb init (fail fast) + hb-workload loop under docker --init; executor PID-1 = foreground daemon. Restart policy unless-stopped.
• Gotchas to preserve: containers need net.ipv6.conf.all.disable_ipv6=1 (executor binds localhost → ::1 otherwise); right after start the executor needs a boot-window retry before health checks pass.

Go implementation notes

• go:embed a tar of provision/, guest/, docker/Dockerfile, entrypoints, box.env → feed to the Engine API's ImageBuild as the build context. Image tag from the CLI's ldflags version.
• Name generator: small embedded adjective+animal word lists.
• Per-box flock in ~/.tx9/locks/ (same semantics as boxd: one operation per box; fail fast, don't queue).
• create progress: stream ImageBuild output through a spinner/step UI on first build; subsequent creates are seconds.
• .tx9 format: tar.gz of /data plus a small JSON metadata header (box name, created-at, CLI/image version, encrypted flag). Simplest encoding: outer tar with metadata.json + data.tar.gz[.gpg] members — sniffable, streamable, and the metadata stays readable without the passphrase.
• Encryption: keep GPG-compatible AES-256 symmetric (shell out to gpg, or use a Go OpenPGP lib) so operators can decrypt archives without tx9 in an emergency.
• Doctor/MCP checks: port lib-mcp.sh's initialize handshake to Go (proper HTTP client, jq logic in code).

Saved for later (explicitly out of v1)

• Remote/multi-host — worth doing eventually: tx9 --host nexus list, or tx9 move large-cat nexus (backup → stream → import → gateway gates, one command from a laptop). Design constraint to keep in mind now: keep the daemon interface behind a small interface type so a remote Docker daemon (SSH tunnel / DOCKER_HOST) slots in without restructuring.
• Hosted docs/site at tx9.col-agents.com beyond the install redirect.
• Registry-published images (decision 1 fallback if local builds annoy).
• Compose healthchecks / depends_on: service_healthy equivalents via the SDK health config.
• Executor-state backup (currently: scratch by contract, does not travel).
• Slim executor image variant; token rotation command; executor egress policy network.

Migration to tx9

The guest layer (guest/, provision/, box.env) is shared and already compose-split aware, so existing boxd-created boxes are structurally identical to what tx9 will create — only labels/names differ (hbl-* vs tx9-*). Don't build compatibility: the running dry boxes are disposable, and any box that matters moves via backup/import anyway.