box/CHANGELOG.md

Changelog

History before 0.5.0 lives in git and in drill/RUNS.md, which records not just what changed but what each drill run proved.

Unreleased

Added

• setup-host refuses a claimed subnet, and BOX_SUBNET picks another (#80) — run inside a box, setup-host used to build a nested boxnet on the exact subnet and gateway of the guest's own uplink: the guest then held its gateway's address as a local address, carried duplicate connected routes for its uplink subnet, and suffered intermittent, self-recovering egress blackouts that looked like flaky internet (measured live: ~24–36 s outages, roughly hourly, with the host clean throughout). setup-host now scans the target subnet before any mutation — the default route's gateway inside it, or any non-boxnet interface holding an address in it — and refuses, naming the way out. A prior boxnet owning the subnet is the legitimate converge path and does not trip it. BOX_SUBNET=<a.b.c.0/24> (validated, alongside the existing BOX_DNS) moves the whole stack: the bridge address, the ACL's gateway carve-out (now converged via network acl edit, so a bridge moved off a colliding subnet no longer strands box DNS behind a stale /32), the firewall (box-firewall reads the gateway off the live bridge), and every drill/migrate probe that used to hardcode 10.88.

• box doctor knows the #80 signature — a default gateway held as a LOCAL address, and duplicate connected routes for the uplink subnet, judged from ip route/ip addr on the machine doctor runs on (both tiers, before any daemon check — the nested daemon answering could be the impostor) and probed inside every box it examines. The existing "egress broken but DNS fine" split now names itself as #80's fingerprint (the impostor dnsmasq on a captured gateway keeps resolving while IP egress dies), and the admin ACL section verifies the gateway carve-out matches boxnet's actual gateway. The agent-context guard for the templates (suggested fix 4) lands in heavy-duty/rig#31's bootstrap roles per the thin-templates split (#81).

• The staging template (#81, the re-cut of #69's layering) — a server-class, creds-free seed: Debian 13, user ops, tmux, rig, BOX_REQUIRE_VM=1 (the VM is its trust boundary), BOX_AUTOSTART=1 (a server returns from a host reboot without an operator), and BOX_BOOTSTRAP_ROLE="staging" — the server posture (docker, sshd hardening) converges via rig bootstrap staging after mint. The tailnet workload join holds a pre-auth key and therefore stays operator-run (box shell → sudo rig bootstrap workload), printed as a next step — box never sees the key.

• BOX_BOOTSTRAP_ROLE template key + mint-time auto-run (#81) — a template names the creds-free rig tenant role box runs inside the guest after cloud-init settles (incus exec … rig bootstrap <role>); the value is a role name by allowlist (anything shell-shaped dies at parse time, on the host). A failed role leaves the box up and names the re-run — the roles are convergent by contract (rig#31). blank names no role and auto-runs nothing.

• The rig pin point: RIG_REPO / RIG_REF (#81) — the tenant seeds preinstall rig, inverting the rig→box install edge (rig#28), and the new edge gets the same honest treatment rig#29 gave box's unpinned install: @RIG_REPO@/@RIG_REF@ tokens in the seed resolve at mint from the environment (default heavy-duty/rig @ main — unpinned, tracking main, until a release flow exists, rig#32/#83). The pin covers both the installer fetched and the tree it installs, so a rig branch under review is testable end to end; values are allowlist-validated before touching the YAML.

• Server-posture template keys (#81, carved from #69) — two optional box.env allowlist keys. BOX_REQUIRE_VM=1 refuses both the silent container fallback (no /dev/kvm, exit 1) and an explicit --container (exit 2): such a template's trust boundary is the VM. BOX_AUTOSTART=1 stamps boot.autostart=true at launch, per-instance like limits.*, so the box returns from a host reboot without an operator; clones inherit it via incus copy. Still no key for a network or a security.* flag, on purpose.

• Dynamic template test suite (#81, carved from #69) — test/cli.sh discovers templates/*/ instead of hardcoding the list, so a new template cannot ship unseen. Per template: box.env is driven through the real, extracted load_template (unknown keys and missing BOX_IMAGE/BOX_USER fail, fixtures proving both dies); user-data.yaml exists, declares #cloud-config, parses as YAML, and installs tmux (#65). Grep guards pin the cmd_new half: the REQUIRE_VM refusal orders after pick_mode, and boot.autostart is stamped only under the T_AUTOSTART guard.

• box export / box import (#70) — a box's state that survives the box and the host, unblocking #66's humane upgrade flow (down, export, rm, upgrade, re-import). box export <box> [<file>] wraps incus export into one portable backup tarball (default <box>-<UTC stamp>.tar.gz), snapshots included by default (--instance-only opts out); the box must be stopped first (box down) so the artifact is a settled disk, not a moving one. The file is shouted about, not scrubbed — it carries the box's whole disk (agent logins, git credentials, SSH keys), and scrubbing a disk image is a promise tarball surgery cannot keep, so box says what is inside instead, every time. box import <file> [--name <box>] mints the box back and re-stamps what is the current host's truth, not the artifact's: the user.box=1 boundary tag (legacy user.claudebox=1 honored), the box-net placement (re-assigned if the artifact's differs — the migrate-host move), and a fresh machine identity: the NIC's MAC (imports restore volatile.* verbatim, and a re-import beside its sibling collided at start with "MAC address already defined on another NIC" — measured live; incus copy regenerates it, incus import does not) plus reset_identity (the clone trust boundary: no DHCP collision with the box it was exported from). Import refuses any name an existing instance holds — the resolve_box boundary, seen from the other side. Works on both tiers: box grant now also converges restricted.backups allow (incus-user blocks backups by default exactly like snapshots, and an export is a backup create+download — measured against incus 6.0's permissions.go); re-run box grant <user> after upgrading, as documented. CI's rehearsal job now proves the round-trip on a live Incus: mint → write a file → snapshot → down → export → rm → import → the file and the snapshot survived, the agent answers, the tag is present, and a colliding re-import is refused.

• Versioned installs (#66's stance, made livable) — install.sh now lands each version side by side at <root>/versions/<v> (its own VERSION + INSTALLED_FROM), with a current symlink tracking the default and $BINDIR/box riding the chain, the way plenty of CLIs manage theirs. New verbs: box versions (lists installs, marks the current default and the running tree), box use <version> (flips the default, converges the PATH symlinks, and asserts the effective result — current must resolve to the asked-for version and the chain's box --version must answer it). Re-running the installer with an installed version is a converging no-op (BOX_REINSTALL=1 replaces that version's tree); a new version installs side-by-side and flips current only when no boxes exist — under existing boxes the flip is refused loudly, naming the boxes (#66: never change versions under a user's boxes; box use keeps the same refusal). A pre-0.7.0 flat tree is migrated in place (two renames, the operator's tree preserved bit for bit), so upgrading from 0.6.0 is seamless; a stale or dangling $BINDIR/box is healed instead of wedging the install; and the installer warns when the other tier's install (/opt/box vs ~/.local) coexists, since PATH order decides which wins.

• A real uninstall — box uninstall [<version>] [--all] [--purge-host] replaces the "rm -rf two paths" prose. One version: refuses the current one (box use off it first). Everything: runs in the safe order — refuses while boxes exist (naming them) unless --purge-host runs teardown-host first — then removes every version, the current and PATH symlinks, and the legacy claudebox crumbs (both name generations), and ends with an absence assert: every removed path is re-checked, and any survivor makes it exit 1 as uninstall INCOMPLETE naming the leftovers (the revoke --purge discipline). teardown-host.sh gains --yes/BOX_YES=1 for automation and now points at box uninstall when done.

• BOX_INSTALL_SOURCE=<dir-or-tarball> — installs from a local tree, bypassing the download. CI's rehearsal job now installs via install.sh itself (proving the installer under review, not a cp -r mimic of it), and ends with an uninstall drill: grant + revoke --purge a throwaway user, teardown-host, box uninstall --all, then assert zero residue — no networks, profiles, ACLs, nft tables, systemd units, files or symlinks.

• test/cli.sh drives real installs — still dependency-free, non-root, no daemon: BOX_INSTALL_SOURCE + throwaway BOX_HOME/BOX_BIN roots and a fake incus on PATH ($FAKE_BOXES) turn layout, chain, no-op/converge, reinstall, side-by-side upgrade, the three #66 refusals (install flip, use, uninstall — boxes named), flat-tree migration, symlink healing, single-version and zero-residue uninstalls, and the INCOMPLETE scream into driven tests instead of greps (154 checks).

Changed

• Thin templates — box mints, rig converges (#81, companion rig#31) — the tenant content that lived in claude/codex/grok's cloud-init (the agent CLI installs, docker, node, the per-template agent-context heredocs) moves to rig's bootstrap roles, where it is convergent, idempotent and testable end to end instead of parse-only YAML. What remains per template is a thin, creds-free seed: the tenant user, tmux (#65), and rig preinstalled — nothing that joins a tailnet or admits credentials. The #80 agent-context guard ("never run box setup-host or the drill inside a box") now lives once, in rig's roles, not copy-pasted per template. The template test sweep grew the contract's teeth: per-template seed asserts (user matches, rig pinned via both tokens) and fail-closed absence greps over effective cloud-init lines — no agent CLI, no docker, no tailscale/authkey/ssh, no write_files heredocs — so tenant content cannot quietly grow back.

Fixed

• revoke --purge re-checks the incus-user state — the purge removed /var/lib/incus/users/<uid> without ever asserting its absence, the one path its own absence block did not cover; and the stat now rides $SUDO test -d (/var/lib/incus is not traversable by a non-root admin, so a bare [ -d ] answered "absent" for a directory that was there).
• A wedged $BINDIR/box no longer blocks installing — the old no-op-if-installed check keyed off the symlink's existence OR the tree's, so a stale symlink (or a half-removed tree) could fake "already installed" forever. Installed-ness is now judged from versions/<v> itself; symlinks are converged with ln -sfn, never trusted as the signal.

0.6.0 — 2026-07-18

Added

• The restricted tier: multi-user hosts (#74, redesigning #72) — an admin runs box grant <user> and that user gets their own boxes on the same hardened boxnet, seeing nobody else's; box revoke <user> takes it back (--purge deletes their world, and asserts the absence). The tier rides incus-user, whose defaults miss box's contract three measured ways (Debian 13 / Incus 6.0.4): a private unhardened NAT bridge per user, snapshots blocked, the box-net profile invisible — so grant is an idempotent convergence: project narrowed to boxnet and only boxnet (listing the private bridge too, the obvious fix, would keep an unhardened network one --network flag away), snapshots allowed, the shipped profile installed into their project. box_tier() (live credentials, argless id -nG) drives the tier-aware surface: expose refuses honestly before any daemon call, setup-host and doctor answer at the caller's tier. Rehearsed end-to-end by drill/multiuser.sh (criteria a–n: confinement, lifecycle, cross-user visibility, name collisions, the in-box isolation contract, escape hatches, re-sync survival, revoke incl. the live-session case) — 54/54 on the design host (container and VM mode), including the raw-attach scoped-guarantee measurement and both grant-failure injections demanded by #75's review.
• CI runs the multi-user rehearsal on a real Incus — a second rehearsal job stands up the full stack on the runner (setup-host, doctor, then multiuser.sh --container), so every PR proves the tier's semantics against a live daemon, not a mock. The VM trust boundary itself remains a real-hardware ritual, like the full drill.
• Global / root install (#71) — run as root, box installs once to /opt/box (world-readable) with the box symlink on /usr/local/bin, so every operator on a shared host runs the same tree. Per-user installs are unchanged ($HOME/.local); BOX_HOME/BOX_BIN still override. A per-user tree under /root is 0700 and unreadable to everyone else — the whole fleet got command not found — so the root branch lands in a system location and chmod -R a+rX's it (read for files, +search on dirs), guarded on root. This unblocks "rig installs box" (rig#24's box role).
• CI + a test suite — .github/workflows/ci.yml (a check job: globstar shellcheck -x over bin/* **/*.sh, then bash test/cli.sh) and test/cli.sh, dependency-free and runnable by a non-root user with no Incus. It exercises the install.sh DEST/BINDIR branch functionally (both tiers + BOX_HOME/BOX_BIN overrides), the CLI contract, and grep-guards the daemon-gated invariants and tmux in every template — the box was the repo with "no tests and no CI".

Fixed

• box restore never worked against Incus 6 — the command table dispatched incus restore, a subcommand that does not exist (Incus 6 spells it incus snapshot restore), so every restore died on "unknown command". Found by #74's rehearsal exercising the full lifecycle as a restricted user; fixed for every tier, and the rehearsal + a grep-guard in test/cli.sh now hold it.

• box tmux works on every template (#65) — box tmux runs tmux new-session inside the box, but the templates did not install tmux, so it failed with tmux: command not found. tmux is now in each template's cloud-init package list (blank/claude/codex/grok).

• box setup-host finishes in one run (#63). When it had to add you to incus-admin it stopped there and told you to re-login and re-run — an exit 0 that reported success having built none of the stack: no boxnet, no ACL, no box-net profile, no firewall. It now re-execs itself under sg incus-admin and completes in that one invocation. The membership check was also asking the wrong question: id -nG "$USER" reads the group database, which lists the group the moment usermod returns, so a same-session re-run passed the check with credentials that still lacked the group and died further down on a bare permission error from incus. Argless id -nG asks the process what it actually holds.

• setup-host works as root, with or without sudo — every privileged call was a hardcoded sudo, so on a minimal root image (no sudo package) it died on sudo: command not found before doing anything. Privilege is now resolved once: nothing at UID 0, sudo otherwise, and a clear error if neither is possible. This is what made install.sh's root path real rather than nominal.

• setup-host grants incus-admin to the human, not to root — under sudo install.sh it would have added root to the group: a no-op (UID 0 opens the socket regardless) that also left the actual user locked out of their own boxes. It now derives the login user from SUDO_USER.

• box-firewall.service now reports its state honestly — the unit is Type=oneshot and was missing RemainAfterExit=yes, so it went inactive (dead) the instant it succeeded: a host whose isolation was perfectly live read as one whose firewall unit had died. drill.sh sends you to systemctl status box-firewall to diagnose exactly that, and setup-host.sh's own comment already asserted the unit "is RemainAfterExit" — it was not. Found by running the drill on a real host and mistrusting the green: nft list table bridge box showed the drop live while the unit read dead. restart was and remains correct either way.

• setup-host's apt calls can no longer hang — a fresh cloud image has apt-daily/unattended-upgrades holding the dpkg lock, and a plain apt-get install waits on it silently and indefinitely. Now bounded (DPkg::Lock::Timeout=300) and non-interactive, which matters because install.sh runs it with nobody watching.

Changed

• drill.sh proves the new contract instead of masking it — the drill ran setup-host itself right after installing, so the stack existed by its own hand and a run passed identically whether or not install.sh had done a thing; a fresh run converged the stack three times, while the messages still described the pre-#63 "first pass may only add you to the group" behaviour. It now asserts the post-install stack in-group before touching the host, and runs setup-host exactly once more — after the clean, which deliberately unsets dns.mode and so has to be converged back. DRILL_OWNS_SETUP=1 hands sequencing back to the drill. Pre-setup tripwires now read before install.sh, since that is what triggers setup now.
• install.sh asks, sets up the host, and no-ops on re-run (#64) — it now prompts "Install box?", then on a fresh host installs the tree and asks a second question, "Set up this machine as a box host now?", running the whole isolation stack if you say yes (previously it only printed a warning and left you a command, so the install reported success and box new died on a host with no Incus). Prompts read /dev/tty, since under curl | bash the script itself is stdin; BOX_YES=1 answers yes unattended (required where there is no terminal), BOX_SKIP_SETUP_HOST=1 declines the host-setup step.
• install.sh never overwrites an existing install — if box is already installed it says so and changes nothing, so a stray re-run can no longer clobber a working tree or rebuild the host stack under live boxes. Upgrading is explicit: uninstall (rm -rf ~/.local/share/box ~/.local/bin/box, boxes preserved first) and install fresh. This replaces the earlier version-diff refusal with a simpler rule that dissolves the same class of errors. The version-aware upgrade that migrates boxes instead is #67; a portable box export so a box survives its own deletion is #70.

0.5.0 — 2026-07-15

The release the project was renamed in: the repo is heavy-duty/box, matching the CLI it ships. Everything legacy-facing is honored forever — the user.claudebox=1 tag, the .claudebox/ runbook folder, the old symlink the installer retires — but nothing current carries the old name.

Added

• codex and grok templates — OpenAI Codex CLI and xAI Grok CLI boxes, creds-free like every template. The template mechanic (image + user + resources, never a network or a security.* key) now has three tenants beside blank, and the drill mints all of them cold.
• box expose <box> <port> [<host-port>] — a deliberate, loopback-only door to a port inside a box, for seeing a dev server in your browser. The listen side is always the host's 127.0.0.1 (no flag to widen it), the door is per-port, --list/--remove manage it, and box info shows open exposures — a box with a hole says so.
• Inline resource overrides on new — --cpu <n> --memory <size> --disk <size> (#57). Resolution most-specific-first: flag > BOX_CPU / BOX_MEMORY / BOX_DISK environment (the scripting form) > template box.env > defaults. Values pass to Incus verbatim; resources are all a flag can touch. --from refuses them — a clone carries its source's resources.
• Host lifecycle as verbs — box setup-host, box teardown-host, and box migrate-host, which re-homes pre-0.4.0 boxes onto the current stack (--box <n> / --all-boxes, authed state preserved) and retires the legacy bridge once empty (--retire-legacy).
• The .box/ recipe convention — the agent-facing runbook folder a repo can ship, renamed from .claudebox/ (both spellings read).

Fixed

• VM mints no longer hang at GRUB — Incus defaults VMs to Secure Boot on, and a cloud image whose shim the host's OVMF doesn't trust dies with "bad shim signature" forever. Boxes now launch with security.secureboot=false; the VM boundary, not boot attestation, is the box threat model.
• box expose actually delivers packets — a trilogy of drill-found absences: the NAT proxy needs the box's boxnet lease pinned as a static ipv4.address (Incus resolves connect=0.0.0.0 against device config, not the lease); a loopback-sourced packet needs route_localnet plus a masquerade on the bridge to leave the host and be answerable; and the box's replies need a ct state established,related accept ahead of the host firewall's input drop, which was eating them statelessly. Boxes still cannot initiate toward the host — a box-originated SYN is a NEW flow.
• Firewall rules now converge on upgrade — box-firewall.sh rebuilds its chains every run (add + flush + re-add) instead of skipping when they exist, which had pinned every host to the rule set of the release that first ran there.
• Failed mints tell you why — cloud-init failures print the box's own log excerpts and leave the box up to inspect; a mint that never boots names the likely cause (corrupt image, Secure Boot, GRUB hang) and ships a sanitized console dump; the installer asserts it landed the ref it was asked for.
• grok installs the binary it actually ships — the installer was read, not guessed at, and the CLI lands on the non-interactive PATH (same fix class as codex).

Changed

• Debrand complete — env vars, install dir, docs, template descriptions and the README all say box; the install URL is heavy-duty/box (GitHub redirects the old one, BOX_REPO overrides).
• The drill grew from 47 to 84 checks — the expose door opened, exercised and shut (with the contract re-probed around it), every template minted cold, a faithful pre-0.4.0 box re-homed through migrate-host, and the inline resource flags asserted (including their precedence over the environment).