Snapshot, Rollback & Clone
This guide covers three advanced APIs provided by the Cube Sandbox Python SDK:
- Snapshot: Persists the state of a running sandbox as a reusable image. A full snapshot keeps memory and filesystem; an fs-only snapshot keeps the filesystem alone. Either can spawn new sandboxes; rollback requires a full snapshot.
- Clone: Calls
clone()on a running sandbox to immediately derive N fully independent copies. Each copy starts from the source sandbox's current state and runs in isolation. - Rollback: Restores a running sandbox to a previously captured snapshot state in place — the sandbox ID stays the same and execution can continue right away.
Concept
| API | Target | Sandbox ID | Typical use |
|---|---|---|---|
sb.create_snapshot() | The source sandbox itself | Unchanged | Create a checkpoint or persist state |
sb.clone(n=N) | Derive N new sandboxes from a running sandbox | N new IDs | Agent parallel rollout, repeatable experiments |
sb.rollback(snap_id) | Restore the current sandbox to a snapshot state | Unchanged | Undo a failed step, branch from a saved point |
Installation
Note: Snapshot, rollback, and clone are Cube Sandbox-exclusive capabilities — the e2b SDK has no equivalent APIs. The
cubesandboxSDK is compatible with the e2b SDK and can be used as a drop-in replacement, while adding these advanced features.
All APIs in this guide require cubesandbox 0.2.0 or later.
pip install "cubesandbox>=0.2.0"Environment variables used throughout the examples:
export CUBE_API_URL=http://127.0.0.1:3000
export CUBE_TEMPLATE_ID=tpl-xxxxxxxxxxxxxxxxxxxxxxxxSnapshot
sb.create_snapshot() persists the sandbox's current state (filesystem + memory) as a snapshot and returns a SnapshotInfo object. An optional name must not start with tpl- or snap- (rejected with HTTP 400), since those prefixes denote IDs. The snapshot_id field can be passed directly to Sandbox.create(template=...).
from cubesandbox import Sandbox
with Sandbox.create(template=TEMPLATE_ID) as sb:
sb.run_code("open('/tmp/data.txt','w').write('hello')")
snap = sb.create_snapshot()
print(f"snapshot: {snap.snapshot_id}")A snapshot's lifecycle is independent of the sandbox: the snapshot remains usable even after the source sandbox is kill()ed. Call Sandbox.delete_snapshot(snapshot_id_or_name) to clean up when it is no longer needed. It accepts either a snapshot ID or the name you passed to create_snapshot, and returns True when the snapshot was deleted or False when it did not exist. The SDK only matches snapshots, never templates: a name that matches no snapshot returns False even if a template alias has that name, and the template is left untouched. If a name matches several snapshots the call fails with HTTP 409 and nothing is deleted; use the snap- ID instead. This requires a CubeAPI that supports snapshot_only; older servers ignore it and still route a name that matches no snapshot to the template of that name.
Filesystem-only snapshots
Pass mode="fs-only" to capture the filesystem without guest memory. The guest is never paused: it keeps running and stays writable as soon as the call returns. The price is that a sandbox created from such a snapshot cold boots — the files are there, but every process is new.
snap = sb.create_snapshot(mode="fs-only")
assert snap.mode == "fs-only"
child = Sandbox.create(template=snap.snapshot_id)
# Files written before the snapshot are visible...
out = child.run_code("print(open('/tmp/data.txt').read())").logs.stdout[0]
assert out.strip() == "hello"
# ...but processes are not.What to expect:
| Aspect | mode="full" (default) | mode="fs-only" |
|---|---|---|
| Guest memory | saved | not saved |
| Source sandbox during the call | briefly paused | stays running |
| Sandbox created from it | memory restored, processes continue | cold boot, fresh processes |
pause() / resume() afterwards | memory kept | memory kept (first pause is a full capture) |
rollback(snapshot) to it | supported | rejected (snapshot_filesystem_only_rollback_unsupported) |
| External mounts (plugin volume, host mount) | recorded in the snapshot and re-mounted | not recorded; re-declare them when you create from the snapshot |
restart with a restart policy | files preserved | files preserved (the captured writable layer is reused) |
A few behaviors worth knowing:
- Every fs-only snapshot is an independent point-in-time image, not an incremental chain — take N snapshots and you store N images. Size for that rather than assuming "filesystem only, so it must be small"; the real footprint depends on the backend's CoW support.
- A sandbox created from an fs-only snapshot behaves like any other sandbox afterwards:
restartreuses the captured writable layer so files survive, and you can take another fs-only snapshot of it later. - An fs-only package records the root filesystem only and carries no external mounts. Creating from one:
- Re-declare the plugin volumes and host mounts you need, including the container paths; anything omitted is not mounted.
- There is no must-match check: the snapshot records no mounts, so the request alone decides.
- The child may run on any node and a declared host path is resolved there; a mount that cannot be established (host path missing, Volume gone) fails the create instead of leaving an empty directory.
If the call fails, the error code tells you why:
| HTTP | Error code | Cause | What to do |
|---|---|---|---|
| 409 | snapshot_filesystem_only_unsupported_node | The control plane or the node agent does not support the fs-only mode | Upgrade whichever side is older; it never falls back to a full snapshot silently |
| 409 | snapshot_filesystem_only_freeze_unsupported / snapshot_filesystem_only_rootfs_unsupported | The node cannot freeze the filesystem / this rootfs type | Cluster-side capability gap; check the node before retrying |
| 5xx | snapshot_filesystem_only_freeze_failed / snapshot_filesystem_only_thaw_failed | Freeze or thaw failed mid-capture | Cluster-side problem; check the node before retrying |
| 409 | snapshot_filesystem_only_shared_volume_unsupported | The sandbox has a writable plugin volume | A writable plugin volume is not part of the captured rootfs; create the sandbox without it before taking the snapshot |
| 409 | snapshot_filesystem_only_multi_container_unsupported | The sandbox has extra user containers | One package records one writable layer; use a single-container sandbox |
The response mode always reports what was actually recorded. When it differs from what you asked for, the call fails with 409 snapshot_mode_conflict instead of returning the artifact, so you never silently receive a full snapshot.
Listing snapshots
# List snapshots (first page)
items, next_token = Sandbox.list_snapshots()
# Filter by sandbox_id
items, _ = Sandbox.list_snapshots(sandbox_id=sb.sandbox_id)list_snapshots() returns (list[SnapshotInfo], next_token). Pass next_token back to retrieve subsequent pages; None means no more pages.
Clone
Calling sb.clone(n=N) on a running sandbox immediately derives N independent copies. Each copy fully inherits the source sandbox's runtime state at the moment of the clone call — memory and filesystem alike — but subsequent writes are fully isolated. The source sandbox keeps running unaffected.
src = Sandbox.create(template=TEMPLATE_ID)
src.run_code("open('/tmp/shared.txt','w').write('hello')")
clones = src.clone(n=3)
for sb in clones:
# Each clone inherits the file written in src
out = sb.run_code("print(open('/tmp/shared.txt').read())").logs.stdout[0]
assert out.strip() == "hello"Concurrent clone
By default clones are created serially. Pass concurrency=C for fan-out scenarios:
clones = src.clone(n=10, concurrency=5)- If any sub-task fails, already-created clones are automatically
kill()ed. The caller either gets all N sandboxes or an exception — no orphaned resources.
Inheritance and isolation
Clones returned by clone() satisfy three properties:
| Property | Meaning |
|---|---|
| Inheritance | Each clone's initial state is identical to the source sandbox at the moment of the clone call |
| Isolation | Writes in one clone are invisible to others and to the source sandbox |
| Continuity | The source sandbox keeps running after clone() returns, unaffected |
Fork
sb.fork(count=N) derives N running copies in a single server-side call: the backend snapshots the source once and derives every copy from that snapshot. The source keeps running, and the temporary snapshot is managed by the server — no client-side cleanup.
src = Sandbox.create(template=TEMPLATE_ID)
forks = src.fork(count=3)
for sb in forks:
if isinstance(sb, Sandbox):
sb.run_code("print('alive')") # a running copy
else:
print(f"fork failed: {sb}") # that slot's exceptionEach fork succeeds or fails independently. The return value has exactly count entries — a Sandbox or the Exception that prevented that fork from starting. Partial success keeps the copies and does not raise; only whole-request failures raise (e.g. the source sandbox does not exist).
clone vs fork
clone(n=N) | fork(count=N) | |
|---|---|---|
| Failure semantics | All-or-nothing: failures kill siblings and raise | Per-fork independent: partial success keeps winners |
| Orchestration | Client-side: snapshot + N creates | One server-side call (single snapshot, N derivations) |
| Temp snapshot | Deleted by the SDK after the last clone is killed | Managed by the server |
| Concurrency | concurrency option (default 1) | Server-governed |
Parameters and errors
count: 1..100, default 1. Out-of-range values raise in every SDK.timeout— idle TTL of the forked sandboxes; the source is unaffected. Units differ per SDK: seconds (Python), milliseconds viatimeoutMs(Node), atime.Duration(Go). The wire unit is seconds.404source sandbox not found.409source not in a forkable state — a freshly created sandbox may need a moment before it can be snapshotted; retry shortly.
Rollback
sb.rollback(snapshot_id) restores the sandbox in place to the specified snapshot state: the filesystem is fully reset, the sandbox ID stays the same, and the sb object remains usable. Rollback requires a full snapshot — rolling back to an fs-only snapshot is rejected with snapshot_filesystem_only_rollback_unsupported (see the comparison table above).
sb = Sandbox.create(template=TEMPLATE_ID)
sb.run_code("open('/tmp/v.txt','w').write('v1')")
checkpoint = sb.create_snapshot()
sb.run_code("open('/tmp/v.txt','w').write('v2')")
sb.rollback(checkpoint.snapshot_id)
after = sb.run_code("print(open('/tmp/v.txt').read())").logs.stdout[0]
assert after.strip() == "v1"After a rollback the sandbox is still writable. You can continue execution and snapshot again — ideal for agent retry loops where you checkpoint at each key decision point, roll back on failure, and try a different branch:
# Continue on the rolled-back branch
sb.run_code("open('/tmp/v.txt','w').write('v3')")
new_snap = sb.create_snapshot()
with Sandbox.create(template=new_snap.snapshot_id) as forked:
out = forked.run_code("print(open('/tmp/v.txt').read())").logs.stdout[0]
assert out.strip() == "v3"Best practices
- Snapshots are not free. Each snapshot corresponds to a full image in persistent storage. Delete snapshots when they are no longer needed, or run
list_snapshots()periodically to clean up. withblocks do not delete snapshots. The context manager only callskill()on the sandbox. Snapshots created withcreate_snapshot()must be deleted explicitly withSandbox.delete_snapshot().clone()cleans up its internal snapshot automatically. For temporary fan-out you do not need to manage snapshot lifecycle yourself — just callclone().- For large-scale fan-out, prefer
fork(count=N)— one round-trip, per-fork independence, server-managed cleanup. Useclone(n=N, concurrency=C)when you need all-or-nothing semantics.
Reference
- Cross-Node Migration — shared backends,
remote_status=ready, and scheduler rules for Resume / FromSnap on another node - Example code:
examples/snapshot-rollback-clone/ - SDK source:
sdk/python/