Skip to main content
A snapshot is a named copy of a running sandbox’s memory, processes, and disks. The source continues once it is taken, and new sandboxes can start from it with that state while the source sandbox exists.

Take a Snapshot

POST /sandbox/{id}/snapshot snapshots a running sandbox. name is optional and need not be unique.
Request
The response is 202 with the snapshot.
Output
phase moves through the steps of the copy and ends at Published when the snapshot is usable, or Failed with a failure_cause. A larger memory size takes longer, from about 10 seconds to about a minute. The source’s processes stand still while its memory is copied, about 6 to 10 seconds at 1 GiB, and its state reads running throughout. A paused sandbox cannot be snapshotted. A snapshot request while a pause or another snapshot is in progress is refused with 409 operation_in_progress.

Create from a Snapshot

from starts a new sandbox with the snapshot’s state.
Request
  • Fields. Only name, tags, timeout, idle_timeout, and region may be given with from. The image, the sizes, the environment, and the network policy are the source’s.
  • Timeouts. An omitted timeout or idle_timeout is copied from the source.
  • Identity. The new sandbox receives a new machine ID, new SSH host keys, and new entropy.
  • Batches. POST /sandbox/batch accepts from, to start many sandboxes from one snapshot.
A snapshot that is not yet Published is refused with 409 snapshot_not_published. A snapshot whose source has terminated is refused with 409 source_terminated.

Manage Snapshots

A sandbox holds at most three snapshots. A fourth is refused with 409 snapshot_quota until one is deleted and the host has removed its checkpoint, shortly after the delete. Pauses and forks do not count against the cap. A snapshot belongs to its source sandbox and is removed when the source terminates. Its record can read Published for a few minutes afterwards, while a create from it is refused with 409 source_terminated. To keep a ready state beyond one sandbox, use a template. A snapshot published as a template Preview will keep a sandbox’s live state after it terminates.

Snapshots, Pauses, and Forks