Tensorlake Documentation

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: 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 instead.

Creating a Snapshot

CLI
Python
TypeScript
HTTP

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

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)

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);

curl -X POST https://api.tensorlake.ai/sandboxes/<sandbox-id>/snapshot \
  -H "Authorization: Bearer $TL_API_KEY"

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

CLI
Python
TypeScript
HTTP

tl sbx create --snapshot <snapshot-id>

restored = Sandbox.create(snapshot_id=snapshot.snapshot_id)

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

const restored = await Sandbox.create({
  snapshotId: snapshot.snapshotId,
});

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

curl -X POST https://api.tensorlake.ai/sandboxes \
  -H "Authorization: Bearer $TL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"snapshot_id": "<snapshot-id>"}'

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.

CLI
Python
TypeScript
HTTP

tl sbx copy <sandbox-id>
tl sbx copy <sandbox-id> -n 4
tl sbx copy <sandbox-id> --timeout 600

Not yet exposed in the TypeScript SDK. Use the CLI or the HTTP API, or call checkpoint() followed by Sandbox.create() explicitly.

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 for the full naming rules.A 200 means every requested copy is running:

{
  "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.

Managing Snapshots

List Snapshots

CLI
Python
TypeScript
HTTP

tl sbx checkpoint ls

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"
    )

const snapshots = await sandbox.listSnapshots();
for (const snapshot of snapshots) {
  console.log(
    `${snapshot.snapshotId} | ${snapshot.status} | ${snapshot.snapshotType ?? "-"} | ${snapshot.sizeBytes ?? 0} bytes`,
  );
}

curl https://api.tensorlake.ai/snapshots \
  -H "Authorization: Bearer $TL_API_KEY"

Get Snapshot Details

TypeScript
Python
HTTP
CLI

const info = await Sandbox.getSnapshot("snapshot-id");
console.log(info.status, info.snapshotType, info.baseImage, info.sizeBytes);

info = Sandbox.get_snapshot("snapshot_id")
print(info.status, info.snapshot_type)

curl https://api.tensorlake.ai/snapshots/<snapshot-id> \
  -H "Authorization: Bearer $TL_API_KEY"

Delete a Snapshot

CLI
TypeScript
Python
HTTP

tl sbx checkpoint rm <snapshot-id>

await Sandbox.deleteSnapshot("snapshot-id");

Sandbox.delete_snapshot("snapshot_id")

curl -X DELETE https://api.tensorlake.ai/snapshots/<snapshot-id> \
  -H "Authorization: Bearer $TL_API_KEY"

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

Lifecycle

Create, suspend, resume, and terminate sandboxes: the operations snapshots build on.

Build and Import Images

Build reusable images. Pair with snapshots for warm starts on top of pinned dependencies.

Computer Use

Snapshot a warmed-up ubuntu-vnc desktop and fork parallel agent sessions.

Drive Chrome over CDP

Snapshot a Chrome profile so parallel browser agents start with cookies and history already in place.

Overview

Guides

Use Cases

Snapshot and Clone

Creating a Snapshot

Restoring from a Snapshot

Copy a Sandbox

Managing Snapshots

List Snapshots

Get Snapshot Details

Delete a Snapshot

`checkpoint()` Parameters

Lifecycle

Build and Import Images

Computer Use

Drive Chrome over CDP

​Creating a Snapshot

​Restoring from a Snapshot

​Copy a Sandbox

​Managing Snapshots

​List Snapshots

​Get Snapshot Details

​Delete a Snapshot

​checkpoint() Parameters

​Related Guides

Lifecycle

Build and Import Images

Computer Use

Drive Chrome over CDP

Creating a Snapshot

Restoring from a Snapshot

Copy a Sandbox

Managing Snapshots

List Snapshots

Get Snapshot Details

Delete a Snapshot

`checkpoint()` Parameters

Related Guides