rig/docs/plans/2026-07-17-host-installs-box.md

# rig `bootstrap host=yes` installs box + runs setup-host — 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:** When `rig bootstrap` converges a VM-host machine (trait `host=yes` —
roles `dev`, `staging`, `workstation`, and `custom --host yes`), it should
**install the `box` CLI globally and run box's own `setup-host`** automatically,
instead of printing `next: install the box CLI and run 'box setup-host'`. This
turns a documented to-do into a real, convergent install step, completing rig#12
(the `dev` role — the Incus claudebox host) and rig#25 (machine classes: the
host class installs box + rig users).

**Why this shape:** a `host=yes` box exists to run guest boxes; a bootstrap that
hardens the OS and joins the tailnet but then hands the operator a manual
checklist has left the machine half-built. The box CLI *is* the host's reason
for existing, so bootstrap finishes the job. But rig must finish it **the same
way `rig users apply` already assumes it happens** — by delegating to box, never
by touching Incus itself.

## The design law this respects

`commands/users-apply.sh` carries the law verbatim: *"rig NEVER installs Incus:
box's setup-host owns the daemon and its group."* Two tools converging one
daemon is drift by construction, and box is the single owner. This change does
**not** weaken that law — it *fulfils* it. rig does not `apt-get install incus`,
does not configure the daemon, does not create the `incus` group. It runs
**box's own global installer** as root; box installs Incus via its `setup-host`.
rig delegates; box owns.

The symmetry is the point: `users-apply` dies on a `host=yes` box whose `incus`
group is absent, pointing at `box setup-host`. After this change, an ordinary
`rig bootstrap dev` is what *makes that group exist* — so the two commands now
close the loop instead of one pointing at a manual step the other assumed.

## Architecture

One block appended to `commands/bootstrap.sh`, after the role-marker write; no
new files, no new flags. It keys off the existing `HOST` trait (so every
`host=yes` shape — preset or `--host yes` override — gets it, and `--host no`
opts a laptop out with zero role logic). The install runs box's raw `install.sh`
piped to `bash` with `BOX_YES=1` in the environment (non-interactive **and**
keeps `setup-host`). Source is pinnable via `BOX_REPO` / `BOX_REF`
(default `heavy-duty/box@main`).

**Tech Stack:** bash only, shellcheck, existing `ci.yml` (globstar shellcheck +
`bash test/cli.sh`) — no workflow change needed; the new code is a `.sh` file
already covered by both jobs.

## Non-Goals

- **No Incus install by rig, no daemon config, no `incus` group creation** —
  box's `setup-host` owns all of it. rig runs box's installer; box owns Incus.
- **No guest provisioning** — minting boxes is box's job (`box new`).
- **No tailnet for guests** — rig#12's constraint: the *host* joins the tailnet
  (done above in the tailscale block); guest boxes never do. box does not join
  the tailnet, so nothing here needs to enforce it.
- **No credentials on the host** — rig#12's constraint: box is creds-free, so
  the delegation introduces none.

## Global Constraints

- `#!/usr/bin/env bash` + `set -euo pipefail`; log prefix `rig-bootstrap:` via
  the existing `log` / `warn` / `die` helpers.
- Runs **only as root**, only after the full bootstrap (root check, sshd
  hardening, tailnet join + tag verification, role-marker write) has succeeded —
  so a box that failed to become what it claims never installs box.
- **Never aborts the bootstrap.** box is the host *extra*; the OS + tailnet core
  is already done and asserted. A missing curl, a dead network, or a box
  installer that errors is a `warn` with a manual-command pointer, never a `die`.
- **Convergent:** box's installer is a no-op once box is installed, so a re-run
  changes nothing.
- 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.

---

## Behavior contract (in file order, `commands/bootstrap.sh`)

After the role-marker write (`install -m 0644 "$MARKER_TMP" "$MARKER"`), before
the closing `log "done — role …"`:

1. **Guard:** `if [ "$HOST" = "yes" ]; then` — the exact guard line, no `&&`
   (distinguishing it from the `/dev/kvm` advisory `if [ "$HOST" = "yes" ] && …`
   up in the guards section).
2. **Pin points:** `BOX_REPO="${BOX_REPO:-heavy-duty/box}"`,
   `BOX_REF="${BOX_REF:-main}"`, and a `BOX_INSTALL_URL` built from them; a
   `BOX_MANUAL` string (`curl -fsSL … | BOX_YES=1 bash`) reused in every pointer.
3. **Opt-out first:** `RIG_SKIP_BOX_INSTALL=1` → `log` the skip with the manual
   pointer, do nothing else. (Rehearsals in containers, offline boxes,
   hand-managed hosts.)
4. **No-curl:** `command -v curl` absent → `warn` with the manual pointer, skip.
5. **Install:** `log` the intent (naming the pinned `BOX_REPO@BOX_REF` and that
   box owns Incus), then `if curl -fsSL "$BOX_INSTALL_URL" | BOX_YES=1 bash;`:
   - success → `log` box installed + host set up, pointer to `box new`;
   - failure (no network, installer error — the pipe fails under `pipefail`) →
     `warn` with the manual pointer. **Never `die`.**

`BOX_YES=1` in the *environment* (not a flag) is load-bearing: it makes box's
installer non-interactive **and** keeps `setup-host`, so the Incus stack is
actually built rather than the CLI merely dropped on PATH. Running as root, box
installs globally to `/opt/box` + `/usr/local/bin`.

The old `if [ "$HOST" = "yes" ]; then log "next: install the box CLI …"` block is
**replaced** by this — the message it printed is now the thing rig does.

---

## The box#71 dependency (ordering / correctness)

The **global, world-readable** install path — box under `/opt/box` with a
`/usr/local/bin` shim readable by every non-root user — depends on **box PR
#71**. Until #71 merges, box's root install lands in `/root`, and non-root users
(the `dev` box's human operator; any `box`-role rig user) cannot reach it. So
this rig step is **correct once box#71 is merged**; before then it installs box
for root but not for the humans who need it.

This is a comment in `bootstrap.sh` and is called out in the PR body. The rig
step itself is right and ships now (it is convergent and delegates correctly);
the *effective* multi-user outcome is gated on box#71. No rig code changes when
#71 lands — box's installer changes where it writes.

---

## Test Plan

### Harness (`bash test/cli.sh`, non-root, network-free)

The install itself needs root, the network, and a real host — none of which the
harness can fabricate — so, exactly like the effective-tag refusals and the
runner repo guard, the shipped script is proven by grepping its load-bearing
pieces:

- **Guarded on host=yes** — the exact guard line (`grep -qxE`) belongs to the
  box block alone.
- **Runs box's installer non-interactively** — `BOX_YES=1 bash` present.
- **Pinnable, default `heavy-duty/box@main`** — `BOX_REPO:-heavy-duty/box`.
- **Opt-out honored** — `RIG_SKIP_BOX_INSTALL` present.
- **rig never apt-installs incus** — a *negative* grep (`grep -nE 'apt-get
  install.* incus'` exits 1 = pass), so the design law cannot silently erode.
- **Ordering** — box install (`BOX_YES=1 bash`) sits *after* the role-marker
  write (`install -m 0644 "$MARKER_TMP"`); compare line numbers, same idiom as
  the `visudo -c` / `sshd -t` ordering asserts, defaults fail closed.
- **Skip/failure keeps a manual pointer** — `prepare Incus` present.
- Existing bootstrap tests unchanged: `dev` / `staging` parse and refuse
  non-root (they reach the root check long before the box block); unknown roles
  still exit 2.

### CI

Unchanged `ci.yml` covers the edits (globstar `shellcheck -x` + `bash
test/cli.sh`). No workflow change.

### Rehearsal (manual, out of harness — the effective-state proof)

Unit tests stop at the script's text; only a real host proves the daemon came
up. On a pristine Debian `host=yes` box (real hardware with `/dev/kvm`, or a
nested-virt VM):

1. `rig bootstrap dev --hostname dev-rehearsal` with a real single-use
   `tag:local` key → hardened sshd drop-in, tailnet join as `dev-rehearsal`,
   role marker `host=yes`, then **box installed and `setup-host` run**.
2. Assert **effective** state, not file existence:
   - `incus info` returns the daemon's info (setup-host built the stack);
   - `getent group incus` exists;
   - as a **fresh user added to the `incus` group** (not root): `box templates`
     lists templates and `incus list` works — the world-readable path (box#71)
     is what makes this succeed for a non-root human.
3. **Convergence:** a second `rig bootstrap dev` run reports box already
   installed and changes nothing; `incus info` unchanged.
4. **Opt-out:** `RIG_SKIP_BOX_INSTALL=1 rig bootstrap dev` skips the install and
   logs the manual pointer; nothing Incus-related is touched.
5. **box#71 gate:** before box#71 merges, step 2's *fresh incus-group user*
   check fails (box lives in `/root`); after it merges, it passes with no rig
   change. This is the acceptance line that must be re-run once box#71 lands.

The `staging` shape is the same box block; rehearsing `dev` exercises it.

## Notes

- rig#12's two hard constraints hold and are commented at the step: the host
  joins the tailnet (guests never do — box doesn't join, fine); no credentials
  on the host (box is creds-free, fine).
- The `users-apply` "absent incus group on host=yes → die pointing at
  setup-host" path stays valid as the fallback for the opt-out / failed-install
  cases; ordinary bootstrap now makes that group exist, closing the loop.