Sandbox

Snapshots

Capture a point-in-time VM snapshot of any Tenki Sandbox session, then restore it later as a new session.

A snapshot is a restorable VM capture of one session, including both disk and memory state. Restore a snapshot to spin up a new session in the exact state of the original.

When to use a snapshot

Use a snapshot when:

  • you want to preserve the exact state of one session
  • the saved state is user-specific or temporary
  • you want a fast restore point for debugging or save-points

Don't use a snapshot when:

  • you want a team-wide reusable environment
  • you want a declarative environment that can be rebuilt intentionally

For those cases, use a template.

CLI workflow

Create

tenki sandbox snapshot create --session <session-id> --name baseline

With expiration:

tenki sandbox snapshot create \
  --session <session-id> \
  --name before-upgrade \
  --expires-at 2026-03-20T12:00:00Z

List, inspect, delete

tenki sandbox snapshot list
tenki sandbox snapshot list --json
tenki sandbox snapshot get <snapshot-id>
tenki sandbox snapshot delete <snapshot-id>

Restore

tenki sandbox snapshot restore <snapshot-id> --name restored-copy

snapshot restore is a convenience wrapper over:

tenki sandbox create --snapshot <snapshot-id>

Go SDK

snapshot, err := client.CreateSnapshot(ctx, session.ID, "baseline", nil)
snapshot, err = client.CreateSnapshotAndWait(
  ctx,
  session.ID,
  "baseline",
  nil,
  tenkisandbox.DefaultSnapshotCreateTimeout,
)
snapshot, err = client.GetSnapshot(ctx, snapshot.ID)
snapshots, err := client.ListSnapshots(ctx)
snapshot, err = client.WaitSnapshotReady(ctx, snapshot.ID, 5*time.Minute)

restored, err := client.Create(
  ctx,
  tenkisandbox.WithSnapshot(snapshot.ID),
  tenkisandbox.WithName("restored-copy"),
)

snapshot, err = client.DeleteSnapshot(ctx, snapshot.ID)

TypeScript SDK

const snapshot = await sandbox.createSnapshotAndWait(session.id, {
  name: "after-setup",
});

// Restore as a new session
const restored = await sandbox.createAndWait({
  snapshotId: snapshot.id,
});

Snapshot metadata

A snapshot record exposes:

  • id, session_id, optional workspace_id, optional name
  • state
  • size_bytes, compressed_bytes, memory_bytes
  • base_image_id
  • created_at, optional expires_at

States: CREATING, READY, FAILED, DELETING, DELETED.

Volumes are not auto-restored

Restored sessions are standard sessions

Snapshots and templates don't automatically reattach the original session's volumes. If you need a volume after restore, pass --volume at creation time or attach it explicitly afterward.

tenki sandbox snapshot restore <snapshot-id> \
  --name restored-copy \
  # Re-attach with the underlying create call:
  # (use `tenki sandbox create --snapshot ... --volume ...` directly)

When you need volumes back, prefer the explicit form:

tenki sandbox create --snapshot <snapshot-id> --volume <volume-id>:/workspace/cache

Pattern: save-point checkpoint

tenki sandbox create --name debugbox
tenki sandbox exec --session <session-id> bash -lc 'apt-get update && apt-get install -y strace'
tenki sandbox snapshot create --session <session-id> --name with-strace --wait-timeout 10m
tenki sandbox terminate --session <session-id>

# Later, restore the prepared environment
tenki sandbox snapshot restore <snapshot-id> --name debugbox-restored

Errors

  • ErrSnapshotNotFound
  • ErrSnapshotFailed
if errors.Is(err, tenkisandbox.ErrSnapshotFailed) {
  // Inspect the snapshot record for the failure reason and recreate
}
LinkedInProduct Hunt