box export: a box's state that survives the box (and the host) #70

New issue

Closed

opened 2026-07-17 15:58:32 +00:00 by claude-bot-andresmgsl · 0 comments

claude-bot-andresmgsl commented

2026-07-17 15:58:32 +00:00

(Migrated from github.com)

Asked for by @danmt on #66, and a prerequisite for the "stop, export, remove every box before you upgrade" flow he wants the installer to enforce:

then file an issue for the export command so the snapshot does survive […] Lets do the fail loudly so you have to manually stop, export, remove every box before you run it again.

The gap

Right now nothing a box holds survives the box:

box snapshot makes an in-box checkpoint. box rm deletes the box and every snapshot it has (box rm --help: "Delete a box and every snapshot it has. This cannot be undone"), so a snapshot cannot outlive its box.
box new --from <box>/<snap> clones to a new box — independent (it is incus copy), so it survives rm of the source, but it still lives on the same host and gets the same stack rebuilt under it. It is not an artifact you can carry off the machine or keep across a teardown.

So the honest instruction today is "copy what you need out by hand (box shell / box exec) before you rm." For the upgrade flow to be safe — down, export, rm, upgrade, re-import — there has to be an export that produces a portable, host-independent artifact.

Shape (starting point, for discussion)

box export <box> [<file>] → a single file (Incus already has the primitive: incus export writes a backup tarball of an instance and its snapshots). Default name <box>-<snapshot-or-live>.tar.gz.
box import <file> [--name <box>] → mint a box from that artifact, re-stamped onto the current stack (re-apply user.box.*, re-run reset_identity so auth state does not silently ride along unless intended).
Decisions to make:
- Does export include all snapshots or just live state? (incus export can do either.)
- Running box: export a live instance, or require box down first for a consistent artifact? Probably require down, or snapshot-then-export.
- Auth/creds: a box carries login state and git creds. Export must either scrub them or shout that they are inside the artifact — this is the same trust boundary reset_identity guards on clone.

Why it blocks the installer flow

#66 makes install.sh refuse to proceed while boxes exist (per your "make sure there are no active boxes that can be potentially lost"). That refusal is only humane if there is a real way to preserve a box first. Until box export exists, the refusal has to tell people to copy data out of the box by hand — which is the honest-but-lossy state we are in. This issue is what upgrades that instruction to "export, keep the file, re-import after."

Related: #67 (version-aware upgrade — the "magical" path that would migrate instead of refusing).

🤖 Generated with Claude Code

Asked for by @danmt on #66, and a prerequisite for the "stop, export, remove every box before you upgrade" flow he wants the installer to enforce: > then file an issue for the export command so the snapshot does survive […] Lets do the fail loudly so you have to manually stop, export, remove every box before you run it again. ## The gap Right now nothing a box holds survives the box: - `box snapshot` makes an **in-box** checkpoint. `box rm` deletes the box **and every snapshot it has** (`box rm --help`: "Delete a box and every snapshot it has. This cannot be undone"), so a snapshot cannot outlive its box. - `box new --from <box>/<snap>` clones to a **new box** — independent (it is `incus copy`), so it survives `rm` of the source, **but it still lives on the same host** and gets the same stack rebuilt under it. It is not an artifact you can carry off the machine or keep across a teardown. So the honest instruction today is "copy what you need out by hand (`box shell` / `box exec`) before you `rm`." For the upgrade flow to be safe — down, export, rm, upgrade, re-import — there has to be an export that produces a **portable, host-independent artifact**. ## Shape (starting point, for discussion) - `box export <box> [<file>]` → a single file (Incus already has the primitive: `incus export` writes a backup tarball of an instance and its snapshots). Default name `<box>-<snapshot-or-live>.tar.gz`. - `box import <file> [--name <box>]` → mint a box from that artifact, re-stamped onto the current stack (re-apply `user.box.*`, re-run `reset_identity` so auth state does not silently ride along unless intended). - Decisions to make: - Does export include **all snapshots** or just live state? (`incus export` can do either.) - Running box: export a live instance, or require `box down` first for a consistent artifact? Probably require down, or snapshot-then-export. - Auth/creds: a box carries login state and git creds. Export must either scrub them or shout that they are inside the artifact — this is the same trust boundary `reset_identity` guards on clone. ## Why it blocks the installer flow #66 makes `install.sh` refuse to proceed while boxes exist (per your "make sure there are no active boxes that can be potentially lost"). That refusal is only humane if there is a real way to preserve a box first. Until `box export` exists, the refusal has to tell people to copy data out of the box by hand — which is the honest-but-lossy state we are in. This issue is what upgrades that instruction to "export, keep the file, re-import after." Related: #67 (version-aware upgrade — the "magical" path that would migrate instead of refusing). 🤖 Generated with [Claude Code](https://claude.com/claude-code)