# CubeCoW Snapshot Model Explained: How Flat Snapshots Work in CubeSandbox

> Explore the CubeCoW snapshot model. Discover how its flat snapshot design ensures safe deletion and O(1) clone creation in CubeSandbox, streamlining data management.

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

---

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

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

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

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

```go
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.