How to Snapshot and Fork a Sandbox for Agents (2026 Guide)

The test agent spent most of the morning getting the legacy app to build: the right compiler, a pinned database, a config file nobody had documented. Then it had to try several candidate patches, and every attempt risked wrecking the environment it had just assembled. Rebuilding it from scratch before each try would eat the rest of the day.

That is the job snapshots and forks exist for. To snapshot and fork a sandbox, prepare the machine once, save its disk and memory with snapshot() while it keeps working, then start independent copies with fromSnapshot or rewind the original with revert(). Solari AI Sandboxes do all three from the same account and API as its cloud browsers and desktops, and this guide walks through each call and the rules that trip people up.

Why Agents Branch Their Work

The reason to bother comes before the calls. A snapshot is the state of a system at a point in time, and an agent often needs to return to one: before a destructive migration, before a risky patch, before an evaluation episode that has to begin exactly where the last one did.

Forking takes the idea further. Like a process fork, a forked sandbox is a new machine that starts from its parent's state and then goes its own way, so an agent can try several approaches in parallel and keep the one that works. The slow setup happens once, and every copy opens already installed and configured.

Both moves begin with a machine worth saving, which is where the setup starts.

How to Take a Snapshot of a Running Sandbox

The first step is a sandbox prepared the slow way, once. A Solari sandbox is an isolated Linux machine for agent code, a sandbox in the security sense, and the CPU and memory size chosen at create time sticks across snapshot, pause and resume. The setup below installs the dependencies and saves the result under a name:

const sbx = await sandboxes.create({ template: "base" })
await sbx.connect()
await sbx.commands.run("sh", { args: ["-c", "./install-deps.sh"] })
const snapId = await sbx.snapshot("after-setup")

const sbx = await sandboxes.create({ template: "base" })
await sbx.connect()
await sbx.commands.run("sh", { args: ["-c", "./install-deps.sh"] })
const snapId = await sbx.snapshot("after-setup")

const sbx = await sandboxes.create({ template: "base" })
await sbx.connect()
await sbx.commands.run("sh", { args: ["-c", "./install-deps.sh"] })
const snapId = await sbx.snapshot("after-setup")

The machine keeps running while the snapshot is taken, so an agent can checkpoint mid-task without stopping its work. The call returns a snapshot id, and that id is what every later step uses.

With the id in hand, the agent can start copies from it.

How to Fork Independent Copies of a Sandbox

Forking is a create call with a single extra field. Passing fromSnapshot to create starts a fresh machine from the saved state, and each copy is fully independent, so many can run at once from the prepared starting point described in Solari snapshots:

const workers = await Promise.all(
  patches.map(() =>
    sandboxes.create({ template: "base", fromSnapshot: snapId }),
  ),
)

const workers = await Promise.all(
  patches.map(() =>
    sandboxes.create({ template: "base", fromSnapshot: snapId }),
  ),
)

const workers = await Promise.all(
  patches.map(() =>
    sandboxes.create({ template: "base", fromSnapshot: snapId }),
  ),
)

Each worker is a full machine: it can be snapshotted again, reverted, paused and forked from its own snapshots, so lineages branch anywhere rather than only from the original. Copies inherit the snapshot's memory topology, so a source machine that ran with extra RAM needs the same memMb passed when forking.

Forks suit parallel attempts; the next call suits trying again on the same machine.

How to Rewind a Sandbox Between Runs

Reverting is the lighter option when the agent only needs its own machine back. revert(snapId) rewinds the sandbox to the snapshot and keeps the same id, so anything that points at the machine keeps working, which suits resetting a test environment between runs:

await sbx.revert(snapId)

await sbx.revert(snapId)

await sbx.revert(snapId)

Under the hood a revert boots a fresh VM from the snapshot and swaps it in, so open connections drop and re-establish; it can also target any snapshot the organization owns, and if it fails, the machine keeps running untouched.

That covers the three calls, and the rules around them are short.

Rules That Trip People Up

Most first attempts fail on one of two refusals, and the figure below sets the three calls beside pause, the state they are most often confused with.

The first rule is about pause. A snapshot or a revert needs a running machine, so on a paused sandbox both return 409 NotRunning; the pause already holds its state, and calling resume() first fixes it. Solari desktops share the same lifecycle, so the rule applies to VMs too.

The second rule is about builds. A memory snapshot is tied to the template build it was taken on (the root filesystem, kernel and hypervisor, known as its golden), so a restore onto a host running a different build is refused at once as SnapshotNotRestorable. Retrying will not help; the fix is a fresh sandbox from the current template and a new snapshot.

Rebuilt snapshots pile up, which brings the guide to cost.

What Snapshots Cost and How to Trim It

Storage is the only new line on the bill. Solari bills stored snapshots at $0.05 per GB-month, pro-rated daily from the organization's credit balance, with the first 10 GB across the organization free, as set out in Solari pricing.

Because every snapshot is self-contained, carrying its own disk and memory image rather than pointing at a parent, deleting superseded ones is the quickest saving, and only a running or paused machine started from it, or a template it backs, blocks a deletion. Even at a zero balance, restoring, forking and deleting keep working; only new snapshots wait for a top-up.

Choosing the Right Setup

The setup comes down to matching the call to the shape of the work. Snapshot once the slow setup is done, fork when the agent needs parallel attempts from the same state, and revert when a single machine needs a clean start between runs. Keep pause for long waits, resume before any snapshot, and rebuild from the template when a restore reports a golden mismatch.

Get Started With Solari

For the patch-testing job in the opener, build the environment once in a dedicated sandbox, snapshot it, and fork a worker for each candidate patch. Solari sandboxes are ready in 90 ms, and Solari is almost 3x cheaper than E2B per sandbox hour. Start free on Solari with the credits the Free plan includes and take the first snapshot today.