Skip to main content

Snapshot & Restore Workflow

Use snapshots to create checkpoints, try risky changes safely, and fork experiments without losing progress.

Prerequisites

  • Caged CLI installed
  • A running sandbox (caged up or caged run)

The Checkpoint Pattern

Create snapshots at known-good states before attempting risky operations:
# 1. Set up your sandbox
caged up --template node-20 --repo https://github.com/your-org/project

# 2. Let the agent install deps and get things working
caged exec cage-a1b2c3d4 "npm install && npm test"

# 3. Snapshot the known-good state
caged snapshot create cage-a1b2c3d4 --name "baseline-passing"

# 4. Let the agent attempt a risky refactor
caged exec cage-a1b2c3d4 "claude 'Refactor the auth module to use JWTs'"

# 5. Check if it worked
caged exec cage-a1b2c3d4 "npm test"

# If tests fail — restore and try a different approach:
caged snapshot restore snap-abc123

Branching Experiments

Fork a sandbox to try multiple approaches in parallel:
# Create base sandbox and get it to a good state
caged up --template node-20 --repo https://github.com/your-org/api
caged exec cage-base "npm install && npm test"
caged snapshot create cage-base --name "ready-to-experiment"

# Fork into three parallel experiments
caged up --from-snapshot snap-ready --name "experiment-a"
caged up --from-snapshot snap-ready --name "experiment-b"
caged up --from-snapshot snap-ready --name "experiment-c"

# Run different agent prompts in each
caged exec cage-exp-a "claude 'Refactor using the repository pattern'"
caged exec cage-exp-b "claude 'Refactor using the service layer pattern'"
caged exec cage-exp-c "claude 'Refactor using event sourcing'"

# Compare results
caged exec cage-exp-a "npm test && echo 'PASS'" 
caged exec cage-exp-b "npm test && echo 'PASS'"
caged exec cage-exp-c "npm test && echo 'PASS'"

# Keep the winner, destroy the rest
caged destroy cage-exp-b --force
caged destroy cage-exp-c --force

Iterative Agent Workflow

Use snapshots as save points in a multi-step agent workflow:
#!/bin/bash
# iterative-agent.sh — Step-by-step agent work with save points

SANDBOX="cage-a1b2c3d4"
STEPS=(
  "Install dependencies and verify the project builds"
  "Add TypeScript strict mode and fix all type errors"
  "Add unit tests for all exported functions"
  "Set up CI with GitHub Actions"
)

for i in "${!STEPS[@]}"; do
  step="${STEPS[$i]}"
  echo "=== Step $((i+1)): $step ==="

  # Snapshot before each step
  caged snapshot create "$SANDBOX" --name "before-step-$((i+1))"

  # Run agent
  caged exec "$SANDBOX" "claude '$step'"

  # Verify
  RESULT=$(caged exec "$SANDBOX" "npm test 2>&1; echo EXIT:\$?")

  if echo "$RESULT" | grep -q "EXIT:0"; then
    echo "✓ Step $((i+1)) passed"
  else
    echo "✗ Step $((i+1)) failed — restoring snapshot"
    SNAP_ID=$(caged snapshot list "$SANDBOX" --json | jq -r '.[-1].id')
    caged snapshot restore "$SNAP_ID"
    echo "Retrying with different prompt..."
    caged exec "$SANDBOX" "claude 'The previous attempt failed. Try a different approach: $step'"
  fi
done

echo "=== All steps complete ==="

Sharing State Across Team

Export a snapshot and share it:
# Developer A: save a well-configured sandbox
caged snapshot create cage-a1b2c3d4 --name "team-baseline-v2"

# Get the snapshot ID
caged snapshot list cage-a1b2c3d4
# snap-x1y2z3w4    team-baseline-v2    120 MB    just now

# Developer B: create a new sandbox from that snapshot
caged up --from-snapshot snap-x1y2z3w4

# Or download as an archive for offline use
caged snapshot download snap-x1y2z3w4 --output ./team-baseline-v2.tar.gz

Tips

Auto-snapshots on sleep: Caged automatically snapshots when a sandbox sleeps (idle timeout or caged sleep). You always have a restore point.
Name your snapshots clearly: Use descriptive names like "after-auth-refactor" or "pre-migration". You’ll thank yourself later.
Fork before risky operations: It’s cheaper to fork a snapshot than to redo 30 minutes of agent work. Fork liberally.
Snapshot storage is incremental: Only the delta from the previous state is stored, so frequent snapshots don’t cost much.