How CubeSandbox Snapshot, Clone, and Rollback Work at Hundred-Millisecond Granularity

CubeSandbox achieves sub-second checkpoint operations by using a copy-on-write (CoW) engine that captures VM memory and disk state through metadata-only snapshots, enabling snapshots, clones, and rollbacks in approximately 90 milliseconds.

The TencentCloud/CubeSandbox repository implements a high-performance sandboxing platform designed for AI workloads requiring rapid state management. Its CubeCoW engine leverages RustVMM and KVM to provide copy-on-write snapshotting of both memory pages and ext4-based root filesystems without copying underlying data blocks. This architecture allows developers to checkpoint, branch, and rewind sandbox states at event-level granularity suitable for real-time applications.

The CubeCoW Architecture

The snapshot system rests on three integrated layers that bridge low-level virtualization APIs to high-level SDK operations.

CubeCoW Engine (RustVMM + KVM) provides the core cubecow.Engine interface for volume creation, snapshotting, and activation. The Go CowVolumeManager wraps these primitives in Cubelet/storage/cubecow_volume_manager.go, exposing high-level operations to the HTTP API layer. Finally, the Python SDK in sdk/python/cubesandbox/sandbox.py offers client-side methods like create_snapshot(), clone(), and rollback() that invoke the underlying HTTP endpoints.

How Snapshots Work

Snapshots in CubeSandbox are metadata-only operations that create a new generation of the root filesystem without duplicating data blocks.

When the SDK calls POST /sandboxes/:id/snapshots, the CowVolumeManager.RollbackDeriveNewGen function creates a snapshot volume using CoW reflinks. This function—defined in Cubelet/storage/cubecow_volume_manager.go—resolves the device path and resizes the snapshot if necessary:

func (m *CowVolumeManager) RollbackDeriveNewGen(
    ctx context.Context, sandboxID, snapshotRootfsVol string,
    gen uint32, desiredSizeBytes uint64) (*cowVolume, error) {

    snapshotName := fmt.Sprintf("sb-%s-rootfs-gen%d", sandboxID, gen)
    devPath, err := m.createOrResolveSnapshotPathFromSource(
        ctx, snapshotRootfsVol, snapshotName)
    if err != nil {
        return nil, err
    }
    // Resize if the snapshot is smaller than requested
    if resized, _ := m.resizeSnapshotIfTooSmall(snapshotName, desiredSizeBytes); resized {
        devPath, _ = m.ResolveDevPath(ctx, snapshotName, cowKindSnapshot)
    }
    return newCowVolume(snapshotName, cowKindSnapshot, gen, devPath), nil
}

The engine.CreateSnapshot(..., true) call establishes a reflink to the source volume, sharing unchanged blocks while tracking new modifications separately. Because only metadata describing the new generation is written, the operation completes without copying the entire disk image.

How Cloning Works

Cloning creates an ephemeral snapshot that serves as a template for spawning multiple new sandboxes, then automatically discards the temporary checkpoint.

The process follows three steps implemented in sandbox.py (lines 776-800):

1. Create temporary snapshot using the same RollbackDeriveNewGen API used for standard snapshots
2. Spawn N sandboxes in parallel using Sandbox.create(template=snapshotID) with a configurable concurrency parameter
3. Delete the ephemeral snapshot once all children are running

This fan-out pattern allows developers to create multiple isolated environments from a single state:

src = Sandbox.create(template="tpl-abcdef")
src.run_code("open('/tmp/shared.txt','w').write('hello')")

clones = src.clone(n=4, concurrency=2)   # Spawns 4 sandboxes from ephemeral snapshot

for child in clones:
    out = child.run_code("cat /tmp/shared.txt").logs.stdout[0]
    assert out.strip() == "hello"

The concurrency parameter reduces wall-time by running multiple Sandbox.create operations simultaneously, while the underlying CoW mechanism ensures each clone starts instantly without duplicating the base filesystem.

How Rollback Works

Rollback performs an in-place restore that restarts the sandbox from a previous snapshot while preserving the same sandbox ID.

When the SDK invokes POST /sandboxes/:id/rollback, the CowVolumeManager activates the snapshot volume and reattaches it as the sandbox's root filesystem. The VM process restarts from the saved memory pages and disk state, effectively "jumping" to the checkpoint without requiring a full boot sequence.

The Python SDK handles connection management during this transition by resetting pooled HTTP connections:

from cubesandbox import Sandbox

sb = Sandbox.create(template="tpl-abcdef")
sb.run_code("open('/tmp/v.txt','w').write('v1')")
snap = sb.create_snapshot()          # Checkpoint current state

sb.run_code("open('/tmp/v.txt','w').write('v2')")  # Modify state

sb.rollback(snap.snapshot_id)        # Restore to checkpoint

sb._reset_connections()              # Reset HTTP connections for fresh socket

assert sb.run_code("cat /tmp/v.txt").logs.stdout[0].strip() == "v1"

Because the snapshot already points to the exact memory pages and filesystem state captured at creation, the rollback completes as a metadata operation rather than a data restoration process.

Performance Characteristics

CubeSandbox achieves hundred-millisecond granularity through incremental dirty-page tracking and zero-copy block sharing.

According to the benchmark documentation in docs/blog/posts/2026-06-03-cubesandbox-perf-benchmark-pvm.md, the system delivers:

• ~90 ms for single rollback operations
• ~65 ms per rollback when running 5 parallel rollbacks (326 ms total)
• Similar latency for clone operations since they reuse the same snapshot creation step

The performance stems from tracking only pages modified since the last snapshot. Unchanged blocks remain shared via reflinks, while the filesystem snapshot captures the ext4 metadata state without copying data blocks. This incremental approach minimizes I/O overhead and memory pressure during checkpoint operations.

Summary

• Zero-copy CoW via reflink technology allows CubeSandbox to create snapshots by writing only metadata, avoiding full disk copies.
• Rollback reattaches snapshot volumes and restarts VMs from saved memory pages, completing in ~90 ms without changing the sandbox ID.
• Clone operations create ephemeral snapshots to template multiple sandboxes, then clean up the temporary checkpoint automatically while supporting parallel creation.
• Incremental dirty-page tracking ensures only modified pages are written, enabling sub-second checkpoint granularity for real-time AI workloads.

Frequently Asked Questions

What is the actual latency for snapshot operations in CubeSandbox?

Single snapshot and rollback operations typically complete in approximately 90 milliseconds, while parallel rollbacks achieve roughly 65 milliseconds per operation when running 5 concurrent instances. These measurements are documented in the repository's performance benchmarks.

How does CubeSandbox handle memory state during snapshots?

The CubeCoW engine captures VM memory pages using copy-on-write semantics. Only pages modified since the last snapshot are written to disk, while unchanged pages remain shared through the CoW reflink mechanism, minimizing both storage overhead and capture time.

Can I rollback to a snapshot while preserving the sandbox ID?

Yes, rollback performs an in-place restore that maintains the same sandbox ID. The Python SDK's rollback() method restarts the VM from the snapshot state and resets internal HTTP connections via _reset_connections(), allowing seamless continuation of agent execution without creating a new sandbox instance.

What happens to the ephemeral snapshot after cloning?

The ephemeral snapshot created during clone() is automatically deleted after all child sandboxes have successfully spawned. This temporary checkpoint serves only as a template for the fan-out operation and does not persist as a user-accessible snapshot once the cloning process completes.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}