Snapshot 'pristine' at mint, before the rig bootstrap hook #104

New issue

Closed

opened 2026-07-19 17:35:37 +00:00 by dan-claude-bot · 0 comments

dan-claude-bot commented

2026-07-19 17:35:37 +00:00

(Migrated from github.com)

Snapshot `pristine` at mint, before the rig bootstrap hook

Child of heavy-duty/rig#62. This is the one that actually delivers "back to
pristine Debian".

The gap

cmd_new's fresh-mint branch runs launch → wait_agent → cloud-init status --wait → the rig hook at bin/box:1121. At the moment cloud-init
finishes and before rig converges anything, the guest is pristine Debian
plus box's seed. That is the exact state heavy-duty/rig#62 wants back, it
exists for a few seconds on every mint, and nothing captures it.

Capturing it is close to free. cmd_snapshot (bin/box:1295-1299) is three
lines, takes no lock and does not stop the instance, and the storage backend
is btrfs by deliberate design (host/setup-host.sh:261-298) — CoW, so the
snapshot costs kilobytes until the guest diverges.

Proposal

Take a snapshot named pristine immediately before the
[ -n "$T_BOOTSTRAP_ROLE" ] block at bin/box:1119. Then:

box restore agent1 pristine

is a complete answer for every tenant role, because everything
bootstrap-tenant.sh does — docker, node, the agent CLI, the context file,
the role marker — is box-local and file-shaped.

Worth considering alongside: a second bootstrapped snapshot after a
successful hook, so an operator can get back to a converged-but-untouched
box without paying a re-mint. Cheap on CoW, and it is the state people
actually want more often than truly-pristine.

Decisions to make

Default on, or --snapshot-pristine? Default on, I think — the cost
is near-zero on btrfs and the value only exists if it is already there
when you need it. But on a dir-backend host (the documented fallback at
host/setup-host.sh:294) it is a full multi-GB copy, so the mint should
probably detect the driver and skip with a warning rather than silently
double every mint's disk cost.
Naming. pristine is what heavy-duty/rig#56 called it and it is
honest — the guest at that point has had cloud-init but not rig.
Interaction with --from. The clone branch (bin/box:977-990) skips
cloud-init and rig entirely, so there is no pristine moment to capture.
A clone should inherit the source's snapshots or take none; it must not
mint a misleading pristine that is really "whatever the source was".

Note on durability

Snapshots cannot outlive their instance — box rm takes every snapshot with
it (bin/box:73, and docs/plans/2026-07-18-box-export.md:12-13). So this
is an undo, not a backup, and the docs should not let anyone confuse the
two. box export remains the durable path.

# Snapshot `pristine` at mint, before the rig bootstrap hook Child of heavy-duty/rig#62. This is the one that actually delivers "back to pristine Debian". ## The gap `cmd_new`'s fresh-mint branch runs launch → `wait_agent` → `cloud-init status --wait` → the rig hook at `bin/box:1121`. At the moment cloud-init finishes and before rig converges anything, the guest **is** pristine Debian plus box's seed. That is the exact state heavy-duty/rig#62 wants back, it exists for a few seconds on every mint, and nothing captures it. Capturing it is close to free. `cmd_snapshot` (`bin/box:1295-1299`) is three lines, takes no lock and does not stop the instance, and the storage backend is btrfs by deliberate design (`host/setup-host.sh:261-298`) — CoW, so the snapshot costs kilobytes until the guest diverges. ## Proposal Take a snapshot named `pristine` immediately before the `[ -n "$T_BOOTSTRAP_ROLE" ]` block at `bin/box:1119`. Then: ```sh box restore agent1 pristine ``` is a complete answer for every tenant role, because everything `bootstrap-tenant.sh` does — docker, node, the agent CLI, the context file, the role marker — is box-local and file-shaped. Worth considering alongside: a second `bootstrapped` snapshot *after* a successful hook, so an operator can get back to a converged-but-untouched box without paying a re-mint. Cheap on CoW, and it is the state people actually want more often than truly-pristine. ## Decisions to make - **Default on, or `--snapshot-pristine`?** Default on, I think — the cost is near-zero on btrfs and the value only exists if it is already there when you need it. But on a `dir`-backend host (the documented fallback at `host/setup-host.sh:294`) it is a full multi-GB copy, so the mint should probably detect the driver and skip with a warning rather than silently double every mint's disk cost. - **Naming.** `pristine` is what heavy-duty/rig#56 called it and it is honest — the guest at that point has had cloud-init but not rig. - **Interaction with `--from`.** The clone branch (`bin/box:977-990`) skips cloud-init and rig entirely, so there is no pristine moment to capture. A clone should inherit the source's snapshots or take none; it must not mint a misleading `pristine` that is really "whatever the source was". ## Note on durability Snapshots cannot outlive their instance — `box rm` takes every snapshot with it (`bin/box:73`, and `docs/plans/2026-07-18-box-export.md:12-13`). So this is an *undo*, not a backup, and the docs should not let anyone confuse the two. `box export` remains the durable path.

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference: heavy-duty/box#104

No description provided.