History

dan-claude-bot 86dbb0449e refactor(templates): the tenant seeds carry rig's -box family suffix rig is growing a second family of roles, and once a 'staging' role can mean either a fleet machine or a box tenant, the bare name stops naming anything. rig's answer is a suffix on the role (heavy-duty/rig#76): '-server' for fleet machines, '-box' for box tenants. box's answer is that a template keeps being named for the role it converges, so the tenant templates move with it: claude -> claude-box codex -> codex-box grok -> grok-box staging -> staging-box Templates are the only surface that spells a rig role out loud (BOX_BOOTSTRAP_ROLE, auto-run at mint since #81), so a directory that says one thing and a role key that says another is a trap with a 15-minute fuse: it mints clean and dies at convergence. Renamed with 'git mv' so the history of each seed follows it. 'blank' keeps its name. It seeds no tenant role and sets no BOX_BOOTSTRAP_ROLE, so it has nothing to agree with — renaming it would only churn the default template's name for symmetry's sake. Two namespaces move apart here and only one of them moved: the template name and the role are now claude-box, while the seed USER stays 'claude' — that is the user rig's role converges and the one 'box shell' lands in. test/cli.sh pins the pair per tenant rather than each half alone, because a later rename that moves one and forgets the other mints a box whose role dies looking for a user nobody created. drill.sh keeps its bare box NAMES ('codex', 'grok' — what the pre-flight banner announces and what teardown deletes) and only moves the --template it passes. The mint-time hints in cmd_new match both spellings of user.box.template, and that is not an alias for the role: 'rig bootstrap claude' is gone and nothing here softens the cut. The stamp is a fact about an INSTANCE, written at its own mint time and carried forward by every clone; refusing the old spelling would cut nothing over and only drop the login hint on boxes that predate today — the same reason user.claudebox is honored everywhere else. migrate-host.sh stamps re-homed legacy boxes claude-box, the name the template has today, so a re-homed box looks like a fresh mint rather than a fossil. Ordered AFTER rig's rename, and that is not a preference. The seeds install rig from RIG_REPO/RIG_REF, defaulting to heavy-duty/rig@main and unpinned until rig#32's releases, so these templates ask whatever main happens to be for 'rig bootstrap claude-box'. Against a pre-rename rig that role does not exist and cmd_new refuses to call the box ready. Merged in the other order the window closes instead of opening: rig's cut is hard, with no aliases, so the day it lands every unmerged box seed naming a bare role is the broken one. Closes #123 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>		2026-07-20 00:01:29 +00:00
..
doctor.sh	docs: the subnet auto-pick — help, README, changelog, doctor wording (#80 )	2026-07-18 21:22:00 +00:00
drill.sh	refactor(templates): the tenant seeds carry rig's -box family suffix	2026-07-20 00:01:29 +00:00
multiuser.sh	fix: the unattended rehearsal consents explicitly to the restore gate	2026-07-19 19:46:06 +00:00
README.md	docs: the restricted tier — README, design doc, plan doc with measured results (#74 )	2026-07-18 04:09:48 +00:00
RUNS.md	grant/rehearsal: the codex round — verified rollback, loud partial states, and the raw-attach guarantee measured (#75 )	2026-07-18 06:41:05 +00:00
wipe.sh	test+ci: add CI workflow and a dependency-free test suite	2026-07-18 00:01:15 +00:00

README.md

The drill

An end-to-end rehearsal of box against a real Incus: install the CLI, set up the host, mint boxes, drive the whole surface, check that the isolation actually holds — and run the full #15 audit, including a live rehearsal of the hardening #16 proposes. It ends with a block of audit answers to paste into #15.

⚠ It rearranges the host it runs on. Incus, a systemd unit, a network, an ACL, a profile, rewritten firewall rules — and, in the last phase, deliberate mutations to the network and profile. Run it on a machine you can format — a spare server, a cloud VM you'll destroy, a VM on your laptop. Not your workstation.

git clone https://github.com/heavy-duty/claudebox && cd claudebox
bash drill/drill.sh --yes      # run and forget; omit --yes to be asked first

Useful flags: --ref <branch> (drill a branch rather than main), --keep-boxes (leave the boxes up to poke at — note the last phase's network and profile mutations stay applied with them).

Exit 0 means every check passed. Roughly 20 minutes, most of it the cold box.

Something wrong with the host? bash drill/doctor.sh — it reports whether the host is fit to drill (network, profile, ACL, leftover boxes, whether a box can still resolve DNS), and --fix reverts what an aborted run left behind. The drill mutates the host in phase D; an aborted run can leave a network that mints boxes with no DNS.

Iterating on the drill? Read RUNS.md first — it is the run log: what the audit has answered so far, the bugs the drill has found in box, the traps this script has already fallen into (every one cost a run), how to diagnose a stall, and how to run a single probe by hand instead of paying for a whole run.

Why it exists

The repo has no tests and no CI, and the CLI is a shell script that shells out to incus. That means the interesting failures are not in the bash — they are in what Incus actually does, which is exactly what unit tests would stub out and get wrong. The drill runs the real thing.

What it checks

A. Incus semantics. The assumptions box is built on, probed directly: that incus config get <inst> user.claudebox returns 1 (this is on the path of every box command — if it lies, everything fails closed); that the user.claudebox=1 list filter selects our instances and excludes an untagged one; that --columns nstS gives four clean CSV fields; that the state column reads RUNNING; that incus rename really does refuse a running instance; that snapshot-list's first CSV field is the label; that an unset config key reads as empty with exit 0 (#15 B4); and that incus copy preserves user.* keys (#15 B2 — the whole template-metadata design in #17 rests on it).

B. The surface. Mint, list, info, snapshot, clone-from-a-snapshot-of-a- renamed-box, rename (running must refuse, stopped must work), the escape hatch and its isolation warning, the rm confirmation guard, and the CLI contract (typo'd command, typo'd flag, list <box>).

The boundary gets its own treatment: the drill launches an instance box did not mint, aims down, rm and the escape hatch at it, and requires all three to refuse — and the instance to still be standing afterwards.

C. Isolation baseline (#15 section A). From inside a real box: public egress works; the box cannot reach a listener on the host's claudenet gateway; RFC1918 is dropped; a sibling box is unreachable (a listener runs on the peer so "refused" — the packet arrived — cannot masquerade as "dropped"); whether DNS enumerates the sibling is recorded (#12 predicts it leaks today; that is audit data, not a failure); IPv6 is off; and the host cannot connect into a box.

D. Hardening rehearsal (#15 section B). The host is disposable, so the drill applies the exact changes #16 proposes and watches what breaks: dns.mode=none (must kill sibling resolution, must not kill egress), security.mac_filtering + security.ipv4_filtering on the NIC (the box and its in-box Docker must keep working), and @internal as an ACL drop destination on a bridge network (if accepted and egress survives, #16's sibling drop is renumber-proof by construction; if not, #16 derives the subnet instead). A FAIL in this phase is a design veto for #16, caught before the code is written.

What it does not check

agent login (e.g. claude /login) — it's interactive by design, and the box is creds-free by design. The drill confirms each coding-agent template's CLI is installed and runnable; authenticating is yours.

If the host has no /dev/kvm, box falls back to container mode. The drill still runs, but it says loudly that the VM trust boundary was not validated rather than passing quietly on a weaker one.

The multi-user rehearsal (`multiuser.sh`)

The restricted tier (#74) has its own rehearsal — the drill proves one operator's host; this proves a shared one:

sudo BOX_MULTIUSER_REHEARSAL=1 bash drill/multiuser.sh --yes

Root only, opt-in twice (it creates system users and edits the group database). It creates two throwaway users, grants them the tier through the real box grant, mints real boxes as them, and measures — from inside those boxes — that each user is confined to their own project (a), the full lifecycle works (b), no cross-user visibility (c), names don't collide (d), expose/setup-host/doctor answer honestly at the tier (e/f), the boxes ride boxnet under the full isolation contract including the cross-user sibling drop (g), the private-bridge escape hatches are closed (h), the grant survives an incus-user restart (k), and revoke --purge erases one user without touching the other (l). Everything it makes, it deletes.