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 a snapshot reaches completed, 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. Before running the examples, install the CLI or SDK and authenticate.

Snapshot Format

Content Addressable Streaming (CAS) is Tensorlake’s format for sandbox images and snapshots. A sandbox created from a CAS image or snapshot starts running before its contents have been downloaded from the underlying blob storage. The missing parts stream in the background at high throughput, while the memory and I/O requests the sandbox makes are served at high priority to keep their latency low. Images and snapshots are deduplicated, so only data that isn’t already cached locally is downloaded. The result is fast and consistent cold starts, with extra disk read latency only for a short time after creation. Users are only billed for unique bytes in their images and snapshots.

Creating a Snapshot

The CLI and checkpoint() wait until the snapshot is resumable (local_ready or completed). local_ready does not mean the snapshot has finished uploading to durable storage. To wait for completed, set wait_until="completed" in Python or waitUntil: "completed" in TypeScript.

CLI
Python
TypeScript
HTTP

tl sbx checkpoint your_sandbox_id
tl sbx checkpoint your_sandbox_id --checkpoint-type filesystem
tl sbx checkpoint your_sandbox_id --checkpoint-type memory
tl sbx checkpoint your_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("python3", ["-c", "import pandas as pd; pd.DataFrame({'a': [1,2,3]}).to_csv('/tmp/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 the captured filesystem).
# Wait for durable storage.
snapshot = sandbox.checkpoint(
    checkpoint_type=CheckpointType.FILESYSTEM,
    wait_until="completed",
)

assert snapshot is not None
print(snapshot.snapshot_id)

import { Sandbox } from "@tensorlakeai/tensorlake";

const sandbox = await Sandbox.create();

await sandbox.run("pip", {
  args: [
    "install",
    "numpy",
    "pandas",
    "--user",
    "--break-system-packages",
  ],
});
await sandbox.run("python3", {
  args: [
    "-c",
    "import pandas as pd; pd.DataFrame({'a': [1,2,3]}).to_csv('/tmp/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 the captured filesystem).
// Wait for durable storage.
snapshot = await sandbox.checkpoint({
  checkpointType: "filesystem",
  waitUntil: "completed",
});

if (!snapshot) {
  throw new Error("Snapshot was not returned");
}
console.log(snapshot.snapshotId);

curl -X POST https://api.tensorlake.ai/sandboxes/your_sandbox_id/snapshot \
  -H "Authorization: Bearer $TENSORLAKE_API_KEY"

The HTTP request returns a snapshot ID before the snapshot is ready. Poll snapshot details until its status is local_ready or completed before restoring it.

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. You can resize resources after restoring. For filesystem snapshots, you can pass --disk_mb in the CLI, disk_mb in Python, diskMb in TypeScript, or resources.disk_mb in HTTP at restore time to grow root disk size (growth-only).

CLI
Python
TypeScript
HTTP

tl sbx create --snapshot your_snapshot_id

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

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

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

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

curl -X POST https://api.tensorlake.ai/sandboxes \
  -H "Authorization: Bearer $TENSORLAKE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"snapshot_id": "your_snapshot_id"}'

Copy a Sandbox

Cloning a sandbox is done with tl sbx copy or sandbox.copy() in either SDK. It boots one or more new sandboxes from a running, suspended, or resume-failed source, restoring filesystem, memory, and running processes so each copy warm-starts. Use -n in the CLI or times in the SDKs to create several copies from the same source in one call. The source can be running, suspended, or resume_failed. A running source is copied directly from the executor hosting it. A suspended or resume-failed source uses its retained checkpoint, which must still be available and ready to copy. A recoverable resume failure preserves the original snapshot_id; it does not invalidate an otherwise usable checkpoint. Copying or exporting that checkpoint remains available subject to checkpoint readiness. A copy gets a new sandbox ID and does not retry the source. To recover the same sandbox, retry resume explicitly. 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. In the HTTP API, pass name to choose the name yourself; with more than one copy it is suffixed -1..-N.

CLI
Python
TypeScript
HTTP

tl sbx copy your_sandbox_id
tl sbx copy your_sandbox_id -n 4
tl sbx copy your_sandbox_id --timeout 600

copies = sandbox.copy(times=4, request_timeout=600)
for copied in copies.sandboxes:
    print(copied.sandbox_id, copied.status, copied.reason)

const copies = await sandbox.copy({ times: 4, requestTimeout: 600 });
for (const copied of copies.sandboxes) {
  console.log(copied.sandboxId, copied.status, copied.reason);
}

curl -X POST "https://api.tensorlake.ai/sandboxes/your_sandbox_id/copy?times=1" \
  -H "Authorization: Bearer $TENSORLAKE_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": "your_sandbox_id",
  "sandboxes": [
    { "sandbox_id": "your_copy_id", "status": "running", "sandbox_url": "your_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.

The SDKs return metadata for each copy. Inspect status and reason for partial failures. request_timeout in Python and requestTimeout in TypeScript set the copy request timeout in seconds.

Managing Snapshots

List Snapshots

The CLI and HTTP examples list snapshots in the current namespace. sandbox.list_snapshots() and sandbox.listSnapshots() list snapshots from that sandbox.

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 $TENSORLAKE_API_KEY"

Get Snapshot Details

TypeScript
Python
HTTP
CLI

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

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

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

Delete a Snapshot

CLI
TypeScript
Python
HTTP

tl sbx checkpoint rm your_snapshot_id

await Sandbox.deleteSnapshot("your_snapshot_id");

Sandbox.delete_snapshot("your_snapshot_id")

curl -X DELETE https://api.tensorlake.ai/snapshots/your_snapshot_id \
  -H "Authorization: Bearer $TENSORLAKE_API_KEY"

`checkpoint()` Parameters

Call checkpoint() on the sandbox handle with these options:

Python	TypeScript	Type	Default	Description
`wait`	`wait`	`bool` / `boolean`	`True` / `true`	Wait for the requested readiness condition
`checkpoint_type`	`checkpointType`	`CheckpointType`	Server default (currently `filesystem`)	`filesystem` captures filesystem-only state; `memory` captures filesystem, memory, and running processes
`wait_until`	`waitUntil`	`SnapshotWaitCondition` (Python also accepts `str`)	`"local_ready"`	`local_ready` accepts resumable or completed snapshots; `completed` waits for durable storage
`timeout`	`timeout`	`float` / `number`	`300`	Max seconds to wait when `wait` is true
`poll_interval`	`pollInterval`	`float` / `number`	`1.0`	Seconds between status polls when `wait` is true

With wait=True / wait: true, checkpoint() returns snapshot metadata. With wait=False / wait: false, it requests the snapshot without waiting and returns None in Python or undefined in TypeScript. CheckpointType and SnapshotWaitCondition are exported from tensorlake.sandbox (Python) and @tensorlakeai/tensorlake (TypeScript). TypeScript accepts "memory" / "filesystem" for checkpointType and "local_ready" / "completed" for waitUntil in CheckpointOptions.

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

Snapshot Format

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

​Snapshot Format

​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

Snapshot Format

Creating a Snapshot

Restoring from a Snapshot

Copy a Sandbox

Managing Snapshots

List Snapshots

Get Snapshot Details

Delete a Snapshot

`checkpoint()` Parameters

Related Guides