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

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>"}'

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

CLI
Python
TypeScript
HTTP

tl sbx clone <sandbox-id>
tl sbx clone <sandbox-id> --timeout 600

Not yet exposed in the TypeScript SDK. Use the CLI for one-step clone workflows, or call checkpoint() followed by Sandbox.create() explicitly.

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.

Sandbox Images

Build reusable base 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

Snapshots

Creating a Snapshot

Restoring from a Snapshot

Clone a Sandbox

Managing Snapshots

List Snapshots

Get Snapshot Details

Delete a Snapshot

`checkpoint()` Parameters

Lifecycle

Sandbox Images

Computer Use

Drive Chrome over CDP

Overview

Guides

Use Cases

Documentation Index

​Creating a Snapshot

​Restoring from a Snapshot

​Clone a Sandbox

​Managing Snapshots

​List Snapshots

​Get Snapshot Details

​Delete a Snapshot

​checkpoint() Parameters

​Related Guides

Lifecycle

Sandbox Images

Computer Use

Drive Chrome over CDP

Creating a Snapshot

Restoring from a Snapshot

Clone a Sandbox

Managing Snapshots

List Snapshots

Get Snapshot Details

Delete a Snapshot

`checkpoint()` Parameters

Related Guides