# Snapshots > Point-in-time images of a box's disk. Take one by hand or on a schedule, restore it into a new box, fork a running box in one step, and save named templates new boxes start from. URL: https://prized.dev/docs/snapshots ## What a snapshot captures [#what-a-snapshot-captures] A snapshot is an image of the box's whole disk at one instant, taken while the box keeps running; the box is never paused for it. * **Crash-consistent.** It holds what had reached the disk at that instant, like a machine that lost power; anything still in memory (an editor buffer, a database's unflushed page) is not in it. Save or flush first if a moment matters. * **Block level, incremental.** A snapshot stores only what changed on the disk since the one before it, so frequent snapshots of a quiet box are cheap. A new box's first snapshot stores only what the box itself has written. * **Independent of the box.** Deleting the box does not delete its snapshots, and restoring one never changes the box it came from. ## Kinds [#kinds] Every snapshot has a kind that says why it exists; the Snapshots page and `prized snapshot ls` show it. | 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 transient: not listed by default, never restored or named, gone once the new box is running. `prized snapshot ls --kind fork` shows them while they exist; `prized fork --keep-snapshot` keeps the copy as a manual snapshot instead. ## Take a snapshot [#take-a-snapshot] ```bash prized snapshot create mango --name pre-upgrade prized snapshot ls ``` The command returns as soon as the snapshot is registered; it shows `creating` until the disk copy completes, then `available` (a minute or two on a quiet box, longer the more has been written since the last one). One snapshot per box at a time: a second request while one is in flight is refused with `snapshot_in_progress`. The dashboard does the same from 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 whose disk is the snapshot, in the snapshot's size and region, with the source box's login user (the home directory on that disk belongs to it). `--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 the balance rules of a new box 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 dashboard's Fork action on the box page does the same and opens the new box's page. * **Minutes, not seconds.** The new box waits for the disk copy, then launches and boots; `--wait` prints each step, otherwise the box page shows progress. * **A wait that never ends is a failure.** A disk copy still not done after 30 minutes marks the new box failed with the reason (delete it; the source is untouched). A disk with a great deal written since its last snapshot can take longer than that: take a manual snapshot first, since the fork then copies only what changed after it. * **The copy is crash-consistent**, like any snapshot, and temporary: it deletes itself once the new box is running (or has failed for good) and never counts toward the snapshot limit. `--keep-snapshot` keeps it as a manual snapshot, where it does count. * **A fork is a create.** The box limit and the balance rules of a new box apply; if either refuses, 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_`; a snapshot's own name is not accepted there. * **Saving a name again moves it.** The name goes to the newer snapshot and the previous holder turns back into a plain manual snapshot, kept, not deleted. * **Templates count toward the snapshot limit** like manual snapshots. Naming an automatic snapshot turns it into a counted one and is refused when the limit is full; a fork copy cannot be named. * **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 ``` With a schedule set, the box's disk is snapshotted whenever the newest automatic snapshot is older than the interval, and the newest `keep` are kept. The box page has the same control under Automatic snapshots. * **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.** Automatic snapshots never count toward the 20 snapshot limit, but need a funded balance or an active plan like any snapshot. Names are `auto--`, 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 [--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 [--name NEWBOX] [--tier T]` | A new box from a snapshot or template; `--tier` is any size whose disk holds it | | `prized snapshot delete [-y]` | Delete a snapshot (asks first) | | `prized snapshot template ` | Name a snapshot by id, or snapshot a box now and name it | | `prized snapshot untemplate ` | Drop a template name; the snapshot stays | | `prized fork [--name] [--tier] [--keep-snapshot] [--wait]` | A new box from a copy of the box's disk | | `prized box auto-snapshot --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).