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