Skip to main content
Basic snapshot and rollback are implemented via runtools sandbox snapshot and runtools sandbox rollback. Named snapshots and branching (creating a new sandbox from a snapshot) are planned but not yet available. The SDK APIs shown below are aspirational.

​
Overview

Snapshots let you save named checkpoints of your sandbox’s entire state. You can then rollback or branch from any snapshot.
Snapshots are different from pause/resume. Pause saves temporary state; snapshots create permanent, named checkpoints you can return to anytime.

​
Creating Snapshots

// Create a named snapshot
await sandbox.snapshot({ name: 'before-refactor' });

// With description
await sandbox.snapshot({
  name: 'v1-working',
  description: 'Working version before major changes',
});

​
Listing Snapshots

const snapshots = await sandbox.snapshots.list();

for (const snap of snapshots) {
  console.log(snap.name, snap.createdAt);
}
// before-refactor    2025-01-21T10:00:00Z
// v1-working         2025-01-21T11:00:00Z

​
Rolling Back

Restore sandbox to a previous snapshot: 
// Rollback to snapshot
await sandbox.rollback({ snapshot: 'before-refactor' });

// The sandbox is now exactly as it was at that snapshot
Rollback discards all changes since the snapshot. Current state is lost.

​
Branching

Create a new sandbox from a snapshot: 
// Branch from snapshot
const branched = await sandbox.branch({
  snapshot: 'before-refactor',
  name: 'experiment-1',
});

// branched is a new sandbox with same state as the snapshot
console.log(branched.id); // sandbox-def456
This is useful for:
  • Trying different approaches
  • A/B testing changes
  • Creating isolated environments

​
CLI Usage

# Create snapshot
runtools sandbox snapshot sandbox-abc123 --name "before-refactor"

# List snapshots
runtools sandbox snapshots sandbox-abc123

# Rollback
runtools sandbox rollback sandbox-abc123 --to "before-refactor"

# Branch
runtools sandbox branch sandbox-abc123 \
  --from "before-refactor" \
  --name experiment-1

​
Use Cases

Safe Experimentation

Checkpoint before risky changes. Easy rollback if things go wrong.

A/B Testing

Branch to try different approaches. Compare results.

Environment Cloning

Create identical environments for different purposes.

Disaster Recovery

Always have a known-good state to return to.

​
Snapshot Storage

Snapshots are stored on our NFS infrastructure:
TierSnapshots/SandboxRetention
Free37 days
Pro1030 days
Team5090 days
EnterpriseUnlimitedUnlimited

​
Best Practices

Always create a snapshot before refactoring, upgrading, or risky operations.
Name snapshots clearly: “before-db-migration”, “v2-working”, etc.
Delete snapshots you no longer need to save storage.
Don’t modify production sandbox. Branch for experiments.