# Snapshots

https://instabox.sh/docs/snapshots.md

Save a machine once, start new ones from it.

A snapshot holds a machine's installed software and its files under `/data`: home, workspace and saved sign-ins (gh, Claude, Codex, git, SSH). It does not hold memory or running processes. Snapshots are private to you.

### Save one, start from it
```
instabox snapshot save dev --name dev-base
instabox create --name dev2 --snapshot dev-base
instabox snapshot ls
```
In the dashboard: **Save snapshot** in a machine's menu, then **New machine from it**, now or later on the **Snapshots** page.

### Fork a machine
```
instabox fork dev --name dev2
instabox fork dev --name try --count 3 --json
```
`fork` (or `clone`) copies a running or stopped machine into one new machine (or `--count`, up to 5, named `try-1` to `try-3`) with the same template and size, and waits until they run. The server copies the disks on the machine's host and boots the copies, in a few seconds and without a snapshot (`POST /v1/machines/{id}/fork`); memory and running programs are not copied. With an older server that has no native fork, or with `--keep-snapshot`, it saves a snapshot, creates the copies from it, then deletes the snapshot (also on error or Ctrl-C) unless `--keep-snapshot`. A suspended machine is copied neither way: resume or stop it first. The source machine is not changed. Each new machine counts toward your plan's machine starts a minute; `fork` waits that out.

### Restore a machine in place
```
instabox restore dev --snapshot dev-base
instabox restore dev --yes --stopped
```
`restore` puts a machine's disks back to a snapshot's, in place: the machine keeps its ID, name, hostname, public port URLs and ssh-config block, so everything that names it keeps working, and everything on its root disk and `/data` since the snapshot is gone, running programs included (it asks first; `--yes` skips that). Without `--snapshot` it restores the snapshot the machine was created from. A running machine is stopped first; then the machine boots the restored disks and the command waits until it runs, or `--stopped` leaves it stopped. Its SSH host keys are new afterwards, so an SSH client that pinned them asks again. A snapshot saved `--root-only`, or whose `/data` is larger than the machine's disk, is refused (grow the disk with `resize` first). The API is `POST /v1/machines/{id}/restore` with `{"snapshotId": "sn_..."}` (`machines:write`); it answers a `restore` operation. To keep the machine as it is and get a copy of the snapshot, use `create --snapshot` or `fork` instead.

### Set up once, reuse everywhere
In the **Playground**, start a machine, install your tools, repos and agent sign-ins in its terminal, then **Save as snapshot**. Every machine you start from it is set up.

### Good to know
- `snapshot save` (CLI and API) saves a **stopped** machine, or a **running** one live where the server has live snapshots on (api.instabox.sh does): a live save keeps the machine running, and that snapshot may leave out data programs have not written to disk yet. A **paused** machine, or a running one on a server without live snapshots, is refused with `409` "stop it first": stop it, then save (files on disk are kept; processes end). The dashboard's **Save snapshot** does that stop for you when a live save is not possible.
- `snapshot save` waits until it is saved; `--no-wait` returns at once.
- `--root-only` saves the installed software only: machines from it start with an empty home and workspace, as do older snapshots that hold installed software only.
- Saving refused because the machine has unsaved changes? Stop it again, then retry.
- `instabox snapshot files dev-base /etc` lists its files without starting a machine.
- Deleting a machine keeps its snapshots; deleting a snapshot does not affect machines made from it.
- Over HTTP: `POST /v1/machines/{id}/snapshots` saves one, `GET /v1/snapshots` lists them, `POST /v1/machines` with `"snapshotId"` starts a machine from one.
- From a Docker image: `instabox snapshot import IMAGE --name N` makes a snapshot of it. See [Custom images](https://instabox.sh/docs/custom-images.md).