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.
flowchart LR
A[source sandbox<br/>running] -->|create_snapshot| S[(snapshot<br/>snap-xxx)]
A -->|clone n=N| C1[clone 1]
A -->|clone n=N| C2[clone 2]
A -->|clone n=N| Cn[clone N]
A -.->|rollback snap-xxx| A2[source sandbox<br/>restored to snapshot state]
classDef src fill:#e8f4fd,stroke:#3b82f6,stroke-width:2px;
classDef snap fill:#fef3c7,stroke:#f59e0b,stroke-width:2px;
classDef clone fill:#d1fae5,stroke:#10b981,stroke-width:1px;
class A,A2 src;
class S snap;
class C1,C2,Cn clone;
| 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 |
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-xxxxxxxxxxxxxxxxxxxxxxxxsb.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.
Set a TTL for temporary checkpoints, experiment snapshots or short-lived restore backups so they can be cleaned up automatically when no longer needed. Omit it or pass zero for snapshots you want to keep until explicitly deleted.
snap = sb.create_snapshot(name="checkpoint", ttl_seconds=3600)
print(snap.expires_at)
# Each restore creates a new sandbox while the snapshot is still valid.
restored = Sandbox.create(template=snap.snapshot_id)The TTL starts when the snapshot becomes ready. expires_at is its UTC expiration
time, or None without a TTL. Use SDK, CubeAPI and CubeMaster versions that
support snapshot expiration. Node accepts
sb.createSnapshot("checkpoint", { ttlSeconds: 3600 }); Go accepts
sb.CreateSnapshot(ctx, "checkpoint", cubesandbox.CreateSnapshotOptions{TTLSeconds: 3600}).
After expiration, the snapshot cannot be used for new restores or rollbacks. Sandboxes already running from it continue to work. Cleanup runs periodically; storage is released only after running sandboxes and other dependencies have released their references, so expiration does not free disk space immediately.
If a permanently lost node leaves a pending restore that prevents cleanup, an
administrator can use cubemastercli snapshot recover-create. First fence the
node so its VMs and queued requests cannot resume, retire the snapshot, and wait
at least 24 hours for the pending reservation:
cubemastercli snapshot recover-create \
--snapshot-id snap-example --sandbox-id reserved-example \
--node-id retired-node --node-ip 192.0.2.10 \
--confirm-node-fenced --reason "Host powered off and prevented from restarting"Use the node identity recorded for that pending restore. Recovery releases only the matching stale reservation; it refuses healthy nodes, known sandboxes and active snapshot operations. Physical cleanup continues on a later reconciliation pass. Normal expiration does not require this command.
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.
# 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.
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"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.
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 |
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(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 |
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.
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"- 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.
- 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/