Skip to main content
A snapshot is a point-in-time image of a sandbox’s filesystem. You can launch a brand-new sandbox from any snapshot you own, with exactly the files you saved. Use snapshots to:
  • Save a working environment before risky changes.
  • Hand off a configured environment to a teammate (within your account; snapshots are per-user).
  • Spin up identical sandboxes from a known-good baseline instead of re-running setup every time.
Snapshots are independent objects: a sandbox can be destroyed without affecting its snapshots, and a snapshot can be deleted without affecting the sandbox it came from.

​
Creating a snapshot

You create snapshots in two modes: manually whenever you want, or on a schedule.

​
Manual

From the dashboard, click Snapshot on a sandbox’s detail page and name it. From the SDK, call snapshots.create on the handle: 
const snap = await handle.snapshots.create({ name: "before-migration" });
console.log(snap.id, snap.status); // status starts as "creating"
The name is lowercase letters, digits, and hyphens, 1–40 chars. The response is immediate with status: "creating". The snapshot transitions to ready once the image is built, typically within a couple of minutes for typical sandbox sizes. If the build fails, the snapshot moves to failed and stays there; failed snapshots don’t auto-retry.
Sandbox detail page with the Take snapshot modal open, showing the name input and the Create button
You can only snapshot a ready sandbox. Sandboxes that are paused, starting, or anything else reject the snapshot call. Only one snapshot per sandbox can be in-flight at a time; back-to-back requests serialize.

​
Automatic

To snapshot on a schedule, set snapshotMode: "automatic" and snapshotFrequency (a five-field cron expression) at sandbox creation: 
const handle = await client.sandboxes.createReady({
  template: "node-22",
  persistent: true,
  persistentDiskGB: 20,
  snapshotMode: "automatic",
  snapshotFrequency: "0 */2 * * *", // every two hours
});
The example above snapshots every two hours. The scheduler only fires when the sandbox is ready and no snapshot is already in flight; if the sandbox is paused or busy, the tick is skipped (it doesn’t queue up missed runs). snapshotMode defaults to manual. snapshotFrequency is required when mode is automatic and forbidden otherwise.

​
Restoring from a snapshot

Restoring doesn’t modify the snapshot; it creates a new sandbox whose initial filesystem is the snapshot’s image. Pass fromSnapshot to any create call: 
const handle = await client.sandboxes.createReady({
  fromSnapshot: snapshotId,
});
A few things to know:
  • Only ready snapshots are restorable. creating rejects with a clear error; failed is unusable.
  • The new sandbox’s template is inherited from the snapshot’s source template.
  • The new sandbox gets a fresh ID and is otherwise independent; pause, exec, destroy, all behave normally.
  • You can restore the same snapshot any number of times. Each restore is a separate sandbox.
Restores boot a few seconds slower than a fresh template sandbox. Snapshots aren’t pre-warmed, the image has to be pulled and unpacked before the container can start. Expect a small extra delay on the starting → ready transition compared to a regular create. createReady / getReady waits for you; if you’re driving the create manually, give waitUntilReady a slightly longer timeout.
Snapshots tab in the dashboard with name, source sandbox, status, created date, and a Restore button on each row

​
Listing snapshots

Two views, depending on scope: 
// Every snapshot you own across all sandboxes, paginated
const all = await client.snapshots.listAll({ page: 1, limit: 50 });

// Just the snapshots from one sandbox
const mine = await handle.snapshots.list({ page: 1, limit: 50 });
Each snapshot exposes id, name, source_template, status, created_at, and sandbox_id. The image bytes themselves aren’t downloadable; snapshots are restore-only.

​
Deleting snapshots

await client.snapshots.delete(snapshotId);
Deletion is permanent. The snapshot’s underlying image is removed; restore stops working immediately for anyone holding the ID.
Snapshot deletion can’t be undone. There’s no soft-delete. Sandboxes already restored from the snapshot keep running, but you can’t restore the same snapshot again. If the snapshot is your only copy of important state, take a fresh one before deleting.

​
Retention and expiry

Each snapshot has an expires_at timestamp set at creation. A background reaper runs hourly and deletes snapshots whose expires_at has passed. The retention window depends on your plan and account configuration; check Billing → Limits to see your current snapshot retention. Restoring from a snapshot does not extend its expiry. If you want to keep a baseline indefinitely, take a fresh snapshot from the restored sandbox before the original expires.

​
Billing

Snapshots count against your account’s compute-storage usage for the time they’re held. Storage charges are visible under Billing → Usage. Deletion stops the billing immediately. Restoring isn’t free either: the new sandbox bills from the moment it goes ready, like any other sandbox. The snapshot itself stays billable separately.

​
Failure modes

FailureWhat happensWhat to do
Snapshot build failsStatus flips to failed; no auto-retryDelete the failed snapshot, take a fresh one from a ready sandbox.
Snapshot expired before you restoredRestore call returns not foundTake snapshots more frequently, or extend retention via plan upgrade.
Snapshot deleted while you were restoringRestore fails partway with a clear errorDon’t delete snapshots in flight; deletion is final but waits for in-flight restores to complete first.
Concurrent snapshots requestedSecond request is rejectedWait for the in-flight snapshot to finish (ready or failed), then retry.

​
Next steps

  • SDKs, the full reference, including snapshot helpers on the handle and at the client level.
  • Sandboxes overview, lifecycle and operations.
  • Sandbox internals, how snapshot images are stored and restored.
Last modified on May 24, 2026