Snapshots

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

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

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

Take a snapshot

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

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

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

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.

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

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

Every cap, the 20-snapshot count included, is on Limits.

CLI

Every command takes --json and prints one object.

Exit codes follow the CLI contract: 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.