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

> Discover how CubeSandbox achieves sub-second snapshot clone and rollback operations using a copy-on-write engine for lightning-fast VM state management.

- Repository: [Tencent Cloud/CubeSandbox](https://github.com/TencentCloud/CubeSandbox)
- Tags: internals
- Published: 2026-07-09

---

**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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/Cubelet/storage/cubecow_volume_manager.go)—resolves the device path and resizes the snapshot if necessary:

```go
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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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:

```python
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:

```python
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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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.