How to Create, Rollback, and Clone Snapshots in CubeSandbox

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, 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.

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 (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.

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

The implementation handles the POST /sandboxes/:id/rollback endpoint in [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 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.

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

The implementation in [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:

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:

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/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.
• 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 are exposed through the Python interface with identical semantics and performance characteristics.

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