Snapshots.

What a snapshot captures

A snapshot is an image of the box's whole disk at one instant, taken by the storage layer while the box keeps running. Nothing on the box is touched, and the box is never paused for it.

• Crash-consistent. The snapshot 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 the blocks that 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 a snapshot never changes the box it came from.

Snapshots are for boxes on the standard sizes. Fast boxes cannot be snapshotted; pausing one already checkpoints it.

Kinds

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

Fork copies are transient: they are not listed by default, cannot be restored or named, and delete themselves once the new box is running. prized snapshot ls --kind fork shows them while they exist; to keep the disk copy of a fork as a normal snapshot, fork with --keep-snapshot.

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. The new box gets the snapshot's size and lives in the snapshot's region; its login user is the source box's, because the home directory on that disk belongs to it. --tier picks another size: any size whose disk holds the snapshot works; one whose disk is smaller is refused with the numbers (a disk image cannot shrink).

A restore is a create: 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: the control plane snapshots the box's disk and creates the new box from it in the same step. The source keeps running the whole time. The new box keeps the source's size, region, login user, and auto-pause setting; --tier picks another size, any whose disk holds the copy.

• Minutes, not seconds. The new box waits for the disk copy, then launches and boots. --wait watches it come up and prints each step; without it the command returns right away and the box page shows progress.
• A wait that never ends is a failure, not a hang. If the disk copy is still not done after 30 minutes, the new box is marked failed with the reason (delete it; the source box is untouched). A first snapshot of a very large disk can take longer than that: take a manual snapshot first, later snapshots of the same disk are incremental and fast.
• The copy is crash-consistent (see above). Anything the source had not written to disk at that instant is not on the fork.
• The disk copy is temporary. The snapshot behind a fork is deleted by itself once the new box is running (or once it has failed for good). It never counts toward the snapshot limit. --keep-snapshot keeps it under Snapshots as a manual snapshot instead, 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.

The dashboard's Fork action on the box page does the same and opens the new box's page.

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 of that box is taken and named) or a snapshot id starting with snp_ (from prized snapshot ls). A snapshot's own name is not accepted there, so a box called the same thing as a snapshot is never mistaken for it.
• Saving a name again moves it. The name goes to the newer snapshot and the previous holder turns back into a plain manual snapshot. It is kept, not deleted; delete it yourself when you no longer need it.
• Templates count toward the snapshot limit like manual snapshots. Naming an automatic snapshot as a template turns it into a counted one, and is refused when the limit is full. A transient fork copy cannot be named.
• A template is ready once its snapshot is available. Creating a box from a template that is still being taken is refused with snapshot_in_progress; try again when it shows available.

Automatic snapshots

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

With a schedule set, the control plane snapshots the box's disk whenever the newest automatic snapshot is older than the interval, and keeps the newest keep. The box page has the same control under Automatic snapshots.

• When they run. While the box is running or paused (a paused box still has its disk). A box in deep sleep or with no disk yet is skipped until it has one. A manual snapshot in flight defers the scheduled one to the next pass.
• Retention. At most keep automatic snapshots per box, and each one expires after keep x interval (every 6 hours keeping 5 means a 30 hour window). Switching the schedule off stops new ones; the ones already taken still expire on their own. A snapshot a new box is still launching from is kept until that box is running.
• Outside the limit. Automatic snapshots never count toward the 20 snapshot limit. They still need a funded balance or an active plan, like any snapshot.
• Names. auto-<box>-<yyyymmdd-hhmmss>, in UTC.

Limits

CLI

Every command takes --json and prints one object. A snapshot in JSON is {id, name, description, kind, template, status, box_id, box, tier, region, size_gb, created, expires, error}; a box is {id, hostname, tier, state}.

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

API

All routes take the CLI token; ids are tenant-scoped, so another workspace's ids answer 404.

Refusals: 409 snapshot_in_progress, 409 no_volume, 409 insufficient_balance, 409 name_taken, 409 box_limit, 409 snapshot_unavailable (a failed, deleting, or transient fork snapshot as a template), 422 microvm_unsupported, 429 snapshot_limit, 403 restore_tier_not_allowed (the shape is off-plan or its disk cannot hold the snapshot; the message names the size and the disk).