> ## Documentation Index
> Fetch the complete documentation index at: https://instabox.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Snapshots

> Save a machine once, start new ones from it, fork it, or restore it in place.

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.

```bash theme={null}
instabox snapshot save dev --name dev-base
instabox create --name dev2 --snapshot dev-base
instabox snapshot ls
```

In the dashboard, choose **Save snapshot** in a machine's menu. Then choose **New machine from it**,
now or later on the **Snapshots** page.

> [!TIP]
>
> Set up once, reuse everywhere. In the **Playground**, start a machine and install your tools, repos,
> and agent sign-ins in its terminal. Then choose **Save as snapshot**. Every machine you start from it is set up.

## Save a running or stopped machine

* A **stopped** machine saves as is.
* A **running** machine is saved live. It keeps running, and the snapshot may leave out data programs
  have not written to disk yet.
* A **paused** machine is refused with `409`, and it cannot be stopped while paused. To save it,
  resume it, then save it live (or, where live saves are off, resume it, then stop it, then save).
  Files are kept either way.

`snapshot save` waits until the snapshot is saved, and `--no-wait` returns at once. `--root-only` saves
only the installed software, so machines from it start with an empty home and workspace.

## Fork a machine

```bash theme={null}
instabox fork dev --name dev2
instabox fork dev --name try --count 3 --json   # try-1 to try-3
```

`fork` (or `clone`) copies a running or stopped machine into one new machine, or up to 5 with `--count`.
The copies have the same template and size, and `fork` waits until they run. The server copies the disks on the
machine's host and boots the copies in a few seconds, without a snapshot. Memory and running programs
are not copied, and the source machine is not changed. What a fork keeps and when it uses a snapshot:
[Fork](https://instabox.sh/docs/machines/fork.md).

> [!NOTE]
>
> A paused machine cannot be forked, or stopped: resume it first. Each new machine counts toward your plan's
> machine starts a minute, and `fork` waits that limit out. Each one also runs, so when your workspace cannot
> run `--count` more machines, `fork` creates none and says how many fit.

> [accordion] Fork through a snapshot
>
> With an older server that has no native fork, a source host that is under maintenance or full, or
> with `--keep-snapshot`, `fork` saves a snapshot,
> creates the copies from it, then deletes the snapshot (also on error or Ctrl-C) unless
> `--keep-snapshot`. Over the API, a native fork is `POST /v1/machines/{id}/fork`.

## Restore a machine in place

```bash theme={null}
instabox restore dev --snapshot dev-base
instabox restore dev --yes --stopped
```

`restore` puts a machine's disks back to a snapshot's. The machine keeps its ID, name, hostname, public
port URLs and ssh-config block, so everything that names it keeps working. Without `--snapshot` it
restores the snapshot the machine was created from.

> [!WARNING]
>
> Everything on the root disk and `/data` since the snapshot is gone, running programs included.
> `restore` asks first, and `--yes` skips the question. To keep the machine as it is, use
> `create --snapshot` or `fork` instead.

A running machine is stopped first. Then it boots the restored disks, and the command waits until it
runs. To leave it stopped, add `--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 first with `instabox resize <machine> --disk N`. Over the API, send `POST /v1/machines/{id}/restore`
with `{"snapshotId": "sn_..."}` (`machines:write`). It answers with a `restore` operation.

## Edge cases

> [accordion] Saving is refused
>
> A running machine on a server without live snapshots is refused like a paused one. Stop it, then
> save (api.instabox.sh has live snapshots on). If the save is refused because the machine has unsaved
> changes, stop it again, then retry.

> [accordion] Browse, delete and the free plan
>
> `instabox snapshot files dev-base /etc` lists a snapshot's files without starting a machine.
> Deleting a machine keeps its snapshots. Deleting a snapshot does not affect machines made from it.
> The free plan keeps 5 snapshots. Older snapshots that hold installed software only
> start with an empty home and workspace, like `--root-only` ones.

> [accordion] Over HTTP
>
> `POST /v1/machines/{id}/snapshots` saves a snapshot, and `GET /v1/snapshots` lists them.
> `POST /v1/machines` with `"snapshotId"` starts a machine from one.

> [card] [Custom images](https://instabox.sh/docs/machines/custom-images.md)
>
> Turn a Docker image into a snapshot.

> [card] [Parallel forks](https://instabox.sh/docs/use-cases/parallel-forks.md)
>
> Run several agents from one set-up machine.