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

# Snapshots

> Save and restore sandbox filesystem, memory, and running processes

Snapshots support two snapshot types:

* `filesystem`: captures filesystem state and restores with a cold boot.
* `memory`: captures filesystem, memory, and running process state and restores with a warm start.

When you do not specify a type, Tensorlake uses `filesystem` by default.

Snapshots are independent of sandbox [lifecycle](/sandboxes/lifecycle) — once captured, the artifact persists after the source sandbox is terminated. This means you can snapshot an ephemeral sandbox before it ends, then restore that state into a new sandbox much later. If you only need to pause a single sandbox in place rather than produce a reusable artifact, use [suspend/resume](/sandboxes/lifecycle#suspend-and-resume) instead.

## Creating a Snapshot

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    tl sbx checkpoint <sandbox-id>
    tl sbx checkpoint <sandbox-id> --checkpoint-type filesystem
    tl sbx checkpoint <sandbox-id> --checkpoint-type memory
    tl sbx checkpoint <sandbox-id> --timeout 600
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    from tensorlake.sandbox import CheckpointType, Sandbox

    sandbox = Sandbox.create()
    sandbox.run("pip", ["install", "numpy", "pandas", "--user", "--break-system-packages"])
    sandbox.run("python", ["-c", "import pandas as pd; pd.DataFrame({'a': [1,2,3]}).to_csv('/data/output.csv')"])

    # Default (server-side default, currently `filesystem`).
    snapshot = sandbox.checkpoint()

    # Explicitly request a memory checkpoint (warm-restore VM memory + processes).
    snapshot = sandbox.checkpoint(checkpoint_type=CheckpointType.MEMORY)

    # Filesystem-only checkpoint (cold-boot from snapshot tarball).
    snapshot = sandbox.checkpoint(checkpoint_type=CheckpointType.FILESYSTEM)

    print(snapshot.snapshot_id)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    import { Sandbox, type CheckpointType } from "tensorlake";

    const sandbox = await Sandbox.create();

    await sandbox.run("pip", {
      args: [
        "install",
        "numpy",
        "pandas",
        "--user",
        "--break-system-packages",
      ],
    });
    await sandbox.run("python", {
      args: [
        "-c",
        "import pandas as pd; pd.DataFrame({'a': [1,2,3]}).to_csv('/data/output.csv')",
      ],
    });

    // Default (server-side default, currently `filesystem`).
    let snapshot = await sandbox.checkpoint();

    // Explicitly request a memory checkpoint (warm-restore VM memory + processes).
    snapshot = await sandbox.checkpoint({ checkpointType: "memory" });

    // Filesystem-only checkpoint (cold-boot from snapshot tarball).
    snapshot = await sandbox.checkpoint({ checkpointType: "filesystem" });

    console.log(snapshot?.snapshotId);
    ```
  </Tab>

  <Tab title="HTTP">
    ```bash theme={null}
    curl -X POST https://api.tensorlake.ai/sandboxes/<sandbox-id>/snapshot \
      -H "Authorization: Bearer $TL_API_KEY"
    ```
  </Tab>
</Tabs>

## Restoring from a Snapshot

Create a new sandbox from a snapshot.
If the snapshot is filesystem (default), the new sandbox restores the captured filesystem. You can change sandbox resources (CPU, memory, disk) for the new sandbox.
If the snapshot is memory, the new sandbox restores filesystem, memory, and running processes exactly as they were. Image, resources (CPUs, memory), entrypoint, and secrets come from the snapshot and cannot be changed at restore time. If you need different resources, create a fresh sandbox instead of restoring.
For filesystem snapshots, you can pass `--disk_mb` / `resources.disk_mb` at restore time to grow root disk size (growth-only).

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    tl sbx create --snapshot <snapshot-id>
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    restored = Sandbox.create(snapshot_id=snapshot.snapshot_id)

    result = restored.run("cat", ["/data/output.csv"])
    print(result.stdout)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    const restored = await Sandbox.create({
      snapshotId: snapshot.snapshotId,
    });

    const result = await restored.run("cat", {
      args: ["/data/output.csv"],
    });
    console.log(result.stdout);
    ```
  </Tab>

  <Tab title="HTTP">
    ```bash theme={null}
    curl -X POST https://api.tensorlake.ai/sandboxes \
      -H "Authorization: Bearer $TL_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"snapshot_id": "<snapshot-id>"}'
    ```
  </Tab>
</Tabs>

## Clone a Sandbox

`tl sbx clone` creates a `memory` checkpoint and immediately boots a new sandbox from it, so the clone warm-restores filesystem, memory, and running processes from the source. The intermediate snapshot persists — it shows up in `tl sbx checkpoint ls` and counts toward storage until you delete it with `tl sbx checkpoint rm <snapshot-id>`.

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    tl sbx clone <sandbox-id>
    tl sbx clone <sandbox-id> --timeout 600
    ```
  </Tab>

  <Tab title="Python">
    Not supported in the Python SDK.
  </Tab>

  <Tab title="TypeScript">
    Not yet exposed in the TypeScript SDK. Use the CLI for one-step clone workflows, or call `checkpoint()` followed by `Sandbox.create()` explicitly.
  </Tab>

  <Tab title="HTTP">
    Not supported in the HTTP API.
  </Tab>
</Tabs>

## Managing Snapshots

### List Snapshots

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    tl sbx checkpoint ls
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    snapshots = sandbox.list_snapshots()
    for s in snapshots:
        print(
            f"{s.snapshot_id} | {s.status.value} | {s.snapshot_type.value if s.snapshot_type else '-'} | {s.size_bytes} bytes"
        )
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    const snapshots = await sandbox.listSnapshots();
    for (const snapshot of snapshots) {
      console.log(
        `${snapshot.snapshotId} | ${snapshot.status} | ${snapshot.snapshotType ?? "-"} | ${snapshot.sizeBytes ?? 0} bytes`,
      );
    }
    ```
  </Tab>

  <Tab title="HTTP">
    ```bash theme={null}
    curl https://api.tensorlake.ai/snapshots \
      -H "Authorization: Bearer $TL_API_KEY"
    ```
  </Tab>
</Tabs>

### Get Snapshot Details

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    const info = await Sandbox.getSnapshot("snapshot-id");
    console.log(info.status, info.snapshotType, info.baseImage, info.sizeBytes);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    info = Sandbox.get_snapshot("snapshot_id")
    print(info.status, info.snapshot_type)
    ```
  </Tab>

  <Tab title="HTTP">
    ```bash theme={null}
    curl https://api.tensorlake.ai/snapshots/<snapshot-id> \
      -H "Authorization: Bearer $TL_API_KEY"
    ```
  </Tab>

  <Tab title="CLI">
    Not supported in the CLI.
  </Tab>
</Tabs>

### Delete a Snapshot

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    tl sbx checkpoint rm <snapshot-id>
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    await Sandbox.deleteSnapshot("snapshot-id");
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    Sandbox.delete_snapshot("snapshot_id")
    ```
  </Tab>

  <Tab title="HTTP">
    ```bash theme={null}
    curl -X DELETE https://api.tensorlake.ai/snapshots/<snapshot-id> \
      -H "Authorization: Bearer $TL_API_KEY"
    ```
  </Tab>
</Tabs>

## `checkpoint()` Parameters

| Parameter         | Type                                                                                  | Default                                 | Description                                                                                                                 |
| ----------------- | ------------------------------------------------------------------------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `sandbox_id`      | `str`                                                                                 | —                                       | ID of the running sandbox to snapshot                                                                                       |
| `checkpoint_type` | `CheckpointType` (Python) / `CheckpointType` (TypeScript: `"memory" \| "filesystem"`) | server default (currently `filesystem`) | Checkpoint type. `FILESYSTEM` captures filesystem-only state; `MEMORY` captures filesystem + VM memory + running processes. |
| `timeout`         | `float`                                                                               | `300`                                   | Max seconds to wait for completion                                                                                          |
| `poll_interval`   | `float`                                                                               | `1.0`                                   | Seconds between status polls                                                                                                |

`CheckpointType` is exported from `tensorlake.sandbox` (Python) and `tensorlake` (TypeScript). The TypeScript field on `CheckpointOptions` is `checkpointType`.

## Related Guides

<CardGroup cols={2}>
  <Card title="Lifecycle" icon="arrows-spin" href="/sandboxes/lifecycle">
    Create, suspend, resume, and terminate sandboxes — the operations snapshots build on.
  </Card>

  <Card title="Sandbox Images" icon="box" href="/sandboxes/images">
    Build reusable base images. Pair with snapshots for warm starts on top of pinned dependencies.
  </Card>

  <Card title="Computer Use" icon="desktop" href="/sandboxes/computer-use">
    Snapshot a warmed-up `ubuntu-vnc` desktop and fork parallel agent sessions.
  </Card>

  <Card title="Drive Chrome over CDP" icon="chrome" href="/sandboxes/chrome-cdp">
    Snapshot a Chrome profile so parallel browser agents start with cookies and history already in place.
  </Card>
</CardGroup>