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

# Snapshot and Clone

> Save, restore, and clone 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), and entrypoint 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>

## Copy a Sandbox

Cloning a sandbox is done with `tl sbx copy`. It boots one or more new sandboxes from a running or suspended source, restoring filesystem, memory, and running processes so each copy warm-starts. Use `-n` to create several copies from the same source in one call.

The source must be running or suspended. A running source is copied directly from the executor hosting it, and a suspended source is copied from the snapshot its suspend already produced, so a copy does not leave a new checkpoint behind for you to clean up.

Copies inherit the source's image, resources, entrypoint, network policy, and exposed ports.

Names are unique per namespace, so copies cannot reuse the source's name. A copy of a named sandbox is named `<source-name>-copy` by default, which keeps it suspendable and resumable like its source; an unnamed sandbox terminates at its idle timeout instead. Pass `name` to choose the name yourself; with more than one copy it is suffixed `-1`..`-N`.

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    tl sbx copy <sandbox-id>
    tl sbx copy <sandbox-id> -n 4
    tl sbx copy <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 or the HTTP API, or call `checkpoint()` followed by `Sandbox.create()` explicitly.
  </Tab>

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

    `times` defaults to `1`, and `name` sets the copy name. The request takes no body. See the [API reference](/api-reference/v2/sandboxes/copy) for the full naming rules.

    A `200` means every requested copy is running:

    ```json theme={null}
    {
      "source_sandbox_id": "<sandbox-id>",
      "sandboxes": [
        { "sandbox_id": "<copy-id>", "status": "running", "sandbox_url": "..." }
      ]
    }
    ```

    A `422` means one or more copies failed before becoming ready, and a `504` means they did not become ready within the timeout. Both return the same body shape, so inspect each entry's `status` to see which copies succeeded.
  </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="Build and Import Images" icon="layer-group" href="/sandboxes/images">
    Build reusable 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>