Snapshot And Restore

Sandbox rootfs snapshots are point-in-time copies of a sandbox writable root filesystem. Use them when you want to checkpoint an initialized workspace, claim new sandboxes from that known filesystem state, roll an existing sandbox back, or fork a sandbox into an isolated child sandbox.

Use this page when you need to:

• create named rootfs snapshots from a running or paused sandbox
• claim a new sandbox with a named rootfs snapshot
• restore a paused sandbox rootfs from a snapshot
• fork a running or paused sandbox into another paused sandbox
• rebase a paused sandbox onto a newer attested Base artifact
• understand how rootfs snapshots differ from pause/resume

How It Differs From Pause And Resume#

Pause/resume keeps the latest checkpoint for one sandbox identity. Rootfs snapshots are explicit records that you can list, fetch, claim from, restore, and delete. Fork creates a new sandbox with Copy-on-Write rootfs isolation from the source rootfs state.

Use sandbox rootfs snapshots when the default writable filesystem is the state you want to version or fan out into another sandbox identity.

State Model#

• Create snapshot creates a snapshot record from the source sandbox's current rootfs head. If the source is running, Sandbox0 briefly barriers the sandbox, checkpoints its writable rootfs, and then releases the source back to running.
• Claim with snapshot_id creates a running sandbox and initializes its writable rootfs from the selected snapshot before process APIs are initialized.
• Restore changes a paused target sandbox rootfs head to the selected snapshot and leaves the sandbox paused.
• Fork creates a new paused sandbox with the source sandbox configuration and an isolated rootfs fork. If the source is running, Sandbox0 briefly barriers the sandbox, checkpoints its writable rootfs, and then releases the source back to running. The fork request can override lifecycle ttl and hard_ttl.
• Rebase applies the paused sandbox's file-level changes to a different attested immutable Base artifact, publishes one new durable generation, and retains the old generation for a bounded rollback window.
• Resume is required before reading or writing files through sandbox process and file APIs after restore or fork. A sandbox claimed with snapshot_id starts running.
• Deleting a snapshot does not modify any sandbox already claimed or restored from it, and it does not affect forks created from the same rootfs state.

Rootfs Path Semantics#

Snapshots, snapshot claims, restore, and filesystem-only fork use the same block-COW persistence boundary as pause and resume. Ordinary writable RootFS paths such as /var/tmp and workspace directories are captured. /tmp, virtual runtime mounts such as /proc, /dev, and /sys, and template-defined ephemeralMounts are recreated for each runtime generation and are not snapshot content.

The default /tmp capacity is half the sandbox memory limit. Its temporary filesystem uses a private disk file on the compute node. Cached file pages still count toward memory usage, but can be reclaimed under memory pressure. The capacity itself reserves no memory. A template can set an explicit /tmp capacity using ephemeralMounts. /dev/shm and other ephemeral mounts remain memory-backed. Temporary files are discarded when the runtime ends, including filesystem-only pause/resume, and never enter a RootFS checkpoint. Explicit memory checkpoints can retain supported runtime tmpfs state separately from RootFS.

Storage Encryption#

When application-layer object encryption is enabled, manager and ctld encrypt persisted RootFS block data and descriptors before writing them to S3-compatible storage. With aes256gcm-rsa, each object receives a random data key, its contents are independently authenticated, and the data key is wrapped with the installation's RSA key.

This is service-side encryption, not end-to-end encryption: manager and the active ctld hold the installation key and can decrypt RootFS objects while serving sandbox operations. Enabling encryption does not rewrite historical objects automatically. Self-hosted deployments configure rootfs_object_storage.object_encryption_enabled, key path, and algorithm on manager and ctld; see Configuration.

Initialize Once, Claim Many#

RootFS snapshots plus claim-time snapshot_id can act like a lightweight custom RootFS when your changes are ordinary filesystem state. Start from a compatible template, initialize the sandbox, publish a RootFS snapshot, then claim new sandboxes from that snapshot. All compatible templates share the same resource-neutral carrier pool.

Use this pattern for:

• package installs and dependency caches
• cloned repositories and checked-out branches
• generated build artifacts that future runs should inherit
• local tool configuration written into the sandbox filesystem

Typical workflow:

1. claim a sandbox from a compatible builtin or team-owned template
2. install dependencies or prepare the workspace inside the sandbox rootfs
3. create a named rootfs snapshot for the initialized state
4. optionally pause or delete the seed sandbox after the snapshot is created
5. claim each task sandbox with the same template and snapshot_id

bash
SEED_SANDBOX_ID="$(s0 -o json sandbox create --template default --hard-ttl 86400 | jq -r '.id')"

# Initialize the rootfs with your normal sandbox commands, file writes, or SSH session.

SNAPSHOT_ID="$(s0 -o json sandbox snapshot create "$SEED_SANDBOX_ID" \
    --name python-deps-v1 \
    --description "Default template after Python dependency install" \
    | jq -r '.id')"

TASK_SANDBOX_ID="$(s0 -o json sandbox create \
    --template default \
    --snapshot-id "$SNAPSHOT_ID" \
    --hard-ttl 3600 \
    | jq -r '.id')"

Claiming with snapshot_id is the preferred path for reusable custom rootfs state because the result is a fresh running sandbox that still uses the builtin template's image, resources, mounts, services, and network defaults. Use restore when you need to roll an existing paused sandbox back to a snapshot. Use fork when you specifically need a paused child sandbox cloned from a running or paused source.

For a longer walkthrough of this pattern, see Initialize Once, Claim Many.

Rootfs Operation Lifecycle#

Create a snapshot from a running or paused sandbox. Pause the sandbox and wait until status is paused before restoring into it. Forking also accepts a running or paused source sandbox.

go
paused, err := client.PauseSandboxAndWait(ctx, sandbox.ID, nil)
if err != nil {
  log.Fatal(err)
}
fmt.Printf("Sandbox status: %s\n", paused.Status)

Create A Snapshot#

Create a rootfs snapshot from a running or paused sandbox. A running source remains running after the snapshot is created.

Request Body#

go
snapshot, err := client.CreateSandboxRootFSSnapshot(ctx, sandbox.ID, &apispec.CreateSandboxRootFSSnapshotRequest{
  Name:        apispec.NewOptString("before-agent-task"),
  Description: apispec.NewOptString("Workspace after dependency install"),
})
if err != nil {
  log.Fatal(err)
}
fmt.Printf("Snapshot ID: %s\n", snapshot.ID)

On the Nomad/gVisor runtime, a running-source snapshot is bound to the exact live allocation, node incarnation, rootfs writer grant, writer epoch, and source generation observed when the operation starts. The checkpoint is published as a separate immutable filesystem, so the source writer and source rootfs head are unchanged. If the API connection or manager restarts, Sandbox0 recovers the same pending operation from PostgreSQL; it never substitutes a checkpoint from a newer source runtime.

List And Get Snapshots#

List snapshots created from a sandbox, or fetch a snapshot directly by snapshot ID.

go
snapshots, err := client.ListSandboxRootFSSnapshots(ctx, sandbox.ID)
if err != nil {
  log.Fatal(err)
}
for _, item := range snapshots.Snapshots {
  name := item.Name.Or("")
  fmt.Printf("%s %s\n", item.ID, name)
}

snapshot, err = client.GetSandboxRootFSSnapshot(ctx, snapshot.ID)
if err != nil {
  log.Fatal(err)
}
fmt.Printf("Created at: %s\n", snapshot.CreatedAt)

Claim From A Snapshot#

Use snapshot_id on sandbox claim when you want a new running sandbox initialized from a named rootfs snapshot. The requested template still controls image, resources, mount declarations, services, network defaults, and other runtime shape. Sandbox0 applies the snapshot rootfs before file APIs, contexts, services, and SSH are initialized.

Request Body#

go
sandbox, err := client.ClaimSandbox(ctx, "default",
  sandbox0.WithSandboxSnapshotID(snapshot.ID),
  sandbox0.WithSandboxHardTTL(3600),
)
if err != nil {
  log.Fatal(err)
}
fmt.Printf("Sandbox ID: %s\n", sandbox.ID)

Restore A Sandbox Rootfs#

Restore moves a paused target sandbox rootfs to the selected snapshot and returns the sandbox status. The sandbox stays paused after restore; resume it before using files, contexts, services, or SSH.

Request Body#

go
restored, err := client.RestoreSandboxRootFS(ctx, sandbox.ID, apispec.RestoreSandboxRootFSRequest{
  SnapshotID: snapshot.ID,
})
if err != nil {
  log.Fatal(err)
}
fmt.Printf("Restored snapshot %s, status=%s\n", restored.SnapshotID, restored.Status)

_, err = client.ResumeSandboxAndWait(ctx, sandbox.ID, nil)
if err != nil {
  log.Fatal(err)
}

Fork A Sandbox#

Fork creates a new paused sandbox from a running or paused source sandbox rootfs. A running source is briefly barriered and checkpointed during the operation, then remains running. The fork receives its own sandbox ID. Writes made after resuming the fork do not modify the source sandbox rootfs.

On the Nomad/gVisor runtime, Sandbox0 persists the fork operation and paused target before contacting the source node. The authenticated node request is bound to the exact live allocation, node incarnation, rootfs writer grant, writer epoch, and source generation. If the API connection or manager restarts after checkpoint publication, background reconciliation recovers the committed target from PostgreSQL without freezing a newer source state again. A never-run fork target starts at runtime generation 0; its first resume claims a fresh slot as generation 1.

Omit the request body to inherit the source sandbox lifecycle configuration. To set a new lifecycle window for the fork, pass config.ttl and/or config.hard_ttl. Positive values are counted from the fork creation time, and 0 disables that expiration path.

json
{
    "config": {
        "ttl": 300,
        "hard_ttl": 3600
    }
}

go
forked, err := client.ForkSandbox(ctx, sandbox.ID, nil)
if err != nil {
  log.Fatal(err)
}
fmt.Printf("Forked sandbox: %s\n", forked.Sandbox.ID)

_, err = client.ResumeSandboxAndWait(ctx, forked.Sandbox.ID, nil)
if err != nil {
  log.Fatal(err)
}

Explicit Memory Fork#

Fork defaults to filesystem-only state. Experimental memory fork uses the same endpoint with memory: true and requires a stable Idempotency-Key header. The key and request body must stay unchanged on retries.

http
POST /api/v1/sandboxes/sb_source/fork
Content-Type: application/json
Idempotency-Key: branch-task-001

{
    "memory": true,
    "config": {
        "ttl": 300,
        "hard_ttl": 3600
    }
}

For a paused source, memory fork requires a retained memory checkpoint matching its RootFS head. For a running source, the current implementation captures and retires the source runtime, commits the paused child and resumes the parent into a new carrier. It does not keep the original parent runtime executing during capture. The parent's runtime ID and generation change; its original soft TTL is retained, and deletion or expiry cannot be undone by fork completion.

The operation returns 503 unavailable while capture or parent resume is still pending. Retry with the same key and body. A 201 response identifies the paused child; it does not start the child. Resume that child with memory: true to continue its captured processes. The parent and child use independent writable RootFS branches and resource leases; immutable checkpoint image data is shared.

python
from sandbox0.apispec.models.fork_sandbox_request import ForkSandboxRequest

forked = client.sandboxes.fork(
    sandbox.id,
    ForkSandboxRequest(memory=True),
    idempotency_key="branch-task-001",
)
client.sandboxes.resume_and_wait(forked.sandbox.id, memory=True)

The SDK call above performs one request. If it reports a pending operation, retry it with the same key and body before attempting child resume. In TypeScript, use client.sandboxes.fork(id, { memory: true }, { idempotencyKey: key }). In Go, use ForkSandboxWithOptions with ForkSandboxRequest.Memory and ForkSandboxOptions.IdempotencyKey.

Fork rebinds the captured runtime and session identity to the child without restarting guest processes. Previously queued parent webhook events are retained as inherited records and are not sent as child events. New child events carry the child's identity. External connections are not guaranteed to survive.

Memory fork has the compatibility and transfer costs described in Pause And Resume. Named snapshots, snapshot claims, restore and rebase remain RootFS operations; they do not create or restore process memory.

Rebase A Paused Sandbox#

Use rebase when a sandbox must move to a newer immutable Base artifact while preserving file-level changes from its current writable rootfs. The target Base artifact must already be attested and available in the same region. Rebase does not accept an image tag or build an image implicitly.

Request Body#

go
rebased, err := client.RebaseSandboxRootFS(ctx, sandbox.ID, apispec.RebaseSandboxRootFSRequest{
  TargetBaseArtifactDigest: "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  RollbackTTL:              apispec.NewOptInt32(86400),
})
if err != nil {
  log.Fatal(err)
}
fmt.Printf("Rebased generation: %s\n", rebased.GenerationID)

The sandbox must already be paused, have no live runtime slot or writer grant, and use the block-COW storage format. An exact retry returns the same target generation. A changed target digest or rollback window for the same operation is rejected with 409 Conflict.

Rebase is file-aware rather than a raw block transplant: the worker mounts the old Base, current source, and target Base in isolated branches, computes the filesystem change set, applies it to the target, validates the result, and only then publishes immutable objects. PostgreSQL commits the target generation and rollback pin atomically. The API can therefore recover a committed result after a manager restart or response loss without executing the merge again.

Delete A Snapshot#

Delete a rootfs snapshot when you no longer need it. This does not modify any sandbox that already restored from that snapshot, and it does not affect forks created from the same rootfs state.

go
_, err := client.DeleteSandboxRootFSSnapshot(ctx, snapshot.ID)
if err != nil {
  log.Fatal(err)
}
fmt.Println("Snapshot deleted")

Typical Pattern#

For coding-agent and test-generation workflows, a common pattern is:

1. claim a sandbox and initialize the repository or dependency cache
2. write a marker, lockfile, or workspace state that future tasks should inherit
3. create a rootfs snapshot for that initialized state; a running source remains running
4. claim each task sandbox with the same template and snapshot_id
5. run task-specific work in the newly claimed sandbox

Next Steps#