# 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](docs/tx9-cli-design.md) for the full
design and [docs/docker-architecture.md](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](docs/tailscale-executor.md).

## Model

```text
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

| Path | Role |
|---|---|
| `box.env` | Build/runtime configuration: tool versions/channels and feature flags |
| `site/` | Cloudflare Worker for tx9.col-agents.com: homepage, `/install` script, release downloads from R2 |
| `provision/provision.sh` | Runs inside `docker build` (`tools` + `assets` layers); installs everything |
| `guest/` | In-box runtime: `hb` control CLI, `hb-workload` reconcile loop, `hermes-state` validator, profiles, tmux config |
| `docker/` | Image build assets: `Dockerfile`, agent + executor entrypoints |
| `docs/` | Architecture, CLI design, operations history |
| `tests/` | Static contract checks and guest-script regressions (`make check`) |

## In-box control (`hb`)

Inside the agent container:

```bash
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:

```bash
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

```bash
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.