Skip to content

Latest commit

 

History

History
288 lines (216 loc) · 15.2 KB

snapshot-rollback-clone.md

File metadata and controls

288 lines (216 loc) · 15.2 KB

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

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;
Loading
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 cubesandbox SDK 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-xxxxxxxxxxxxxxxxxxxxxxxx

Snapshot

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.

Snapshot expiration

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.

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: restart reuses 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 exception

Each 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 via timeoutMs (Node), a time.Duration (Go). The wire unit is seconds.
  • 404 source sandbox not found. 409 source 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.
  • with blocks do not delete snapshots. The context manager only calls kill() on the sandbox. Snapshots created with create_snapshot() must be deleted explicitly with Sandbox.delete_snapshot().
  • clone() cleans up its internal snapshot automatically. For temporary fan-out you do not need to manage snapshot lifecycle yourself — just call clone().
  • For large-scale fan-out, prefer fork(count=N) — one round-trip, per-fork independence, server-managed cleanup. Use clone(n=N, concurrency=C) when you need all-or-nothing semantics.

Reference