Skip to main content
A snapshot is a named checkpoint of a sandbox. Capture one from a running sandbox, then start as many new sandboxes as you need from that same point. The original sandbox keeps running. The snapshot is a separate object you can list, reuse, and delete. In the API and SDK a sandbox is a runtime (runtime_id, client.runtime, gravixlayer runtime). The snippets below use those names.

Cold and hot

Choose the kind when you create the snapshot. Restore always starts a new sandbox. Use cold after you have installed packages or written files and you only need the disk. Use hot when you also need memory — a loaded model, a running server, or interpreter state.

Snapshots vs pause vs templates

Start from a template when every sandbox should look the same. Take a snapshot when the sandbox has already done work you want to keep.

When to use a snapshot

  • Save a sandbox after installs, clones, or data prep, then start later from that point.
  • Snapshot before a risky step. If it fails, start a new sandbox from the snapshot instead of cleaning up by hand.
  • Start several sandboxes from the same checkpoint so they all begin in the same place.

During capture

The source sandbox pauses briefly, then continues with the same ID. Open SSH sessions, terminals, and streams may drop. Reconnect after the snapshot is ready.
Capture can take from under a second (typical hot) to several seconds (cold, larger disk). The create call waits until the snapshot is ready to use.

Region

A snapshot belongs to the region of the sandbox you captured. New sandboxes from that snapshot start in the same region. Pass the same cloud and region you used for the source sandbox. If that region has no capacity, create fails.

Endpoints

Snapshot object