# rig `bootstrap staging` Implementation Plan > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. **Goal:** Add a `staging` bootstrap role alongside `control-plane` / `workload` / `runner` — the host archetype for a machine whose job is to **host staging VMs**: Incus VMs minted by the `box` CLI (heavy-duty/box) from its `staging` template, each later converged from *inside* with `rig bootstrap workload` and registered in the control plane as its own server. **Why this shape:** the host and its guests sit on opposite sides of a trust boundary. The guests are servers the control plane manages; the **host is not** — it must never carry `tag:server`, and the fleet has already been bitten once by a host that wrongly did. The role is deliberately minimal host plumbing: hardening, tailnet join (key minted with `tag:local`), hostname — and **nothing about Incus or box**. box's own `setup-host` owns Incus configuration; two tools converging the same daemon is drift by construction, so rig only *points* at box's installer in its closing log. The guest side needs zero rig changes — `rig bootstrap workload` already is the staging-box role. **Architecture:** `staging` joins the existing role case in `commands/bootstrap.sh`; no new files, no new flags. Since issue #16 / PR #20, the tailnet tag is **not a rig argument** — the pre-auth key carries its tags and rig asserts on the tag control actually *granted* (`.Self.Tags`), post-join and on every re-run. So the role's tag policy lands in `verify_effective_tag`, exactly where the `runner` policy lives: role `staging` **refuses an effective `tag:server`** (die, exit 1 — a runtime refusal, not a usage error). The `/dev/kvm` advisory and the box next-step pointer live in the execution path; argument validation stays pure and root-free. **Tech Stack:** bash only, shellcheck, existing `ci.yml` (globstar shellcheck + `bash test/cli.sh`) — no workflow change needed. ## Non-Goals - **No Incus, no box install** — box's `setup-host` is the single owner of the Incus daemon's configuration. rig prints a pointer, nothing more. - **No VM provisioning** — minting boxes is box's job (`box new --template staging`, companion issue heavy-duty/box#68). - **No control-plane/Coolify API usage** — guests register themselves via the existing workload flow. - **No `dev` role** — a dev-box host role is anticipated (same plumbing, honest name) but explicitly out of scope here. ## Global Constraints - `#!/usr/bin/env bash` + `set -euo pipefail`; log prefix `rig-bootstrap:` via the existing `log`/`warn`/`die` helpers. - Exit codes: `2` = usage/argument error, `1` = runtime refusal. **All argument validation runs BEFORE the root check** so error paths are testable as non-root. - The tag policy asserts the **effective** tag, never a requested one — there is no `--ts-tag` to refuse anymore (it died in PR #20; passing it exits 2 with a pointer at the key). The issue's original "refuse `--ts-tag tag:server`" acceptance is therefore satisfied at the stronger, post-join layer, same as `runner`. - `/dev/kvm` absence is a **warning, not a failure** — the role is rehearsed in containers where `/dev/kvm` legitimately isn't there. - Convergent: a second run changes nothing and exits 0. - shellcheck-clean exactly as CI runs it (`shopt -s globstar; shellcheck -x bin/* **/*.sh`); `bash test/cli.sh` green as non-root. - Keep the diff minimal — no drive-by refactors. (One deliberate exception: `bin/rig`'s bootstrap usage line still advertises the removed `--ts-tag` flag and the old `tag:ci` default — stale since PR #20. It gets corrected in the same breath as adding `staging` to the role list, because shipping a new role into a help text that lies about the flag surface would be worse than the drive-by.) --- ### Task 1: role wiring in `commands/bootstrap.sh` + dispatcher usage + tests **Files:** - Modify: `commands/bootstrap.sh` (role case, effective-tag refusal, `/dev/kvm` advisory, closing next-step log, usage heredoc) - Modify: `bin/rig` (bootstrap usage line: role list + stale-flag correction) - Modify: `test/cli.sh` (bootstrap section additions) **Behavior contract, in file order:** 1. Usage heredoc: role list becomes ``; one added sentence: staging hosts box-minted staging VMs, its key should be minted with `tag:local`, and it refuses `tag:server` — the host is never managed by the control plane; its guest VMs are. 2. Role case arm: `control-plane|workload|runner|staging) shift ;;` and both error messages (`role required`, `unknown role`) name the four roles. 3. `verify_effective_tag`: after the `runner` refusal, the `staging` one — same shape (`grep -qx 'tag:server'` against the effective tags), message `role staging joined with tag:server ...` naming the repair (mint a `tag:local` key), rationale comment: hosts are never managed by the control plane, their guest VMs are; the fleet has been bitten by a host wrongly carrying `tag:server`. `die` with default status → exit 1. 4. Guards section (execution path, after the root check): when role is `staging` and `/dev/kvm` is absent, `warn` — the host exists to run VMs, but a container rehearsal legitimately has no `/dev/kvm`, so this must not fail. 5. Closing log: `staging` branch pointing at the box CLI — install box, run `box setup-host` to prepare Incus, then `box new --template staging`. 6. `bin/rig` usage: `bootstrap [--hostname ]`; drop the stale `[--ts-tag ]` and `tag:ci`-default sentence; say the tag comes from the pre-auth key and that roles `runner` and `staging` refuse `tag:server`. - [ ] **Step 1: Append failing tests** In `test/cli.sh`, bootstrap section: ```bash check "bootstrap: staging + removed --ts-tag exits 2" 2 "comes from the pre-auth key" \ "$ROOT/commands/bootstrap.sh" staging --ts-tag tag:server # The staging tag:server refusal rides the EFFECTIVE tag, inside # verify_effective_tag — a path that needs a real tailnet, so it belongs to the # rehearsal. What the harness CAN prove is that the refusal exists in the shipped # script: grep the die message, so a deleted guard cannot ship green (the same # reason the runner-install repo guard is grepped below). check "bootstrap: staging effective-tag refusal is present" 0 "" \ grep -q "role staging joined with tag:server" "$ROOT/commands/bootstrap.sh" ``` and in the existing non-root block: ```bash check "bootstrap: staging role parses, refuses non-root" 1 "must run as root" env TS_AUTHKEY=x "$ROOT/commands/bootstrap.sh" staging ``` The existing `unknown role exits 2` (potato) check already covers the still-fails-usage path and stays untouched. - [ ] **Step 2: Run tests to verify the new ones fail** Run: `bash test/cli.sh` Expected: the staging checks FAIL (`unknown role: staging` → wrong exit/output for the first and third; missing die message for the grep); everything existing stays green; harness exits 1. - [ ] **Step 3: Implement the role** Per the behavior contract above. - [ ] **Step 4: Run tests to verify they pass** Run: `bash test/cli.sh` Expected: all checks pass, exit 0. - [ ] **Step 5: shellcheck + syntax** Run: `shopt -s globstar; shellcheck -x bin/* **/*.sh` (exactly CI's invocation) and `bash -n` on each edited script. Expected: exit 0, no findings. - [ ] **Step 6: Commit** ```bash git add commands/bootstrap.sh bin/rig test/cli.sh git commit -m "feat(bootstrap): staging role — the host archetype for box-minted staging VMs" ``` --- ### Task 2: README roles documentation **Files:** - Modify: `README.md` (bootstrap section: heading role list, example block, the roles paragraph) - [ ] **Step 1: Write it** Content requirements (in the README's existing voice): - Heading/example gain `staging` (`rig bootstrap staging --hostname my-vm-host`). - One honest paragraph in the roles discussion: `staging` is the box that *hosts* staging boxes — Incus VMs minted by the `box` CLI, each converged from inside with `rig bootstrap workload` and registered in the control plane as its own server. Mint its key with `tag:local`; the role **refuses an effective `tag:server`** — the host is never managed by the control plane, its guests are. rig deliberately installs no Incus and no box (box's `setup-host` owns that); it points there when done. - [ ] **Step 2: Full local gate** Run: CI's shellcheck invocation + `bash test/cli.sh`. Expected: silent shellcheck; all tests pass. - [ ] **Step 3: Commit** ```bash git add README.md git commit -m "docs: README section for the staging bootstrap role" ``` --- ## Test Plan - **Harness (`bash test/cli.sh`, non-root, network-free):** staging parses and reaches the root check (exit 1 `must run as root`); staging + the removed `--ts-tag` dies at arg validation (exit 2, message points at the key — proving validation precedes the root check); the effective-tag refusal message is present in the script; unknown roles still exit 2. - **CI:** unchanged `ci.yml` covers the edits (globstar shellcheck + harness). - **Rehearsal (manual, out of harness):** pristine Debian box → `rig bootstrap staging` with a real single-use `tag:local` key → hardened sshd drop-in, tailnet join, hostname `staging`, `/dev/kvm` warning absent on real hardware, closing log points at box; second run is a no-op. A `tag:server` key must die post-join with the staging refusal. ## Addendum (2026-07-17, written before implementation) Issue #22 predates the merge of PR #20 (issue #16: the tag comes from the key). Its acceptance criterion "`rig bootstrap staging --ts-tag tag:server` exits 1 with a refusal, before the root check" names a flag that no longer exists — `--ts-tag` now dies (exit 2) for every role, before the root check, pointing at the key. The staging `tag:server` policy therefore lands where the runner's did: on the **effective** tag in `verify_effective_tag`, exit 1, which is the strictly stronger check (it guards the tag the key actually granted, not the one rig hoped for). This plan is the up-to-date statement of the work.