# How to Create, Rollback, and Clone Snapshots in CubeSandbox

> Learn to create, rollback, and clone snapshots in CubeSandbox using its Go SDK or REST endpoints. Master sub-second checkpointing and in-place restoration.

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

---

**CubeSandbox provides three first-class snapshot APIs—`CreateSnapshot`, `Rollback`, and `Clone`—that enable sub-second checkpointing, in-place restoration, and parallel sandbox instantiation through the Go SDK (which powers the Python SDK) and REST endpoints.**

CubeSandbox offers immutable snapshots that capture both memory and filesystem state of running sandboxes. These capabilities, implemented in the official Go SDK at [`sdk/go/snapshot.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/sdk/go/snapshot.go), allow developers to checkpoint workloads, recover from failures instantly, and scale horizontally by cloning sandbox states.

## Creating Snapshots with CreateSnapshot

The `Sandbox.CreateSnapshot` method captures the current memory and filesystem of a running sandbox and returns a `SnapshotInfo` struct. This snapshot ID also serves as a template ID for future cloning operations.

```go
snap, err := sb.CreateSnapshot(ctx, "my-checkpoint")

```

According to the CubeSandbox source code, the underlying implementation resides in the POST handler within [[`sdk/go/snapshot.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/sdk/go/snapshot.go) (lines 38-55)](https://github.com/TencentCloud/CubeSandbox/blob/master/sdk/go/snapshot.go#L38-L55). The method persists the complete runtime state, making it suitable for creating recovery points before risky operations or for creating golden images that can be instantiated multiple times.

## Rolling Back to Previous States

`Sandbox.Rollback` restores a sandbox **in-place** to a previously created snapshot without changing the sandbox ID. This allows clients to continue issuing commands to the same sandbox instance after restoration.

```go
_, err := sb.Rollback(ctx, snap.SnapshotID)

```

The implementation handles the POST `/sandboxes/:id/rollback` endpoint in [[`sdk/go/snapshot.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/sdk/go/snapshot.go) (lines 105-119)](https://github.com/TencentCloud/CubeSandbox/blob/master/sdk/go/snapshot.go#L105-L119). After the server restarts the sandbox process, the SDK automatically calls `resetConnections` ([[`sdk/go/sandbox.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/sdk/go/sandbox.go) lines 87-93](https://github.com/TencentCloud/CubeSandbox/blob/master/sdk/go/sandbox.go#L87-L93)) to drop pooled data-plane connections, ensuring the client receives fresh connections to the restored state.

## Cloning Sandboxes from Snapshots

`Sandbox.Clone` enables horizontal scaling by creating **N** independent sandboxes from a single source. The method first creates an ephemeral snapshot via `CreateSnapshot`, then spawns new sandboxes using that snapshot as a template.

```go
clones, err := sb.Clone(ctx, cubesandbox.CloneOptions{
    N:           10,
    Concurrency: 4,
})

```

The implementation in [[`sdk/go/snapshot.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/sdk/go/snapshot.go) (lines 21-87)](https://github.com/TencentCloud/CubeSandbox/blob/master/sdk/go/snapshot.go#L21-L87) handles the orchestration through an inner `createOne` closure that calls `Client.Create` with `TemplateID: snapshot.SnapshotID`. The operation supports concurrency control via the `Concurrency` parameter, limiting the number of parallel instantiation requests.

### Atomic Failure Handling

Clone operations are atomic: if any individual clone fails, the system automatically kills all successfully created clones and returns the first error. This guarantees no orphaned resources remain when scaling operations encounter partial failures.

## Complete Workflow Example

Combine all three APIs to implement resilient, scalable workloads:

```go
ctx := context.Background()
client := cubesandbox.NewClient(cfg)

// Create initial sandbox
sb, _ := client.Create(ctx, cubesandbox.CreateOptions{
    TemplateID: cfg.TemplateID,
})

// Checkpoint baseline state
snap, _ := sb.CreateSnapshot(ctx, "baseline")

// Clone 3 parallel workers
workers, _ := sb.Clone(ctx, cubesandbox.CloneOptions{
    N:           3,
    Concurrency: 3,
})

// Execute code with automatic rollback on failure
for _, w := range workers {
    if err := w.RunCode(ctx, "process-data()", cubesandbox.RunCodeOptions{}); err != nil {
        w.Rollback(ctx, snap.SnapshotID)
    }
}

```

## Python SDK Usage

The Python SDK mirrors the Go implementation, as it uses the Go SDK under the hood:

```python
from cubesandbox import Sandbox

# Create and checkpoint

sb = Sandbox.create(template="tpl-xxxx")
snap = sb.create_snapshot()

# Rollback in-place

sb.rollback(snap.snapshot_id)

# Clone to scale

clones = sb.clone(n=3)  # Returns 3 independent copies

```

## Summary

- **`CreateSnapshot`** captures memory and filesystem state in [[`sdk/go/snapshot.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/sdk/go/snapshot.go)](https://github.com/TencentCloud/CubeSandbox/blob/master/sdk/go/snapshot.go), returning a reusable template ID.
- **`Rollback`** performs in-place restoration via the `/sandboxes/:id/rollback` endpoint, automatically resetting connections through [`resetConnections`](https://github.com/TencentCloud/CubeSandbox/blob/master/sdk/go/sandbox.go#L87-L93).
- **`Clone`** creates ephemeral snapshots and spawns concurrent workers with atomic failure handling—if one clone fails, all are cleaned up.
- Both Go and Python SDKs expose identical functionality, with the Go implementation serving as the underlying engine for REST API calls.

## Frequently Asked Questions

### Does rolling back change the sandbox ID?

No. `Rollback` restores the sandbox **in-place**, meaning the sandbox ID remains unchanged. This design allows existing client connections to continue interacting with the same endpoint after restoration, though the SDK internally resets data-plane connections to ensure consistency.

### What happens if cloning fails partially?

CubeSandbox guarantees atomic cloning behavior. If any of the N clones fails during creation, the system immediately terminates all successfully created clones from that batch and returns the first encountered error. This prevents resource leaks and ensures you never have partial clusters running.

### Can snapshot IDs be used as template IDs?

Yes. The `SnapshotID` returned by `CreateSnapshot` doubles as a template identifier. When cloning or creating new sandboxes, pass this ID as the `TemplateID` parameter to instantiate fresh sandboxes from that checkpointed state.

### Is the Python SDK limited compared to the Go SDK?

No. The Python SDK provides full feature parity because it uses the Go SDK under the hood. All snapshot, rollback, and clone operations available in [`sdk/go/snapshot.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/sdk/go/snapshot.go) are exposed through the Python interface with identical semantics and performance characteristics.