Skip to main content
Sandboxes are in private preview. APIs and features may change as we iterate. Sign up for the waitlist to get access.
A snapshot is a filesystem bundle backed by a Docker image. It is the required input to every sandbox: createSandbox / create_sandbox always takes a snapshot, either by ID (snapshot_id / snapshotId) or by name (snapshot_name / snapshotName). Build a snapshot once, then boot as many sandboxes from it as you need. 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. Sandboxes snapshots page

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

​
Private registries

Pass registry credentials (or a pre-registered registry_id / registryId) to pull from a private registry. 
import os

snapshot = client.create_snapshot(
    "internal-python",
    docker_image="registry.example.com/internal/python:3.12",
    fs_capacity_bytes=2 * 1024**3,
    registry_url="https://registry.example.com",
    registry_username="me",
    registry_password=os.environ["REGISTRY_PASSWORD"],
    timeout=600,
)

​
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"
Capture preserves the persistent filesystem only. Installed packages (under /usr/local, /root, /opt, the home directory, etc.) and files you wrote to those locations are kept. Running processes, open sockets, in-memory state, and anything under /tmp (which is a tmpfs) are not carried over — boot the new sandbox and start the processes you need again.
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")
Pass exactly one of snapshot_id / snapshot_name (or snapshotId / snapshotName in TypeScript).

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

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

​
Stop and start sandboxes

Sandboxes can be stopped and restarted without losing filesystem state. Files you wrote during the previous run are still there when the sandbox comes back up. 
sb = client.create_sandbox(snapshot_id=snapshot.id, name="my-vm")
sb.run("echo 'hello' > /tmp/state.txt")

# Stop the sandbox — preserves files on disk
sb.stop()

# Later: start it again (blocks until ready, default timeout=120s)
sb.start()

result = sb.run("cat /tmp/state.txt")
assert result.stdout.strip() == "hello"
You can also stop and start by name via the client directly (client.stop_sandbox(name) / client.start_sandbox(name) in Python, client.stopSandbox(name) / client.startSandbox(name) in TypeScript).

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