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
• understand how rootfs snapshots differ from pause/resume and Volumes

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 Volumes when data must be mounted by multiple sandboxes, accessed directly through the Volume file API, or managed independently from sandbox rootfs lifecycle. Use sandbox rootfs snapshots when the default writable filesystem is the state you want to version.

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.
• 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 fork use the same persistence boundary as pause and resume. /tmp is ephemeral and is not captured or restored, while /var/tmp and ordinary writable rootfs paths remain persistent. A Sandbox Volume mounted beneath /tmp remains durable because Volume state is managed independently from rootfs checkpoints.

Older snapshot layers are filtered when restored, so legacy /tmp entries do not reappear. Reading and filtering a large legacy layer can make its first restore slower; later checkpoints omit that data. See Pause And Resume for the complete path policy.

Storage Encryption#

Application-layer object encryption is enabled by default. Before manager or ctld writes persisted rootfs layer and checkpoint objects to S3-compatible storage, Sandbox0 encrypts them with AES-256-GCM. Each object receives a random data key, its contents are stored in independently authenticated chunks, 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. Existing plaintext objects remain readable after encryption is enabled, while new object writes use the encrypted format; enabling encryption does not rewrite historical objects automatically. Self-hosted deployments can configure this behavior with spec.storage.runtime.objectEncryptionEnabled; see Service and Runtime Config.

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. Instead of building a custom image and maintaining a team-owned warm pool, start from a builtin template, initialize the sandbox, publish a rootfs snapshot, then claim new sandboxes from that snapshot.

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 builtin template backed by the platform warm pool
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
_, err := client.PauseSandbox(ctx, sandbox.ID)
if err != nil {
  log.Fatal(err)
}

for {
  sb, err := client.GetSandbox(ctx, sandbox.ID)
  if err != nil {
      log.Fatal(err)
  }
  if sb.Status == apispec.SandboxLifecycleStatusPaused {
      break
  }
  time.Sleep(time.Second)
}

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)

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.ResumeSandbox(ctx, sandbox.ID)
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.

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.ResumeSandbox(ctx, forked.Sandbox.ID)
if err != nil {
  log.Fatal(err)
}

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. pause the sandbox and wait for status to become paused
4. create a rootfs snapshot for that initialized state
5. claim each task sandbox with the same template and snapshot_id
6. run task-specific work in the newly claimed sandbox

Next Steps#