Sandbox snapshots - Docs by LangChain

A snapshot is a reusable filesystem bundle backed by a Docker image. Build or capture a snapshot when you want to boot sandboxes from a custom filesystem image. You can also capture a snapshot from a running sandbox—install packages, write data files, or configure state, then snapshot the result and reuse it as a new starting point.

Build a snapshot from a Docker image

Build a snapshot by pointing at any Docker image. The call blocks until the snapshot is ready (default timeout is 60 seconds; bump it for large images).

from langsmith.sandbox import SandboxClient

client = SandboxClient()

snapshot = client.create_snapshot(
    "python",
    docker_image="python:3.12-slim",
    fs_capacity_bytes=1 * 1024**3,  # 1 GiB
)

print(snapshot.id)

import { SandboxClient } from "langsmith/sandbox";

const client = new SandboxClient();

const snapshot = await client.createSnapshot(
  "python",
  "python:3.12-slim",
  1_073_741_824, // 1 GiB
);

console.log(snapshot.id);

Private registries

To pull from a private registry, create a registry once with its credentials, then reference it by id when building a snapshot. Registries persist, so reuse one across snapshots.

import os

registry = client.registries.create(
    name="internal",
    url="registry.example.com",
    username="me",
    password=os.environ["REGISTRY_PASSWORD"],
)

snapshot = client.create_snapshot(
    "internal-python",
    docker_image="registry.example.com/internal/python:3.12",
    fs_capacity_bytes=2 * 1024**3,
    registry_id=registry.id,
    timeout=600,
)

const registry = await client.registries.create({
  name: "internal",
  url: "registry.example.com",
  username: "me",
  password: process.env.REGISTRY_PASSWORD,
});

const snapshot = await client.createSnapshot(
  "internal-python",
  "registry.example.com/internal/python:3.12",
  2_147_483_648,
  {
    registryId: registry.id,
    timeout: 600,
  },
);

List, inspect, update, and delete registries with client.registries.list(), client.registries.retrieve(name), client.registries.update(name, ...), and client.registries.delete(name).

Build a snapshot from a Dockerfile

When you have a local Dockerfile but don’t want to publish the image to a registry first, build a snapshot directly from the Dockerfile and its build context. LangSmith spins up a temporary builder sandbox, uploads the context, runs the build inside it with BuildKit, and captures the resulting image as a snapshot. The builder sandbox is torn down automatically once the build finishes. The call blocks until the snapshot is ready (default timeout is 60 seconds; raise it for large or slow builds). fs_capacity_bytes must be large enough to hold the build context, the intermediate layers, and the final image.

from langsmith.sandbox import SandboxClient

client = SandboxClient()

snapshot = client.create_snapshot_from_dockerfile(
    "my-app",
    dockerfile="Dockerfile",
    fs_capacity_bytes=2 * 1024**3,  # 2 GiB
    context=".",  # build context directory (default: current directory)
)

print(snapshot.id)

import { SandboxClient } from "langsmith/sandbox";

const client = new SandboxClient();

const snapshot = await client.createSnapshotFromDockerfile(
  "my-app",
  "Dockerfile",
  2_147_483_648, // 2 GiB
  { context: "." },
);

console.log(snapshot.id);

dockerfile is resolved relative to context unless you pass an absolute path, and it must live inside the context directory. The .git directory is excluded from the uploaded context automatically.

Build args and target stage

Pass build_args / buildArgs to set Docker ARG values, and target to stop at a specific stage of a multi-stage build.

snapshot = client.create_snapshot_from_dockerfile(
    "my-app",
    dockerfile="Dockerfile",
    fs_capacity_bytes=2 * 1024**3,
    build_args={"PYTHON_VERSION": "3.12", "ENV": "prod"},
    target="runtime",
)

const snapshot = await client.createSnapshotFromDockerfile(
  "my-app",
  "Dockerfile",
  2_147_483_648,
  {
    buildArgs: { PYTHON_VERSION: "3.12", ENV: "prod" },
    target: "runtime",
  },
);

Stream build logs

Pass a callback to on_build_log / onBuildLog to receive the build’s stdout and stderr as it runs, which is useful for surfacing progress or debugging a failing build.

snapshot = client.create_snapshot_from_dockerfile(
    "my-app",
    dockerfile="Dockerfile",
    fs_capacity_bytes=2 * 1024**3,
    on_build_log=lambda line: print(line, end=""),
)

const snapshot = await client.createSnapshotFromDockerfile(
  "my-app",
  "Dockerfile",
  2_147_483_648,
  { onBuildLog: (line) => process.stdout.write(line) },
);

Speed up cold builds

vcpus / vCpus and mem_bytes / memBytes size the temporary builder sandbox. The build runs BuildKit plus the native snapshotter’s layer copies inside it, which contend for the builder’s default 0.5 vCPU, so giving the builder more CPU can cut a cold build’s wall time substantially. Memory is tied to CPU at 4 GiB per vCPU and must stay within 50% of that target, so a 2-vCPU builder accepts 4 to 12 GiB. Omit memory and it follows the ratio.

snapshot = client.create_snapshot_from_dockerfile(
    "my-app",
    dockerfile="Dockerfile",
    fs_capacity_bytes=2 * 1024**3,
    vcpus=2,
    mem_bytes=8 * 1024**3,  # 8 GiB
    timeout=600,
)

const snapshot = await client.createSnapshotFromDockerfile(
  "my-app",
  "Dockerfile",
  2_147_483_648,
  {
    vCpus: 2,
    memBytes: 8_589_934_592, // 8 GiB
    timeout: 600,
  },
);

Both the sync SandboxClient and the AsyncSandboxClient expose this method with the same arguments—await client.create_snapshot_from_dockerfile(...) on the async client.

Capture a snapshot from a running sandbox

Start a sandbox from an existing snapshot, install packages or prepare data, then capture the result as a new snapshot. The returned snapshot has its source_sandbox_id set to the sandbox it was captured from, and can be used as the snapshot_id for any later create_sandbox call.

sb = client.create_sandbox(snapshot_id=base_snapshot_id, name="setup-box")
sb.run("pip install numpy pandas scikit-learn", timeout=180)
sb.write("/opt/config.yaml", "model: gpt-5\n")

# Capture the current filesystem as a new snapshot
snapshot = sb.capture_snapshot("ml-ready")
print(snapshot.id, snapshot.source_sandbox_id)

sb.delete()

# Boot fresh sandboxes pre-loaded with those dependencies
with client.sandbox(snapshot_id=snapshot.id) as sb:
    sb.run("python -c 'import numpy; print(numpy.__version__)'")
    assert sb.read("/opt/config.yaml") == b"model: gpt-5\n"

const running = await client.createSandbox(baseSnapshotId, { name: "setup-box" });
await running.run("pip install numpy pandas scikit-learn", { timeout: 180 });
await running.write("/opt/config.yaml", "model: gpt-5\n");

const snapshot = await running.captureSnapshot("ml-ready");
console.log(snapshot.id, snapshot.source_sandbox_id);

await running.delete();

const sandbox = await client.createSandbox(snapshot.id);
try {
  await sandbox.run("python -c 'import numpy; print(numpy.__version__)'");
  const cfg = await sandbox.read("/opt/config.yaml");
  console.log(new TextDecoder().decode(cfg));
} finally {
  await sandbox.delete();
}

By default, capture preserves the filesystem only. Installed packages (under /usr/local, /root, /opt, the home directory, etc.) and files you wrote to those locations are kept, as is /tmp. Only /dev/shm is a tmpfs, so everything else lives on the sandbox’s disk. Running processes, open sockets, and in-memory state are not carried over: boot the new sandbox and start the processes you need again, or capture memory too.

You can boot a sandbox from a snapshot by name instead of ID — handy when you know the human-readable label you captured with:

sb = client.create_sandbox(snapshot_name="ml-ready")

const sb = await client.createSandbox({ snapshotName: "ml-ready" });

Pass at most one of snapshot_id / snapshot_name (or snapshotId / snapshotName in TypeScript). Omit both to use the default runtime.

Tune capture timing

capture_snapshot blocks until the new snapshot is ready. Raise the timeout kwarg (default 60s) if your filesystem is large or your storage backend is slow.

snapshot = sb.capture_snapshot("ml-ready-v2", timeout=600)

const snapshot = await sb.captureSnapshot("ml-ready-v2", { timeout: 600 });

Resume from memory

A snapshot can carry the sandbox’s RAM alongside its filesystem. Boot from one and the sandbox resumes where it left off, with its processes still running, instead of cold-booting. Use this for environments that are slow to warm up, such as a loaded model or a started database.

Memory snapshots are available over the REST API only. The langsmith.sandbox Python and TypeScript clients do not expose these fields yet.

Capture memory by setting include_memory on a capture:

curl -X POST \
  "$LANGSMITH_ENDPOINT/api/v2/sandboxes/boxes/my-vm/snapshot" \
  -H "x-api-key: $LANGSMITH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "warm-model", "include_memory": true}'

The response reports memory_snapshot_size_bytes when memory was captured. include_memory requires a sandbox that is running or stopped, and it cannot be combined with checkpoint or docker_image. Some sandboxes run on an overlay filesystem runtime that cannot carry a memory image. Capturing one returns include_memory is not supported for overlay-rootfs sandboxes. LangSmith assigns that runtime, so it is not something you select per sandbox. Two fields on create control the other half:

Field	What it does
`restore_memory`	Omit it to resume from memory when the snapshot has it and cold-boot when it does not. `true` requires memory and fails the request if the snapshot has none. `false` always cold-boots.
`preserve_memory_on_stop`	`true` suspends RAM on a voluntary stop (idle timeout or explicit stop) so the sandbox resumes where it left off when it next wakes, rather than cold-booting. Defaults to `false`, which keeps only the filesystem. Restarts triggered by infrastructure maintenance preserve memory either way.

curl -X POST "$LANGSMITH_ENDPOINT/api/v2/sandboxes/boxes" \
  -H "x-api-key: $LANGSMITH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "warm-vm",
    "snapshot": "warm-model",
    "restore_memory": true,
    "preserve_memory_on_stop": true
  }'

Capturing memory from a stopped sandbox only works when that sandbox was created with preserve_memory_on_stop. Without it, the stop discards RAM and there is nothing to capture.

List, fetch, and delete snapshots

# List all snapshots in the workspace
snapshots = client.list_snapshots()
for s in snapshots:
    print(s.id, s.name, s.status)

# Fetch a single snapshot by ID
snapshot = client.get_snapshot("550e8400-e29b-41d4-a716-446655440000")

# Delete a snapshot (fails if any sandbox still references it)
client.delete_snapshot(snapshot.id)

const snapshots = await client.listSnapshots();
for (const s of snapshots) {
  console.log(s.id, s.name, s.status);
}

const snapshot = await client.getSnapshot("550e8400-e29b-41d4-a716-446655440000");

await client.deleteSnapshot(snapshot.id);

list_snapshots / listSnapshots paginates server-side (default page size 50, max 500) and accepts optional filters: name_contains / nameContains (case-insensitive substring on name), limit (1–500), and offset (≥ 0). Page through results by advancing offset.

page = client.list_snapshots(name_contains="ml", limit=100)

const page = await client.listSnapshots({ nameContains: "ml", limit: 100 });

Stopped sandboxes

A stopped sandbox keeps its filesystem, and the next request wakes it automatically. You do not need to start it yourself: send the command you wanted to run and the sandbox comes back up to serve it.

sb = client.create_sandbox(snapshot_id=snapshot.id, name="my-vm")
sb.run("echo 'hello' > /tmp/state.txt")

# Stop early to release resources. The idle timeout does this for you.
sb.stop()

# No start call: this wakes the sandbox and runs once it is up.
result = sb.run("cat /tmp/state.txt")
assert result.stdout.strip() == "hello"

const sb = await client.createSandbox(snapshot.id, { name: "my-vm" });
await sb.run("echo 'hello' > /tmp/state.txt");

await sb.stop();

const result = await sb.run("cat /tmp/state.txt");
console.log(result.stdout.trim()); // "hello"

The first request after a stop pays the boot cost, so it is slower than the ones that follow. Create the sandbox with preserve_memory_on_stop to resume from memory instead of cold-booting.

Next steps

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.

​Build a snapshot from a Docker image

​Private registries

​Build a snapshot from a Dockerfile

​Build args and target stage

​Stream build logs

​Speed up cold builds

​Capture a snapshot from a running sandbox

​Tune capture timing

​Resume from memory

​List, fetch, and delete snapshots

​Stopped sandboxes

​Next steps

Build a snapshot from a Docker image

Private registries

Build a snapshot from a Dockerfile

Build args and target stage

Stream build logs

Speed up cold builds

Capture a snapshot from a running sandbox

Tune capture timing

Resume from memory

List, fetch, and delete snapshots

Stopped sandboxes

Next steps