# 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

<Callout variant="warning">
Creating snapshots and forking accept a running or paused source sandbox. Running sources are briefly barriered and checkpointed, then remain running. Restore still requires a paused target sandbox because it replaces that sandbox's rootfs head. Claiming with `snapshot_id` creates a new running sandbox from an existing snapshot and does not require a paused target sandbox.
</Callout>

## How It Differs From Pause And Resume

| Capability | Purpose | Creates a named restore point | Creates another sandbox | Requires paused sandbox |
|------------|---------|-------------------------------|-------------------------|-------------------------|
| Pause/resume | Release compute and later continue the same sandbox identity from its latest checkpoint | No | No | Pause starts from a running sandbox; resume starts from a paused sandbox |
| Snapshot | Publish an immutable point-in-time rootfs record | Yes | No | No; running sources are checkpointed first |
| Claim with `snapshot_id` | Create a running sandbox initialized from a named snapshot | Uses an existing snapshot | Yes | No target sandbox required |
| Restore | Move a paused sandbox rootfs back to a snapshot | Uses an existing snapshot | No | Yes |
| Fork | Create an isolated paused sandbox from a source sandbox rootfs | No | Yes | No; running sources are checkpointed first |

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](/docs/sandbox/volume) 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.

<Callout variant="info">
The rootfs snapshot API stores snapshot metadata including `name`, `description`, and optional `expires_at`. Delete snapshots explicitly when cleanup workflows no longer need them.
</Callout>

## 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](/blog/2026-06/initialize-once-fork-many-custom-ai-agent-sandboxes).

<Callout variant="warning">
This pattern does not replace template-level configuration. Use a custom template when you need a different container image, resource limits, mount declarations, default network policy, environment defaults, or privileged runtime fields. Mounted Sandbox Volumes are separate from the sandbox rootfs and should be managed with Volume snapshot and fork APIs.
</Callout>

## 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.

<Endpoint method="POST">
/api/v1/sandboxes/{'{id}'}/pause
</Endpoint>

<Tabs
  tabs={[
    {
      label: "Go",
      language: "go",
      code: `_, 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)
}`
    },
    {
      label: "Python",
      language: "python",
      code: `import time

client.sandboxes.pause(sandbox.id)

while True:
    sb = client.sandboxes.get(sandbox.id)
    if sb.status == "paused":
        break
    time.sleep(1)`
    },
    {
      label: "TypeScript",
      language: "typescript",
      code: `await client.sandboxes.pause(sandbox.id);

while (true) {
    const sb = await client.sandboxes.get(sandbox.id);
    if (sb.status === "paused") {
        break;
    }
    await new Promise((resolve) => setTimeout(resolve, 1000));
}`
    },
    {
      label: "CLI",
      language: "bash",
      code: `s0 sandbox pause sb_abc123

# Wait until this shows status "paused".
s0 sandbox get sb_abc123`
    }
  ]}
/>

## Create A Snapshot

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

<Endpoint method="POST">
/api/v1/sandboxes/{'{id}'}/snapshots
</Endpoint>

### Request Body

| Field | Type | Description |
|-------|------|-------------|
| `name` | string | Optional snapshot name |
| `description` | string | Optional snapshot description |
| `expires_at` | string | Optional RFC3339 timestamp stored as snapshot expiration metadata |

<Tabs
  tabs={[
    {
      label: "Go",
      language: "go",
      code: `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)`
    },
    {
      label: "Python",
      language: "python",
      code: `from sandbox0.apispec.models.create_sandbox_root_fs_snapshot_request import CreateSandboxRootFSSnapshotRequest

snapshot = client.sandboxes.create_rootfs_snapshot(
    sandbox.id,
    CreateSandboxRootFSSnapshotRequest(
        name="before-agent-task",
        description="Workspace after dependency install",
    ),
)
print(f"Snapshot ID: {snapshot.id}")`
    },
    {
      label: "TypeScript",
      language: "typescript",
      code: `const snapshot = await client.sandboxes.createRootFSSnapshot(sandbox.id, {
    name: "before-agent-task",
    description: "Workspace after dependency install",
});
console.log("Snapshot ID:", snapshot.id);`
    },
    {
      label: "CLI",
      language: "bash",
      code: `s0 sandbox snapshot create sb_abc123 \\
    --name before-agent-task \\
    --description "Workspace after dependency install"`
    }
  ]}
/>

## List And Get Snapshots

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

<Endpoint method="GET">
/api/v1/sandboxes/{'{id}'}/snapshots
</Endpoint>

<Endpoint method="GET">
/api/v1/sandbox-rootfs-snapshots/{'{snapshot_id}'}
</Endpoint>

<Tabs
  tabs={[
    {
      label: "Go",
      language: "go",
      code: `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)`
    },
    {
      label: "Python",
      language: "python",
      code: `snapshots = client.sandboxes.list_rootfs_snapshots(sandbox.id)
for item in snapshots:
    print(item.id, item.name)

snapshot = client.sandboxes.get_rootfs_snapshot(snapshot.id)
print(f"Created at: {snapshot.created_at}")`
    },
    {
      label: "TypeScript",
      language: "typescript",
      code: `const snapshots = await client.sandboxes.listRootFSSnapshots(sandbox.id);
for (const item of snapshots) {
    console.log(item.id, item.name);
}

const fetched = await client.sandboxes.getRootFSSnapshot(snapshot.id);
console.log("Created at:", fetched.createdAt);`
    },
    {
      label: "CLI",
      language: "bash",
      code: `s0 sandbox snapshot list sb_abc123
s0 sandbox snapshot get rootfs-snapshot-abc123`
    }
  ]}
/>

## 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.

<Endpoint method="POST">
/api/v1/sandboxes
</Endpoint>

### Request Body

| Field | Type | Description |
|-------|------|-------------|
| `template` | string | Template ID to use |
| `snapshot_id` | string | Rootfs snapshot ID used to initialize the new sandbox writable rootfs |
| `config` | object | Optional sandbox configuration |
| `mounts` | array | Optional claim-time Sandbox Volume mounts |

<Tabs
  tabs={[
    {
      label: "Go",
      language: "go",
      code: `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)`
    },
    {
      label: "Python",
      language: "python",
      code: `sandbox = client.sandboxes.claim(
    "default",
    snapshot_id=snapshot.id,
)
print(f"Sandbox ID: {sandbox.id}")`
    },
    {
      label: "TypeScript",
      language: "typescript",
      code: `const sandbox = await client.sandboxes.claim("default", {
    snapshotId: snapshot.id,
    config: { hardTtl: 3600 },
});
console.log("Sandbox ID:", sandbox.id);`
    },
    {
      label: "CLI",
      language: "bash",
      code: `s0 sandbox create --template default --snapshot-id rootfs-snapshot-abc123`
    }
  ]}
/>

## 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.

<Endpoint method="POST">
/api/v1/sandboxes/{'{id}'}/rootfs/restore
</Endpoint>

### Request Body

| Field | Type | Description |
|-------|------|-------------|
| `snapshot_id` | string | Rootfs snapshot ID to restore |

<Callout variant="warning">
Restore is destructive for the target sandbox rootfs. Files changed after the restored snapshot are no longer the target sandbox head after restore.
</Callout>

<Tabs
  tabs={[
    {
      label: "Go",
      language: "go",
      code: `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)
}`
    },
    {
      label: "Python",
      language: "python",
      code: `from sandbox0.apispec.models.restore_sandbox_root_fs_request import RestoreSandboxRootFSRequest

restored = client.sandboxes.restore_rootfs(
    sandbox.id,
    RestoreSandboxRootFSRequest(snapshot_id=snapshot.id),
)
print(f"Restored snapshot {restored.snapshot_id}, status={restored.status}")

client.sandboxes.resume(sandbox.id)`
    },
    {
      label: "TypeScript",
      language: "typescript",
      code: `const restored = await client.sandboxes.restoreRootFS(sandbox.id, {
    snapshotId: snapshot.id,
});
console.log("Restored snapshot:", restored.snapshotId, "status:", restored.status);

await client.sandboxes.resume(sandbox.id);`
    },
    {
      label: "CLI",
      language: "bash",
      code: `s0 sandbox snapshot restore sb_abc123 rootfs-snapshot-abc123
s0 sandbox resume sb_abc123`
    }
  ]}
/>

## 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.

<Endpoint method="POST">
/api/v1/sandboxes/{'{id}'}/fork
</Endpoint>

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
    }
}
```

<Tabs
  tabs={[
    {
      label: "Go",
      language: "go",
      code: `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)
}`
    },
    {
      label: "Python",
      language: "python",
      code: `forked = client.sandboxes.fork(sandbox.id)
print(f"Forked sandbox: {forked.sandbox.id}")

client.sandboxes.resume(forked.sandbox.id)`
    },
    {
      label: "TypeScript",
      language: "typescript",
      code: `const forked = await client.sandboxes.fork(sandbox.id);
console.log("Forked sandbox:", forked.sandbox.id);

await client.sandboxes.resume(forked.sandbox.id);`
    },
    {
      label: "CLI",
      language: "bash",
      code: `s0 sandbox fork sb_abc123

# Resume the forked sandbox ID returned by the fork command.
s0 sandbox resume sb_forked123`
    }
  ]}
/>

## 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.

<Endpoint method="DELETE">
/api/v1/sandbox-rootfs-snapshots/{'{snapshot_id}'}
</Endpoint>

<Tabs
  tabs={[
    {
      label: "Go",
      language: "go",
      code: `_, err := client.DeleteSandboxRootFSSnapshot(ctx, snapshot.ID)
if err != nil {
    log.Fatal(err)
}
fmt.Println("Snapshot deleted")`
    },
    {
      label: "Python",
      language: "python",
      code: `client.sandboxes.delete_rootfs_snapshot(snapshot.id)
print("Snapshot deleted")`
    },
    {
      label: "TypeScript",
      language: "typescript",
      code: `await client.sandboxes.deleteRootFSSnapshot(snapshot.id);
console.log("Snapshot deleted");`
    },
    {
      label: "CLI",
      language: "bash",
      code: `s0 sandbox snapshot delete rootfs-snapshot-abc123`
    }
  ]}
/>

## 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

<CardGroup>
  <Card title="Pause And Resume" href="/docs/sandbox/pause-resume" cta="Continue">
    Control the lifecycle state required before snapshot, restore, and fork operations.
  </Card>

  <Card title="Files" href="/docs/sandbox/files" cta="Continue">
    Read and write sandbox files before creating a rootfs snapshot.
  </Card>

  <Card title="Volumes" href="/docs/sandbox/volume" cta="Continue">
    Use durable shared storage when rootfs snapshots are not the right persistence boundary.
  </Card>

  <Card title="Initialize Once, Claim Many" href="/blog/2026-06/initialize-once-fork-many-custom-ai-agent-sandboxes" cta="Read">
    Use rootfs snapshots and claim-time snapshot IDs as lightweight custom rootfs state.
  </Card>
</CardGroup>
