Snapshots.

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. The first snapshot of a disk copies every used block; later ones store only what changed since, 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

Every snapshot has a kind that says why it exists; the Snapshots page and prized snapshot ls show it.

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

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 (minutes for a big disk the first time, faster after that). 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

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

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 very large disk's first snapshot can take longer than that: take a manual snapshot first, since later ones are incremental and fast.
• 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

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_; 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

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-<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.