Snapshots

A snapshot captures the complete state of a running sandbox — memory contents, filesystem, and process state — and saves it to persistent storage. Snapshots can be restored to create new sandboxes that resume exactly where the original left off.

Create a snapshot

Python
TypeScript

from declaw import Sandbox

sbx = Sandbox.create()

# Install dependencies and run setup
sbx.commands.run("pip3 install numpy pandas matplotlib")
sbx.files.write("/workspace/data.csv", data)

# Snapshot the ready-to-use state
snapshot = sbx.create_snapshot()
print(snapshot.snapshot_id)  # snap-abc123
print(snapshot.sandbox_id)   # sbx-def456
print(snapshot.created_at)   # 2024-01-15T10:00:00Z

sbx.kill()

const sbx = await Sandbox.create();

await sbx.commands.run('pip3 install numpy pandas matplotlib');

const snapshot = await sbx.createSnapshot();
console.log(snapshot.snapshotId);

await sbx.kill();

SnapshotInfo model

Field	Type	Description
`snapshot_id`	`str`	Unique identifier in `snap-*` format
`sandbox_id`	`str`	ID of the sandbox that was snapshotted
`created_at`	`datetime`	When the snapshot was taken

Restore from a snapshot

Pass a snapshot_id to Sandbox.create() to start a new sandbox that resumes from that state.

Python
TypeScript

# Create a fresh sandbox from the snapshot
sbx = Sandbox.create(snapshot_id="snap-abc123")

# The sandbox is already set up — libraries installed, files present
result = sbx.commands.run("python3 -c 'import pandas; print(pandas.__version__)'")
print(result.stdout)  # 2.1.0

result = sbx.commands.run("ls /workspace/")
print(result.stdout)  # data.csv

const sbx = await Sandbox.create({ snapshotId: 'snap-abc123' });

const result = await sbx.commands.run('ls /workspace/');
console.log(result.stdout);  // data.csv

List snapshots

Python

from declaw import Sandbox

paginator = Sandbox.list_snapshots(limit=20)
for snap in paginator:
    print(snap.snapshot_id, snap.sandbox_id, snap.created_at)

Lifecycle during snapshot

When create_snapshot() is called, the sandbox briefly pauses to capture a consistent memory image and then resumes automatically. The sandbox continues running after the snapshot completes. The snapshotting pause is typically under one second for sandboxes with 256 MB of RAM.

Use cases

Warm-start sandboxes

Install heavy ML libraries once, snapshot the result, then create new sandboxes from that snapshot for every request. Eliminates the pip install torch overhead from every run.

# One-time setup
setup_sbx = Sandbox.create()
setup_sbx.commands.run("pip3 install torch transformers sentence-transformers")
snap = setup_sbx.create_snapshot()
setup_sbx.kill()

# Fast warm-start for every agent run
agent_sbx = Sandbox.create(snapshot_id=snap.snapshot_id)
# torch is already installed

Checkpoint long-running tasks

Snapshot a sandbox mid-computation so you can restore it if the run fails.

sbx = Sandbox.create()
sbx.commands.run("python3 download_dataset.py")

# Checkpoint after expensive download
checkpoint = sbx.create_snapshot()

sbx.commands.run("python3 train_model.py")  # may fail
# If it fails, restore from checkpoint and retry

Branch sandbox state

Create multiple independent sandboxes from the same snapshot to explore different execution paths.

snap = base_sbx.create_snapshot()

# Explore two different approaches in parallel
branch_a = Sandbox.create(snapshot_id=snap.snapshot_id)
branch_b = Sandbox.create(snapshot_id=snap.snapshot_id)

branch_a.commands.run("python3 approach_a.py")
branch_b.commands.run("python3 approach_b.py")

Snapshots capture the state of a single sandbox at a point in time. They do not capture external state such as in-flight network connections, database transactions, or changes to services outside the sandbox.

Getting Started

Core Features

CLI

Security

Platform

Deployment

Architecture

Create a snapshot

SnapshotInfo model

Restore from a snapshot

List snapshots

Lifecycle during snapshot

Use cases

​Create a snapshot

​SnapshotInfo model

​Restore from a snapshot

​List snapshots

​Lifecycle during snapshot

​Use cases

Create a snapshot

SnapshotInfo model

Restore from a snapshot

List snapshots

Lifecycle during snapshot

Use cases