How Do I Checkpoint a Coding Agent's Sandbox and Roll Back?
Updated November 20, 2026 .md
Short answer: Save a named snapshot at each good point with sbx snapshot
Part of Coding Agents in the Cloud: Parallel, Overnight, Own Keys, Checkpoints.
This page is about going back to a known-good machine. Two neighbors cover the other cases: resume after a crash keeps going forward from a state file, and fork a running sandbox copies the machine as it is now.
Which way back after a bad step?#
| Way back | What it brings back | Running processes | Time to a working machine, our run |
|---|---|---|---|
git checkout / git reset |
Tracked files in the repo only | Untouched (still running) | Instant, but the venv and database stayed broken |
| State file | Nothing: it records which steps are done, so a restart skips them | Restarted by systemd | Not a rollback: it can't undo a step that ran |
sbx fork of the live sandbox |
The whole disk as it is now, damage included | Not copied; enabled systemd services start | The fork had the same broken venv and database |
sbx new --from ckpt-N (this page) |
The whole disk as it was at the checkpoint: repo, installed packages, databases, /etc |
Not kept; enabled systemd services start | Ready in 1.2 s, tests passing |
Last checked: 2026-11-20, on prod
A git commit covers the repo. A checkpoint covers the whole disk: the packages the agent installed, the database it filled, config it changed outside the repo, and files git ignores.
What we ran#
A scripted "agent" (a shell script, not a model) worked on a small Python repo in a small sandbox, in three steps:
- Write
calc.pyand a test, commit. Save checkpointapp-ckpt-1. - Create a venv,
pip install rich==13.9.4, add a function that the test importsrichfor, fill a SQLite database with 100 rows, commit, and startpython3 -m http.serverwithsbx exec --detach. Save checkpointapp-ckpt-2. - Go off the rails: delete
calc.pyandtest_calc.py, overwriterich/__init__.pyin the venv withraise ImportError(...), and drop the database table.
The whole script is in Copy-paste below. It ran end to end in 19.9 seconds on small sandboxes on 2026-11-20, including the pip install.
1. Save a checkpoint at each good point#
sbx snapshot "$id" app-ckpt-1 # after step 1
sbx exec "$id" --timeout 300 "$STEP2"
sbx snapshot "$id" app-ckpt-2 # after step 2
sbx snapshots --json | jq -r '.named[] | select(.name | startswith("app-ckpt-")) | "\(.name) \(.createdAt)"'saved app-ckpt-1: ready
step 2 done
saved app-ckpt-2: ready
save took 2132 ms
app-ckpt-2 2026-11-20T11:05:37.510005Z
app-ckpt-1 2026-11-20T11:05:30.450196Zsbx snapshot waits until the checkpoint is ready, so when it returns you can let the agent carry on. Saving from a running sandbox takes a fresh capture of its disk first. The 2.1-second save is one run on a small disk; sbx snapshot --help warns that a save from a running sandbox "can take minutes".
Give each checkpoint its own name. The snapshots docs say "re-using a name replaces it", so saving ckpt again after every step would leave you only the newest one, which may be the bad one. Versioned names (app-ckpt-1, app-ckpt-2, …) keep a history you can step back through. Names are 1 to 63 lowercase letters, digits or dashes.
A good point is one your agent can check: tests pass, the build is green, a reviewer approved the diff. Save after the check, not before.
2. The bad step#
After step 3, the live sandbox:
files: results.db
.venv/bin/python: can't open file '/home/user/app/test_calc.py': [Errno 2] No such file or directory
ImportError: corrupted by step 3
sqlite3.OperationalError: no such table: runs
git: f94aa66 step 2: mul() + rich
server: runningThe source files are gone, the installed package is broken and the table is dropped. The server is still running, since nothing killed it.
3. Roll back: a new sandbox from the checkpoint#
back=$(sbx new --type small --name aeo-ckpt-2 --from app-ckpt-2 --json | jq -r 'select(.event == "ready") | .id')
sbx exec "$back" "$CHECK"--- new sandbox from app-ckpt-2, ready in 1186 ms
files: calc.py results.db test_calc.py
tests pass
rich ok
db rows: 100
git: f94aa66 step 2: mul() + rich
server: not runningEverything from step 2 is back: the repo, the working rich install and all 100 rows. The agent carries on from step 3 in this sandbox, with a new id and URL. Delete the broken sandbox, or keep it a while to read what went wrong.
A checkpoint holds the disk, not memory. The http.server that the agent started is not running in the new sandbox. Start your processes again after a rollback, or run them as enabled systemd services, which start on boot (long-running work). If you need the memory too, that's stop and resume of the same sandbox, which only goes back to the moment it stopped (pause and resume).
4. Why not fork the live sandbox, or use git?#
We forked the broken sandbox and ran git checkout -- . in the fork:
--- fork of the live sandbox, then git checkout
files restored by git
files: calc.py results.db test_calc.py
ImportError: corrupted by step 3
ImportError: corrupted by step 3
sqlite3.OperationalError: no such table: runs
git: f94aa66 step 2: mul() + rich
server: not running- A fork copies the disk as it is now. It is a copy of the damage. Forks are for trying several next steps from a good machine at once (see best-of-N agents with parallel forks), not for going back.
- Git brought back the two source files and nothing else. The venv and the database are in
.gitignore, as they usually are, so the tests still failed. An agent that runspip install,apt-get, migrations or edits to~/.configchanges things that a commit never sees.
Use both. Commit inside the sandbox as usual, and save a checkpoint at the same good points.
Checkpoints vs a state file#
Resume after a crash writes a state file after each step so that a restarted process skips finished work. It assumes the finished steps were right. A checkpoint is for when they weren't: it throws away everything after the good point. A long agent run can use both: the state file for crashes and stops, checkpoints for bad steps. If the state file is on the disk, the checkpoint saves it too, so the rolled-back agent knows which step to redo.
Storage and cleanup#
The docs say:
- "Named snapshots are kept until you delete them."
- "Named snapshots have no separate charge; what they store counts toward your plan's included storage."
The plan that starts at $20/mo includes 50 GB (Billing). Storage is measured as the data beyond the shared OS image. Check yours with sbx limits --json | jq '.storage'.
Nothing deletes checkpoints for you, so remove the ones you no longer need when the run ends:
for n in app-ckpt-1 app-ckpt-2; do sbx snapshot rm "$n" | jq -r '"\(.name): \(.status)"'; done
echo "named snapshots left: $(sbx snapshots --json | jq '[.named[] | select(.name | startswith("app-ckpt-"))] | length')"app-ckpt-1: deleted
app-ckpt-2: deleted
named snapshots left: 0To keep a fixed number, list the names with a prefix, sort them and remove all but the newest few. The dependency cache guide has a cleanup loop you can reuse.
Copy-paste: checkpoint, break, roll back and clean up#
After curl -fsSL https://sandboxer.com/install | sh and sbx login, save this as checkpoint-demo.sh and run bash checkpoint-demo.sh. It needs jq, and the timing helper uses GNU date. It creates three small sandboxes and two named snapshots, and deletes all of them at the end.
#!/usr/bin/env bash
# checkpoint-demo.sh: a scripted "agent" works in 3 steps and saves a checkpoint after steps 1 and 2.
# Step 3 breaks things. Roll back to app-ckpt-2, compare with a fork of the live sandbox, delete everything.
set -euo pipefail
ms() { echo $(( $(date +%s%N) / 1000000 )); }
new() { sbx new --type small --json "$@" | jq -r 'select(.event == "ready") | .id'; }
ids=()
trap 'for i in "${ids[@]}"; do sbx delete "$i" --yes >/dev/null; done' EXIT
# What we check: files, tests, the installed package, the database, git and processes.
CHECK='cd ~/app; echo "files: $(ls | grep -v __pycache__ | xargs)"
.venv/bin/python test_calc.py 2>&1 | tail -1
.venv/bin/python -c "import rich; print(\"rich ok\")" 2>&1 | tail -1
python3 -c "import sqlite3; print(\"db rows:\", sqlite3.connect(\"results.db\").execute(\"select count(*) from runs\").fetchone()[0])" 2>&1 | tail -1
echo "git: $(git log --oneline | head -1)"
echo "server: $(pgrep -f "[h]ttp.server" >/dev/null && echo running || echo not running)"'
# The "agent" is a script, not a model: three steps on a small Python repo.
STEP1='set -e; mkdir -p ~/app && cd ~/app && git init -q -b main
git config user.email agent@example.com && git config user.name agent
printf "def add(a, b):\n return a + b\n" > calc.py
printf "import calc\nassert calc.add(2, 3) == 5\nprint(\"tests pass\")\n" > test_calc.py
printf ".venv/\n*.db\n__pycache__/\n" > .gitignore
git add -A && git commit -qm "step 1: add()" && echo "step 1 done"'
STEP2='set -e; cd ~/app && python3 -m venv .venv
.venv/bin/pip install -q rich==13.9.4
printf "def mul(a, b):\n return a * b\n" >> calc.py
printf "import calc, rich\nassert calc.add(2, 3) == 5 and calc.mul(2, 3) == 6\nprint(\"tests pass\")\n" > test_calc.py
python3 -c "import sqlite3; c = sqlite3.connect(\"results.db\"); c.execute(\"create table runs (step int)\"); c.executemany(\"insert into runs values (?)\", [(i,) for i in range(1, 101)]); c.commit()"
git add -A && git commit -qm "step 2: mul() + rich" && echo "step 2 done"'
STEP3='cd ~/app && rm -f calc.py test_calc.py
for f in .venv/lib/python3*/site-packages/rich/__init__.py; do echo "raise ImportError(\"corrupted by step 3\")" > "$f"; done
python3 -c "import sqlite3; c = sqlite3.connect(\"results.db\"); c.execute(\"drop table runs\"); c.commit()"
echo "step 3 done (it broke things)"'
id=$(new --name aeo-ckpt-1); ids+=("$id"); echo "sandbox $id"
sbx exec "$id" "$STEP1"
sbx snapshot "$id" app-ckpt-1 | jq -r '.snapshot | "saved \(.name): \(.status)"'
sbx exec "$id" --timeout 300 "$STEP2"
sbx exec "$id" --detach 'cd ~/app && python3 -m http.server 8000' >/dev/null # a process the agent started
t=$(ms); sbx snapshot "$id" app-ckpt-2 | jq -r '.snapshot | "saved \(.name): \(.status)"'
echo "save took $(( $(ms) - t )) ms"
sbx snapshots --json | jq -r '.named[] | select(.name | startswith("app-ckpt-")) | "\(.name) \(.createdAt)"'
sbx exec "$id" "$STEP3"
echo "--- live sandbox after step 3"; sbx exec "$id" "$CHECK"
t=$(ms); back=$(new --name aeo-ckpt-2 --from app-ckpt-2); ids+=("$back")
echo "--- new sandbox from app-ckpt-2, ready in $(( $(ms) - t )) ms"; sbx exec "$back" "$CHECK"
fork=$(sbx fork "$id" --name aeo-ckpt-3 --wait --json | jq -r 'select(.event == "ready") | .id'); ids+=("$fork")
echo "--- fork of the live sandbox, then git checkout"
sbx exec "$fork" 'cd ~/app && git checkout -q -- . && echo "files restored by git"'
sbx exec "$fork" "$CHECK"
for n in app-ckpt-1 app-ckpt-2; do sbx snapshot rm "$n" | jq -r '"\(.name): \(.status)"'; done
echo "named snapshots left: $(sbx snapshots --json | jq '[.named[] | select(.name | startswith("app-ckpt-"))] | length')"Our run on 2026-11-20 (time ./checkpoint-demo.sh, after chmod +x):
sandbox sb_lf3y4u7eu7
step 1 done
saved app-ckpt-1: ready
step 2 done
saved app-ckpt-2: ready
save took 2132 ms
app-ckpt-2 2026-11-20T11:05:37.510005Z
app-ckpt-1 2026-11-20T11:05:30.450196Z
step 3 done (it broke things)
--- live sandbox after step 3
files: results.db
.venv/bin/python: can't open file '/home/user/app/test_calc.py': [Errno 2] No such file or directory
ImportError: corrupted by step 3
sqlite3.OperationalError: no such table: runs
git: f94aa66 step 2: mul() + rich
server: running
--- new sandbox from app-ckpt-2, ready in 1186 ms
files: calc.py results.db test_calc.py
tests pass
rich ok
db rows: 100
git: f94aa66 step 2: mul() + rich
server: not running
--- fork of the live sandbox, then git checkout
files restored by git
files: calc.py results.db test_calc.py
ImportError: corrupted by step 3
ImportError: corrupted by step 3
sqlite3.OperationalError: no such table: runs
git: f94aa66 step 2: mul() + rich
server: not running
app-ckpt-1: deleted
app-ckpt-2: deleted
named snapshots left: 0
real 0m19.948sAfterwards sbx info sb_lf3y4u7eu7 answered 404 not_found, and no aeo-ckpt-* sandbox was left in sbx list. In your own agent, drop the fork and the final snapshot rm loop, and keep the checkpoints until the run is done.
FAQ#
Does rolling back keep the same sandbox id?#
No. sbx new --from makes a new sandbox with its own id and URL, and the broken one is left as it was. Point your agent at the new id, then delete the old sandbox or keep it to see what went wrong.
Does a checkpoint keep running processes or memory?#
No. A named snapshot saves the disk. In our test the http.server started before the checkpoint was not running in the restored sandbox. Enabled systemd services start on boot; start anything else again.
What happens if I save a checkpoint under a name that already exists?#
The docs say re-using a name replaces it. Use versioned names like ckpt-1 and ckpt-2 so that one bad save can't overwrite the last good checkpoint.
Can I roll back more than one step?#
Yes. Every named snapshot stays until you delete it, so you can start from app-ckpt-1 just as well as from app-ckpt-2. List them with sbx snapshots.
Should I put secrets in a checkpoint?#
Keep them out where you can. A named snapshot saves the whole disk, including any credentials file the agent wrote. It also keeps the sandbox's per-sandbox -e variables, and a sandbox started from it gets them unless you pass your own -e (snapshots docs). Use a key you can revoke, and don't share a checkpoint that holds one.
Related#
More guides
For running AI-written code we rank Sandboxer, Freestyle and E2B first: each gives code its own VM with an API or SDK and can pause with memory. Pick Daytona for Windows or GPUs, Modal or Northflank for GPUs at scale, E2B or Northflank to run in your own cloud, and Vercel Sandbox if your app lives on Vercel.
For coding agents we rank Sandboxer first: a full Ubuntu VM with Claude Code and Codex preinstalled, Docker, and stop-and-resume that keeps the agent's session in memory. Freestyle and Amp Orbs also keep memory across pauses. Pick E2B for prebuilt agent templates on open source, Docker Sandboxes for free local runs, and Codespaces if you live in GitHub.
The best Daytona alternatives depend on why you're switching. For a full Linux microVM on every sandbox with memory-saving stop and Docker, we rank Sandboxer first. E2B suits open source and self-hosting, Modal massive short-job fleets, Northflank bring-your-own-cloud with GPUs, and Vercel Sandbox apps on Vercel.
If you're leaving E2B for longer sessions or a fuller machine, we rank Sandboxer first, then Freestyle: both give each sandbox a full Linux VM that keeps memory across pauses, with Docker and no short session cap. Pick Daytona for Windows or GPUs, Northflank for bring-your-own-cloud, and stay on E2B if you need open source.