# How Do I Checkpoint a Coding Agent's Sandbox and Roll Back?

> Save a named snapshot at each good point with sbx snapshot <id> ckpt-N. When the agent breaks things, start a new sandbox from the last good one with sbx new --from ckpt-N. On a small sandbox on 2026-11-20, the save took 2.1 seconds and the rollback was ready in 1.2 seconds, with files, packages and database intact. Processes restart.

Source: https://sandboxer.com/guides/checkpoint-and-roll-back-a-coding-agents-sandbox. Updated 2026-11-20.

**Short answer:** Save a named snapshot at each good point with sbx snapshot <id> ckpt-N. When the agent breaks things, start a new sandbox from the last good one with sbx new --from ckpt-N. On a small sandbox on 2026-11-20, the save took 2.1 seconds and the rollback was ready in 1.2 seconds, with files, packages and database intact. Processes restart.

Part of [Coding Agents in the Cloud: Parallel, Overnight, Own Keys, Checkpoints](/guides/coding-agents-in-the-cloud).

This page is about going *back* to a known-good machine. Two neighbors cover the other cases: [resume after a crash](/guides/resume-a-long-running-agent-after-a-crash) keeps going *forward* from a state file, and [fork a running sandbox](/guides/fork-a-running-sandbox-with-memory) 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](/guides/resume-a-long-running-agent-after-a-crash) | 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:

1. Write `calc.py` and a test, commit. Save checkpoint `app-ckpt-1`.
2. Create a venv, `pip install rich==13.9.4`, add a function that the test imports `rich` for, fill a SQLite database with 100 rows, commit, and start `python3 -m http.server` with `sbx exec --detach`. Save checkpoint `app-ckpt-2`.
3. Go off the rails: delete `calc.py` and `test_calc.py`, overwrite `rich/__init__.py` in the venv with `raise ImportError(...)`, and drop the database table.

The whole script is in [Copy-paste](#copy-paste-checkpoint-break-roll-back-and-clean-up) 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

```bash
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)"'
```

```text
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
```

`sbx 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](/docs/snapshots#named-snapshots-templates) 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:

```text
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
```

The 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

```bash
back=$(sbx new --type small --name aeo-ckpt-2 --from app-ckpt-2 --json | jq -r 'select(.event == "ready") | .id')
sbx exec "$back" "$CHECK"
```

```text
--- 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
```

Everything 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](/docs/long-running)). 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](/guides/pause-and-resume-a-sandbox-with-memory)).

## 4. Why not fork the live sandbox, or use git?

We forked the broken sandbox and ran `git checkout -- .` in the fork:

```text
--- 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](/guides/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 runs `pip install`, `apt-get`, migrations or edits to `~/.config` changes 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](/guides/resume-a-long-running-agent-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](/docs/billing#storage)). 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:

```bash
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')"
```

```text
app-ckpt-1: deleted
app-ckpt-2: deleted
named snapshots left: 0
```

To keep a fixed number, list the names with a prefix, sort them and remove all but the newest few. The [dependency cache guide](/guides/cache-dependencies-in-a-named-snapshot) 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.

```bash
#!/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`):

```text
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.948s
```

Afterwards `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](/docs/snapshots)). Use a key you can revoke, and don't share a checkpoint that holds one.

## Related

- [Coding Agents in the Cloud: Parallel, Overnight, Own Keys, Checkpoints](/guides/coding-agents-in-the-cloud)
- [Resume a long-running agent after a crash](/guides/resume-a-long-running-agent-after-a-crash)
- [Can you fork a running cloud sandbox?](/guides/fork-a-running-sandbox-with-memory)
- [Cache dependencies in a named snapshot](/guides/cache-dependencies-in-a-named-snapshot)
- [Snapshots: stop, resume, fork and templates](/docs/snapshots)
