Forkable Agent Sandbox

also known as Branch-Context Exploration, Sandbox Checkpoint/Rollback, Copy-on-Write Agent Environment

Turn the agent's whole execution environment, including filesystem, memory and running processes, into a versioned object that can be snapshotted, forked into isolated branches, rolled back and selectively committed.

This pattern helps complete certain larger patterns —

used-byLanguage Agent Tree Search·— Lift the agent loop into a search tree with a learned value function and backtracking.
used-byAdaptive Branching Tree Search·— At each node of an inference-time search tree, use Thompson sampling to decide whether to deepen an existing answer or branch a fresh attempt, optionally choosing per-node which underlying LLM to invoke.

Context

An agent works inside a stateful environment: a container with a seeded database, a package tree that took minutes to install, a running development server, a logged-in browser or desktop session. Search strategies the agent depends on — tree search with backtracking, best-of-N sampling, reinforcement-learning rollouts, speculative execution of a risky command — all assume that a step can be tried and then unmade. Model outputs are trivial to discard because sampling is stateless, but the environment those outputs act on is not.

Problem

Real environments accumulate side effects that plain re-execution cannot undo. A migration has already altered the schema, a process has already written a lock file, a form has already been submitted in the browser session. Backtracking therefore means rebuilding the environment from scratch and replaying every earlier action, which is slow and not always faithful. Full-state duplication is the obvious alternative, but copying an entire sandbox costs hundreds of milliseconds to seconds per operation, which is far too slow to sit in the inner loop of a deep search or a large fan-out. So the agent either explores one path timidly or pays for a fresh environment per branch.

Forces

Search, best-of-N and rollout training all need cheap state restoration, while the environments worth searching in are exactly the ones that are expensive to rebuild.
Undo by re-execution is only faithful when every action is deterministic and reversible; a single external write, timestamp or random seed breaks the replay.
Full-state duplication is simple and correct but costs hundreds of milliseconds to seconds per checkpoint, which bottlenecks deep search and large-scale fan-outs; copy-on-write deltas cut that to milliseconds at the cost of a shared-page dependency between parent and branch.
Isolation and branching pull the same lever in opposite directions: containment keeps a bad path from damaging user state, while forking multiplies the number of live copies of that state that must be tracked, resource-limited and eventually reclaimed.
Anything a branch does outside the snapshot boundary — a payment, an email, an external API write — cannot be rolled back, so the versioning abstraction is exact inside the box and a lie outside it.

When to use

The environment is expensive to rebuild — seeded databases, long installs, long-running processes, an authenticated browser or desktop session — and cannot be re-derived from a prompt.
The agent runs a search, a best-of-N sampling loop or a reinforcement-learning rollout that needs frequent state restoration.
Actions under consideration are destructive or hard to reverse, and trying one should not commit the whole run to it.
Several candidate paths address the same subproblem and only one of them needs to survive.

When not to use

The environment is stateless or trivially re-provisioned, in which case a fresh sandbox per branch is simpler than a fork tree.
The main effects of the work leave the sandbox — payments, emails, third-party writes — so abort cannot restore the world and the abstraction misleads.
Only one path is ever pursued and a linear checkpoint for crash recovery is all that is needed.
The runtime cannot capture process or memory state and the agent's work genuinely depends on it, since a filesystem-only snapshot restores an incomplete environment.

Example

An agent is fixing a failing test inside a container where a database has been seeded and a development server is already running. It wants to try three different repairs, but the first one runs a schema migration that the second one would need undone. Rather than rebuild the container three times, it snapshots the running sandbox, forks three branches from that snapshot, and keeps only the branch whose test suite goes green. The other two are discarded, and the migration they ran disappears with them.

Diagram

flowchart TD A["Live environment: fs + memory + processes + session"] --> B["Snapshot (copy-on-write delta)"] B --> C1["Branch 1: own fs view, own process group"] B --> C2["Branch 2"] B --> C3["Branch 3"] C1 --> D1{"Verdict"} C2 --> D2{"Verdict"} C3 --> D3{"Verdict"} D1 -- "commit (first wins)" --> E["Selective promote into parent"] D2 -- "invalidated by sibling commit" --> F["Abort: discard branch state"] D3 -- "failed" --> F E --> G["New parent state"] C1 -. "external write escapes the boundary" .-> H["Effect gate: not rollback-able"]

Solution

Therefore:

Give the sandbox a lifecycle rather than only a lifetime. A snapshot captures the complete machine state — filesystem, memory pages, process groups, and where it applies the GUI or browser session — as a restorable object. Forking that snapshot creates N branch contexts, each with an independent view of the filesystem and its own process group, sharing unmodified pages copy-on-write so a fork costs a delta rather than a full copy; measured implementations land in the low tens of milliseconds for a checkpoint and single-digit milliseconds for a rollback, which is what makes branching affordable inside a search loop. Each branch runs to a verdict: it commits, promoting its changes back into the parent, or it aborts and its state is discarded whole. When several siblings are exploring the same subproblem, the first successful commit wins and the runtime invalidates the rest, so no merge conflict has to be resolved by the model. Commit can be selective, promoting a chosen subset of changes rather than the whole branch, and contexts nest so a branch can itself fork for a sub-decision. Actions with effects outside the snapshot boundary are routed through a separate gate, because no rollback can retract them.

What it gives you

Backtracking costs a rollback instead of an environment rebuild plus an action replay, so an agent explores substantially more nodes under a fixed time budget.
Speculative and destructive actions become testable: a branch can run the migration, the destructive refactor or the uncertain command and be discarded if the result is bad.
Parallel exploration works in environments that cannot be re-derived from a prompt, because every branch starts from the identical live state rather than from a re-provisioned approximation.
First-commit-wins with sibling invalidation removes the merge problem from the agent's reasoning; the runtime resolves it structurally.

What it costs you

The abstraction is exact only inside the snapshot boundary; a branch that sent an email, charged a card or wrote to an external store has produced an effect that abort cannot retract.
Copy-on-write branches share pages with the parent, so a long-lived fork tree holds storage and memory proportional to the divergence, and abandoned branches leak resources unless reclamation is enforced.
Memory snapshots restore process state that assumed the world had not moved on: expired tokens, closed sockets, stale file handles and clock jumps surface as confusing failures after a restore.
Snapshot and restore are engine-specific and tie the agent to a particular runtime, which makes the exploration strategy hard to move between sandbox providers.
Forked GUI or browser sessions can reuse the same authenticated identity, so siblings acting in parallel may contend for a single remote session the snapshot never owned.

What this pattern forbids. Exploration may only happen inside a forked branch; a branch cannot write to the parent environment before it commits, at most one sibling commit is accepted and the rest must be aborted rather than merged, and actions whose effects escape the snapshot boundary must not be issued speculatively from inside a branch.

The smaller patterns that complete this one —

usesSandbox Isolation★★— Run agent-emitted code or actions in a contained environment with restricted filesystem, network, and process privileges.

And the patterns that stand alongside it, or against it —

alternative-toDurable Workflow Snapshot★— Capture workflow execution state as a snapshot in a pluggable storage provider so a paused run can resume across deployments, process restarts, and host crashes.
alternative-toReplay / Time-Travel★★— Re-run a past agent trace from any step with modified inputs/prompts/tools to debug or branch.
complementsShadow Workspace★— Mirror the workspace into an isolated, version-controlled shadow where the agent makes and reverts edits, surfacing diffs for review and promoting only accepted changes to the real tree.
complementsSpeculative Agentic Actions·— Predict the tool calls the agent is most likely to issue next and execute them preemptively on the current turn, then keep the results that the confirmed trajectory needs and discard the rest.
complementsClone Fan-Out Research·— Spawn 100 or more identical, full-capability agent instances in parallel — each a complete general agent rather than a role-specialised worker — and aggregate their independent outputs into a single answer.
complementsSubagent Isolation★— Run subagents in isolated workspaces so their writes do not collide and parallelism is safe.
complementsCompensating Action★★— Pair every irreversible-looking agent action with a compensating action that can undo or counteract it.
complementsAgent Resumption★★— Persist agent execution state so a long-running run survives restarts, deploys, or user disconnects.