instabox-snapshots

instabox snapshots: save and load

A snapshot is a saved copy of a box's disks (system files and /data), owned by the box's org: every member of the org can use or delete it. Load it by creating a new box from it; that box joins the snapshot's org. Snapshot disks hold installed software and files only: running processes and memory are not saved (use instabox suspend for that).

Save

instabox snapshot save work --name work-ready --description "deps installed, repo cloned"

A running box is saved live, without stopping it: the snapshot is pending in instabox snapshot ls until its disks finish uploading (--no-wait returns at once, otherwise the CLI waits). Only a ready snapshot can start a box.
Do not stop the box first: stop ends every process in it. A live snapshot is like a clean power cut: what is on disk is kept, what programs hold only in memory is not. Only if the server answers that this box must be stopped, or if a program must write its data to disk first (a database mid-write), run instabox stop work, save, then instabox start work.
--root-only saves just the system files (no /data, so no HOME and no workspace): smaller, and a box started from it gets empty /data.
A disk snapshot includes credential files written by applications, tool sign-ins, and historical Vault files. The managed Secret environment lives on tmpfs, but applications can copy real env values to disk. Paused boxes also keep credentials in process memory, though a snapshot does not save memory. Do not describe snapshots as credential-free. Review copied credentials and rotate upstream when required before sharing or retaining them.
Pick names that say what is inside (node20-playwright, api-db-seeded). Snapshot names are 1–63 characters of a–z, 0–9 and -, start with a letter or digit, and must be unique within the org.

Load

instabox snapshot ls                                    # your snapshots: id, name, root/data size, source, status
instabox create --name work2 --snapshot work-ready      # waits for the new box to run
instabox exec work2 -- ls /data/home                    # same disks as when saved

--snapshot takes a snapshot name or its sn_... id (older ones start with im_ and still work). The new box always joins the snapshot's org (naming another org is refused), and keeps the snapshot's Linux user unless --user names another.

Look inside without starting anything

instabox snapshot files work-ready /etc                 # list a directory of the system files
instabox snapshot files work-ready /etc/os-release      # print a text file

This reads the snapshot's system files only; /data (and HOME) are not browsable here. To check files under /data, load the snapshot into a box and use instabox exec.

Copy a box

There is no direct copy: save a snapshot of it, create the new box from that, and delete the snapshot if you will not use it again.

instabox snapshot save work --name work-copy
instabox create --name work2 --snapshot work-copy
instabox snapshot rm work-copy                          # optional; work2 is not affected

The copy gets a new sandbox identity and the selections in its creation request. Without Secret selection flags it keeps the existing Vault behavior and does not enroll in org Secrets; it does not inherit the source's explicit grants or exclusions. To disable new delivery from both stores, use:

instabox create --name work2 --snapshot work-copy --no-vault --secrets none --env-secrets none

To provide a database credential, select its env Secret explicitly with --env-secrets DATABASE_URL. At creation that flag alone also selects all org proxy Secrets; add --secrets none or specific names to narrow proxy access. Copied placeholders cannot authorize use as the source sandbox. New selections do not erase real credentials already present in copied files; a new proxy identity does not make those files safe to share.

Clean up

instabox snapshot rm work-ready

Snapshots count toward the org's snapshot and storage limits (instabox usage). Delete ones you no longer need.

Typical agent loop

instabox create --name job --snapshot <base> (it pauses by itself after 30 idle minutes)
Work with instabox exec job -- ...
When the setup is worth keeping: instabox snapshot save job --name <base>-v2 (no need to stop it; wait for ready)
instabox rm job when done.