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