Snapshot & fork

Goal: Use snapshots to checkpoint a sandbox at a stable state, fork into N independent branches to run experiments in parallel, then restore from the checkpoint if any branch produces a bad outcome.

What you’ll use: Sandboxes, Snapshots

What you’ll build

A reusable fork-and-compare pattern:

sandbox (baseline built) → snapshot_A
      ├── restore → branch-1 (try approach X) → compare
      ├── restore → branch-2 (try approach Y) → compare
      └── restore → branch-3 (try approach Z) → compare
                                                     └── pick winner, destroy losers

The same pattern applies to: A/B testing AI agent strategies, running parallel database migrations, comparing LLM prompt variants, and safe-guarding long operations behind a checkpoint.

Prerequisites

• A MIOSA workspace API key (msk_live_*) - see API Keys
• Node 22+ or Python 3.11+

Step 1 - Install and configure

Step 2 - Build a baseline and checkpoint it

Run all the expensive setup work once - dependency installs, model downloads, dataset loading - then snapshot the sandbox so every branch starts from the same state without repeating the cost.

Step 3 - Fork into branches

Restore the snapshot once per branch. Each restore creates an independent sandbox with the same filesystem and process state as the checkpoint - no shared memory, no interference.

Step 4 - Run each branch and collect results

Execute the experiment on each branch independently and capture the outcome metric.

Step 5 - Pick the winner and clean up

Compare outcomes, keep the best branch, and destroy the rest. If every branch failed, restore from the checkpoint and try a different strategy.

Restore to a known-good state on failure

If production goes wrong during a risky operation, restore from a pre-operation snapshot:

Snapshot lifecycle

Snapshots persist until you explicitly delete them. They do not expire.

Fork a running sandbox

sandbox.fork() creates a copy-on-write clone of a running sandbox - no snapshot creation step, no polling. The original keeps running unchanged.

When to use fork vs snapshots.restore:

What you learned

• sbx.snapshots.create(comment) captures state without stopping the sandbox. The sandbox keeps running while the snapshot uploads.
• sbx.snapshots.restore(snap_id) creates an independent sandbox from the checkpoint. N restores = N independent sandboxes.
• sbx.fork() creates a live copy-on-write clone of a running sandbox instantly - no snapshot step needed.
• Parallel restores let you run experiments without the per-experiment setup cost.
• Snapshots are the rollback primitive: checkpoint before risk, restore on failure.

Next