CubeCoW Snapshot Model Explained: How Flat Snapshots Work in CubeSandbox

CubeCoW uses a flat snapshot model where every snapshot is stored as an independent file alongside the original volume, making deletion operations safe and clone creation O(1) in both time and space.

The CubeCoW storage engine inside TencentCloud's CubeSandbox project abandons traditional hierarchical delta chains in favor of a flat, independent-file architecture. This design choice fundamentally changes how snapshots are created, deleted, and recovered compared to copy-on-write systems that maintain parent-child relationships on disk.

How the Flat Snapshot Model Works

In cubecow/README.md, the CubeCoW engine is documented as implementing a flat snapshot model where snapshots exist as siblings rather than a dependency chain. Each snapshot is a complete, standalone file that lives in the same directory as the original volume.

Snapshot Independence and File Structure

When you create a snapshot, CubeCoW generates a new independent file using FICLONE (or equivalent copy-on-write mechanisms at the filesystem level). The engine records the origin_volume—the ultimate ancestor volume—in memory only. This means:

• No parent-child links exist on the filesystem
• Snapshots do not reference each other on disk
• The "lineage" is purely an in-memory index maintained by the engine

According to the architecture overview in docs/architecture/overview.md, this design ensures that deleting one snapshot never touches another.

Deletion Safety and Crash Recovery

Because snapshots are plain files, removing a snapshot performs a simple unlink operation. This guarantees that deleting a snapshot cannot corrupt or affect any other snapshot in the system.

For crash recovery, the engine rebuilds its in-memory index by scanning the volume directory after a restart. Since there are no delta chains to reconcile or parent references to validate, recovery involves simple file system enumeration.

Working with CubeCoW Snapshots in Go

The CubeSandbox Go SDK provides direct access to the CubeCoW snapshot operations through sdk/go/snapshot.go. Below are practical examples for managing snapshots programmatically.

Creating a Snapshot

Pass an empty string to let the server generate a unique snapshot ID:

sandbox, _ := client.GetSandbox(ctx, "sandbox-id")
snap, err := sandbox.CreateSnapshot(ctx, "")
if err != nil {
    // handle error
}
fmt.Printf("Created snapshot %s\n", snap.SnapshotID)

Listing Snapshots

Use ListSnapshotsOptions to filter results and handle pagination:

opts := cubesandbox.ListSnapshotsOptions{
    SandboxID: "sandbox-id",
    Limit:     50,
}
snaps, next, err := client.ListSnapshots(ctx, opts)
if err != nil {
    // handle error
}
for _, s := range snaps {
    fmt.Println("snapshot:", s.SnapshotID, "names:", s.Names)
}
if next != "" {
    fmt.Println("more results available via next token:", next)
}

Safe Deletion

Remove snapshots without risk to siblings:

err := client.DeleteSnapshot(ctx, snap.SnapshotID)
if err != nil {
    // handle error
}
fmt.Println("snapshot deleted")

Rolling Back to a Snapshot

Restore a sandbox to a specific snapshot state:

result, err := sandbox.Rollback(ctx, snap.SnapshotID)
if err != nil {
    // handle error
}
fmt.Printf("Rollback result: %+v\n", result)

All SDK functions ultimately forward requests to the CubeCoW engine, which handles the underlying flat file operations.

Key Benefits of the CubeCoW Snapshot Model

The flat snapshot model provides distinct advantages over traditional delta-chain approaches:

• Clone Efficiency: Creating a snapshot of a snapshot (cloning) triggers another FICLONE call, completing in O(1) time and space regardless of data size
• Deletion Safety: Removing a snapshot is a simple file deletion that cannot cascade to other snapshots
• Simplicity: No complex dependency chains to track or validate on disk
• Fast Recovery: Rebuild the snapshot index by scanning directory contents without reconciling delta chains

Summary

• CubeCoW implements a flat snapshot model where every snapshot is an independent file stored alongside the original volume
• No filesystem parent-child relationships exist; lineage is tracked only in memory via origin_volume references
• Deletion is always safe—removing one snapshot file never affects others
• Clone operations are O(1) using FICLONE regardless of snapshot depth
• Recovery is simple—the engine rebuilds its index by scanning the volume directory after restart

Frequently Asked Questions

What is the CubeCoW snapshot model?

CubeCoW uses a flat snapshot model where each snapshot exists as a complete, independent file on disk. Unlike hierarchical models that create delta chains or parent-child dependencies, CubeCoW stores snapshots as siblings. This means every snapshot file contains its own data references and can be deleted without impacting other snapshots.

How does CubeCoW handle snapshot deletion?

CubeCoW deletes snapshots using a standard unlink system call. Because snapshots are independent files with no on-disk references to each other, deleting one snapshot immediately removes its file without requiring reconciliation of delta chains or updates to child snapshots. This makes deletion operations atomic and safe.

What is the performance cost of creating a snapshot in CubeCoW?

Creating a snapshot in CubeCoW is an O(1) operation in both time and space. The engine uses FICLONE (filesystem-level copy-on-write) to create the new snapshot file, which completes almost instantly regardless of the volume size. This efficiency applies equally to creating snapshots from the original volume or from existing snapshots (cloning).

Where is the snapshot lineage stored in CubeCoW?

CubeCoW stores snapshot lineage—specifically the origin_volume reference—only in memory, not on the filesystem. While each snapshot knows its ultimate ancestor volume, this metadata exists in the engine's runtime index. The actual files on disk contain no parent references, which simplifies the on-disk format and enables the flat deletion model.

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