Skip to main content
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

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

​
SnapshotInfo model

FieldTypeDescription
snapshot_idstrUnique identifier in snap-* format
sandbox_idstrID of the sandbox that was snapshotted
created_atdatetimeWhen 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. 
# 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

​
List snapshots

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

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