# Snapshots

> Take point-in-time images of a box's disk by hand or on a schedule, restore them into new boxes, fork a running box, and save templates new boxes start from.

URL: https://prized.dev/docs/snapshots

## What a snapshot captures [#what-a-snapshot-captures]

A snapshot is the box's whole disk at one instant, taken without pausing the box.

* **Crash-consistent.** It holds what had reached the disk, as after a power loss, not what was still in memory (an editor buffer, a database's unflushed page). Save or flush first if a moment matters.
* **Block level, incremental.** Each stores only what changed since the one before (a new box's first, only what the box itself wrote), so frequent snapshots of a quiet box are cheap.
* **Independent of the box.** Deleting the box does not delete its snapshots, and restoring one never changes the box it came from.

## Kinds [#kinds]

The box's Snapshots tab and `prized snapshot ls` show each snapshot's kind:

| Kind      | Who takes it                                        | Counts toward the limit | Goes away                                                        |
| --------- | --------------------------------------------------- | ----------------------- | ---------------------------------------------------------------- |
| manual    | You, from the dashboard or `prized snapshot create` | yes                     | When you delete it                                               |
| template  | You, by naming a snapshot                           | yes                     | When you delete it (dropping the name turns it back into manual) |
| fork copy | `prized fork` or the Fork button                    | no                      | By itself, once the new box is running                           |
| automatic | The schedule you set on a box                       | no                      | By itself, past the box's keep count or after keep x interval    |

Fork copies are hidden by default (`prized snapshot ls --kind fork` lists them) and can never be restored or named.

## Take a snapshot [#take-a-snapshot]

```bash
prized snapshot create mango --name pre-upgrade
prized snapshot ls
```

The command returns at once; the snapshot shows `creating` until the disk copy completes, then `available`: a minute or two on a quiet box, longer the more was written since the last one. One per box at a time; a second request is refused with `snapshot_in_progress`. In the dashboard: the Snapshots page, or the Snapshot action on the box page.

## Restore into a new box [#restore-into-a-new-box]

```bash
prized snapshot restore pre-upgrade --name mango-2
```

Restore never rolls a box back in place: it creates a new box from the snapshot, in the snapshot's size and region, with the source box's login user. `--tier` picks any size whose disk holds the snapshot; a smaller disk is refused with the numbers. A restore is a create, so the box limit and a new box's balance rules apply.

## Fork a box [#fork-a-box]

```bash
prized fork mango --name mango-2 --wait
```

A fork is a snapshot and a restore in one call, while the source keeps running. The new box keeps the source's size, region, login user, and auto-pause setting; `--tier` picks another size whose disk holds the copy. The Fork action on the box page does the same.

* **Minutes, not seconds.** The new box waits for the disk copy, then launches and boots; `--wait` prints each step, or watch the box page.
* **A copy that stops is a failure; a slow one is not.** The new box waits as long as the copy keeps moving: the first copy of a large, busy disk can take over an hour. No progress for 30 minutes, or not done after 8 hours, marks the new box failed with the reason (delete it; the source is untouched, and the failed box costs nothing). To make forks of a big box quick, take a manual snapshot first: the fork then copies only what changed after it.
* **The copy is temporary:** it deletes itself once the new box is running (or has failed for good). `--keep-snapshot` keeps it as a manual snapshot, which counts toward the limit.
* **A fork is a create:** if the box limit or the balance rules refuse it, nothing is created.

## Templates [#templates]

A template is a snapshot with a reusable name; new boxes start from it by name, from the create form's Start from picker or the CLI.

```bash
prized snapshot template mango web-stack      # snapshot mango now and name it
prized snapshot template snp_1a2b3c web-stack # or name an existing snapshot by its id
prized snapshot restore web-stack --name api-2
prized snapshot untemplate web-stack          # drop the name; the snapshot stays
```

* **Box or snapshot id.** The first argument is a box name (a fresh snapshot is taken and named) or a snapshot id starting with `snp_`, not a snapshot's own name.
* **Saving a name again moves it** to the newer snapshot; the previous holder turns back into a plain manual snapshot, kept, not deleted.
* **Naming an automatic snapshot** makes it count toward the limit, and is refused when the limit is full.
* **A template is ready once its snapshot is `available`**; creating a box from one still being taken is refused with `snapshot_in_progress`.

## Automatic snapshots [#automatic-snapshots]

```bash
prized box auto-snapshot mango --every 6h --keep 5
prized box auto-snapshot mango --every off
```

A schedule snapshots the box's disk whenever the newest automatic snapshot is older than the interval; the box page's **Snapshots** tab has the same control.

* **When they run.** While the box is running or paused; a box in deep sleep is skipped until it has a disk again, and a manual snapshot in flight defers the scheduled one.
* **Retention.** At most `keep` per box, each expiring after keep x interval (every 6 hours keeping 5 is a 30 hour window). Switching the schedule off stops new ones; those already taken still expire, except one a new box is still launching from.
* **Outside the limit**, but like any snapshot they need a funded balance or an active plan. Names are `auto-<box>-<yyyymmdd-hhmmss>`, in UTC.

## Limits [#limits]

Every cap, the 20-snapshot count included, is on [Limits](https://prized.dev/docs/limits#snapshots).

## CLI [#cli]

Every command takes `--json` and prints one object.

| Command                                                          | What it does                                                                    |
| ---------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `prized snapshot create <box> [--name N] [--description D]`      | Snapshot the box's disk now                                                     |
| `prized snapshot ls [--box B] [--kind K]`                        | List snapshots, newest first; `--kind fork` shows transient fork copies         |
| `prized snapshot restore <id\|name> [--name NEWBOX] [--tier T]`  | A new box from a snapshot or template; `--tier` is any size whose disk holds it |
| `prized snapshot delete <id\|name> [-y]`                         | Delete a snapshot (asks first)                                                  |
| `prized snapshot template <snp_id\|box> <name>`                  | Name a snapshot by id, or snapshot a box now and name it                        |
| `prized snapshot untemplate <name>`                              | Drop a template name; the snapshot stays                                        |
| `prized fork <box> [--name] [--tier] [--keep-snapshot] [--wait]` | A new box from a copy of the box's disk                                         |
| `prized box auto-snapshot <box> --every 6h\|off [--keep N]`      | Set or clear the box's snapshot schedule                                        |

Exit codes follow the [CLI contract](https://prized.dev/docs/cli#for-agents-and-scripts): a busy box, a taken name, or the box limit is `CONFLICT` (6); an unknown box or snapshot, a size that cannot hold the disk, and the snapshot limit are `CHECK_FAILED` (5). Every route, body, and refusal code is on the [API reference](https://prized.dev/docs/api#snapshots).