box/docs/plans/2026-07-17-staging-template.md

staging template Implementation Plan

Spec: issue #68. Companion: heavy-duty/rig#22 (rig bootstrap workload, implemented separately in the rig repo). Steps use checkbox (- [ ]) syntax for tracking.

Goal: A server-class staging template so staging VMs (registered in the control plane as servers, reachable tailnet-only) are minted by box instead of by a hand-rolled incus launch in a private infra repo. The template ships docker + rig preinstalled and nothing else; the operator runs box shell → sudo rig bootstrap workload inside, and rig — not box — hardens sshd, joins the tailnet, and holds the auth key in process memory.

Why box's isolation stack needs zero changes: the guest joins the tailnet itself, outbound. The host-side stack (boxnet ACL, port isolation, box-firewall, loopback-only expose) only ever sees allowed outbound UDP. Isolation becomes the feature: the staging box still cannot reach the LAN, the host, or a sibling box — it is reachable only over the tailnet, which is exactly the staging posture.

Architecture: one new data-only template directory (templates/staging/), two new keys in the box.env allowlist (BOX_REQUIRE_VM, BOX_AUTOSTART) honored by cmd_new in bin/box, and a design-doc section. No new commands, no new flags, no dependency changes.

Non-goals

• No changes to boxnet, the box-isolate ACL, box-firewall, or expose — the whole point is that none are needed.
• No credential injection — no TS_AUTHKEY, no ssh keys, nothing. The creds-free contract is untouched; rig owns the join, inside the guest.
• No tailscale and no openssh-server in the template — rig installs both at bootstrap time, so box ships neither.
• No control-plane/Coolify awareness (that is cast's job, out of scope).
• No agent tooling in the box: no ~/.claude, no agent-context file — this is a server, not an agent devbox.

Global constraints

• templates/staging/ is data-only: a box.env (parsed against the allowlist, never sourced) and a user-data.yaml (passed to Incus verbatim). Templates still cannot touch the network or a security.* key.
• The two new keys are optional and absent from every other template; existing templates mint exactly as before, and the allowlist still rejects unknown keys.
• BOX_REQUIRE_VM refuses both the silent container fallback (no /dev/kvm → exit 1, it went wrong) and an explicit --container (exit 2, you asked wrong), per the existing exit-code contract.
• boot.autostart=true is stamped only when BOX_AUTOSTART is set — absent on every other template's boxes. Clones inherit it via incus copy, which keeps all non-volatile config keys (verified in Incus's InstanceIncludeWhenCopying; same mechanism the user.* stamps already rely on — audit B2), so no clone-path code is needed.
• Match the repo's disciplined-bash style; minimal diff; conventional commits (type(scope): subject).

---

Task 1: BOX_REQUIRE_VM + BOX_AUTOSTART in bin/box

Files: modify bin/box only.

• load_template(): initialize T_REQUIRE_VM=""; T_AUTOSTART="" and accept BOX_REQUIRE_VM / BOX_AUTOSTART in the key allowlist. Update the "image, user and resources, nothing else" phrasing where it enumerates the allowlist (the function's header comment, the unknown-key error, and the new/templates help prose) — there is still no key for a network or a security.* flag, on purpose.
• cmd_new (fresh-mint path): after m="$(pick_mode)", if the template set BOX_REQUIRE_VM and the effective mode is not vm: usage_error when --container was asked for explicitly, die (naming /dev/kvm) when the host fell back. No silent container fallback for a server-class template.
• cmd_new (fresh-mint path): when the template set BOX_AUTOSTART, append --config boot.autostart=true to the launch arguments — the same per-instance mechanism as limits.cpu. The --from clone path needs nothing: incus copy carries the key (see Global constraints).
• Commit: feat(new): BOX_REQUIRE_VM and BOX_AUTOSTART template keys

Task 2: the staging template

Files: create templates/staging/box.env, templates/staging/user-data.yaml.

• box.env, following the existing templates' format and header-comment voice: BOX_DESCRIPTION (server-class staging VM: docker + rig preinstalled; converge with rig bootstrap workload inside, then register in the control plane), BOX_IMAGE="images:debian/13/cloud", BOX_USER="ops", BOX_CPU="4", BOX_MEMORY="8GiB", BOX_DISK="100GiB" (build-sized: the control plane builds on the target), BOX_REQUIRE_VM="1", BOX_AUTOSTART="1".
• user-data.yaml, modeled on the claude template but server-minimal: user ops (NOPASSWD sudo, lock_passwd: true), curl + ca-certificates, docker via get.docker.com (the mechanism the claude template uses), and rig preinstalled via its installer (curl -fsSL …/rig/main/install.sh | bash, with HOME=/root pinned — cloud-init's runcmd does not guarantee HOME, and rig's installer derives its install dir from it: as root it lands in /root/.local/share/rig with a /usr/local/bin/rig symlink, which is what we want since rig runs as root). A comment states that tailscale, openssh-server and every credential are deliberately absent — rig installs those at bootstrap time. No ~/.claude, no agent-context file.
• Commit: feat(templates): staging — server-class VM, docker + rig, creds-free

Task 3: design-doc amendment

Files: modify docs/box-design.md.

• New section (after Isolation, matching the doc's voice): the isolation guarantee is "no inbound via the host's network position"; a guest can deliberately join an overlay network (tailnet) from inside and invite management in over its own outbound tunnel; the staging template is the sanctioned server-class use of that, layered as box mints / rig converges (inside the guest) / cast registers; and the snapshot-before-join rule — clone from a pre-rig bootstrap snapshot, because a post-join clone duplicates the source's tailnet identity.
• Commit: docs(design): server-class boxes — overlay joins and snapshot-before-join

---

Test plan

No Incus in the implementation environment, so runtime minting is not exercised here — the acceptance criteria in #68 (box new --template staging mints a VM on a KVM host, refuses on a non-KVM host, rig bootstrap workload succeeds inside) are exercised on a real host. Static gate, all of which must pass before merge:

• bash -n bin/box — parses.
• shellcheck bin/box — no new findings against main.
• Both templates/staging/*.yaml / all templates' user-data.yaml parse as YAML (pyyaml).
• Grep assertions: BOX_REQUIRE_VM/BOX_AUTOSTART appear in the allowlist; boot.autostart is stamped only under the BOX_AUTOSTART guard; no template other than staging sets either key.