Snapshots and forks

A snapshot saves a sandbox’s memory and disk at a point in time. Sandboxes you create from a snapshot are called forks. A fork starts exactly where the snapshot left off, with its files, installed packages and running processes in place. Pausing saves one sandbox so it can continue later. A snapshot is a copy you can start any number of new sandboxes from, and it stays until you delete it, even after the original sandbox is gone. Use snapshots to:

Skip setup: install dependencies once, snapshot, and start every new sandbox ready to go.
Branch from one state: run several experiments in parallel from the same starting point.
Keep a known-good point: snapshot before a risky change and start fresh from it if something breaks.

Take a snapshot

You can snapshot an active or paused sandbox. A running sandbox is paused briefly while the snapshot is taken, usually for under a second, and then continues. The first snapshot of a large sandbox can take longer.

import { Sandbox } from "@superserve/sdk"

const sandbox = await Sandbox.create({ name: "dev-env" })
await sandbox.commands.run("pip install pandas")
const snapshot = await sandbox.snapshot({ name: "with-pandas" })

from superserve import Sandbox

sandbox = Sandbox.create(name="dev-env")
sandbox.commands.run("pip install pandas")
snapshot = sandbox.snapshot(name="with-pandas")

snapshot() returns once the snapshot is ready.

Create a sandbox from a snapshot

Pass the snapshot, or its ID, as fromSnapshot / from_snapshot. You can’t combine it with fromTemplate.

const fork = await Sandbox.create({
  name: "experiment-1",
  fromSnapshot: snapshot,
})
await fork.commands.run("python -c 'import pandas'")

fork = Sandbox.create(
    name="experiment-1",
    from_snapshot=snapshot,
)
fork.commands.run("python -c 'import pandas'")

Each fork is independent. Changes in one fork don’t affect the snapshot, the original sandbox or other forks.

What a fork starts with

Machine: the snapshot’s vCPU, memory and disk size, and the template it was built on.
Network rules: the original sandbox’s rules, unless you pass network. They apply before anything in the fork runs.
Timeout: the original sandbox’s auto-pause timeout, unless you pass timeoutSeconds / timeout_seconds.
Secrets: the original sandbox’s secrets are attached again. Secrets deleted since the snapshot are left out, and any secrets you pass are attached as usual.
Environment: commands you run in the fork see the original sandbox’s environment, with your envVars / env_vars and secrets added on top.

Processes that were already running when the snapshot was taken keep the environment they started with. Their secret values only work in the original sandbox, so restart any process that uses secrets.

List, rename and delete

import { Snapshot } from "@superserve/sdk"

const snapshots = await sandbox.snapshots() // newest first
const same = await Snapshot.get(snapshots[0].id)
const renamed = await same.rename("golden")
await renamed.delete()

from superserve import Snapshot

snapshots = sandbox.snapshots()  # newest first
same = Snapshot.get(snapshots[0].id)
renamed = same.rename("golden")
renamed.delete()

Snapshots stay after their sandbox is deleted. To list them then, use Snapshot.list(sandboxId) / Snapshot.list(sandbox_id). Deleting a snapshot takes effect immediately and doesn’t affect sandboxes already created from it.

Limits

100 snapshots per team.
20 snapshots per sandbox.
4 snapshots being taken at once per team.

Past a limit, snapshot() fails with too_many_snapshots or too_many_snapshots_in_flight. Delete snapshots you no longer need to free up room, or contact support@superserve.ai to raise a limit. While a snapshot is being taken, you can’t attach or detach that sandbox’s secrets. Those calls return 409 snapshot_in_progress; retry once the snapshot is ready.

Get Started

Sandbox

Secrets & env vars

Templates

Commands

Filesystem

Storage

Errors

Take a snapshot

Create a sandbox from a snapshot

What a fork starts with

List, rename and delete

Limits

​Take a snapshot

​Create a sandbox from a snapshot

​What a fork starts with

​List, rename and delete

​Limits

Take a snapshot

Create a sandbox from a snapshot

What a fork starts with

List, rename and delete

Limits