> ## Documentation Index
> Fetch the complete documentation index at: https://docs.declaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Snapshots

> Create point-in-time snapshots of sandboxes and restore them to resume from a saved state.

A snapshot captures the complete state of a running sandbox — memory contents, filesystem, and process state — and saves it to persistent storage. Snapshots can be restored to create new sandboxes that resume exactly where the original left off.

## Create a snapshot

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from declaw import Sandbox

    sbx = Sandbox.create()

    # Install dependencies and run setup
    sbx.commands.run("pip3 install numpy pandas matplotlib")
    sbx.files.write("/workspace/data.csv", data)

    # Snapshot the ready-to-use state
    snapshot = sbx.create_snapshot()
    print(snapshot.snapshot_id)  # snap-abc123
    print(snapshot.sandbox_id)   # sbx-def456
    print(snapshot.created_at)   # 2024-01-15T10:00:00Z

    sbx.kill()
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    const sbx = await Sandbox.create();

    await sbx.commands.run('pip3 install numpy pandas matplotlib');

    const snapshot = await sbx.createSnapshot();
    console.log(snapshot.snapshotId);

    await sbx.kill();
    ```
  </Tab>
</Tabs>

## SnapshotInfo model

| Field         | Type       | Description                            |
| ------------- | ---------- | -------------------------------------- |
| `snapshot_id` | `str`      | Unique identifier in `snap-*` format   |
| `sandbox_id`  | `str`      | ID of the sandbox that was snapshotted |
| `created_at`  | `datetime` | When the snapshot was taken            |

## Restore from a snapshot

Pass a `snapshot_id` to `Sandbox.create()` to start a new sandbox that resumes from that state.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    # Create a fresh sandbox from the snapshot
    sbx = Sandbox.create(snapshot_id="snap-abc123")

    # The sandbox is already set up — libraries installed, files present
    result = sbx.commands.run("python3 -c 'import pandas; print(pandas.__version__)'")
    print(result.stdout)  # 2.1.0

    result = sbx.commands.run("ls /workspace/")
    print(result.stdout)  # data.csv
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    const sbx = await Sandbox.create({ snapshotId: 'snap-abc123' });

    const result = await sbx.commands.run('ls /workspace/');
    console.log(result.stdout);  // data.csv
    ```
  </Tab>
</Tabs>

## List snapshots

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from declaw import Sandbox

    paginator = Sandbox.list_snapshots(limit=20)
    for snap in paginator:
        print(snap.snapshot_id, snap.sandbox_id, snap.created_at)
    ```
  </Tab>
</Tabs>

## Lifecycle during snapshot

When `create_snapshot()` is called, the sandbox briefly pauses to capture a consistent memory image and then resumes automatically. The sandbox continues running after the snapshot completes.

```mermaid theme={null}
stateDiagram-v2
    Running --> Snapshotting: create_snapshot()
    Snapshotting --> Running: Snapshot saved to storage
    Snapshotting --> NewSandbox: Sandbox.create(snapshot_id)
    NewSandbox --> Running: New VM from snapshot
```

The snapshotting pause is typically under one second for sandboxes with 256 MB of RAM.

## Use cases

<AccordionGroup>
  <Accordion title="Warm-start sandboxes">
    Install heavy ML libraries once, snapshot the result, then create new sandboxes from that snapshot for every request. Eliminates the `pip install torch` overhead from every run.

    ```python theme={null}
    # One-time setup
    setup_sbx = Sandbox.create()
    setup_sbx.commands.run("pip3 install torch transformers sentence-transformers")
    snap = setup_sbx.create_snapshot()
    setup_sbx.kill()

    # Fast warm-start for every agent run
    agent_sbx = Sandbox.create(snapshot_id=snap.snapshot_id)
    # torch is already installed
    ```
  </Accordion>

  <Accordion title="Checkpoint long-running tasks">
    Snapshot a sandbox mid-computation so you can restore it if the run fails.

    ```python theme={null}
    sbx = Sandbox.create()
    sbx.commands.run("python3 download_dataset.py")

    # Checkpoint after expensive download
    checkpoint = sbx.create_snapshot()

    sbx.commands.run("python3 train_model.py")  # may fail
    # If it fails, restore from checkpoint and retry
    ```
  </Accordion>

  <Accordion title="Branch sandbox state">
    Create multiple independent sandboxes from the same snapshot to explore different execution paths.

    ```python theme={null}
    snap = base_sbx.create_snapshot()

    # Explore two different approaches in parallel
    branch_a = Sandbox.create(snapshot_id=snap.snapshot_id)
    branch_b = Sandbox.create(snapshot_id=snap.snapshot_id)

    branch_a.commands.run("python3 approach_a.py")
    branch_b.commands.run("python3 approach_b.py")
    ```
  </Accordion>
</AccordionGroup>

<Warning>
  Snapshots capture the state of a single sandbox at a point in time. They do not capture external state such as in-flight network connections, database transactions, or changes to services outside the sandbox.
</Warning>