The migration agent was partway through rebuilding a search index when the laptop driving it went to sleep on Friday evening. By Monday the machine running the job had been torn down, and the agent started again from scratch with nothing it had built.
The code never failed; the machine simply forgot the work. An agent sandbox is an isolated machine, created by API for a task, where an AI agent runs the code it writes, and its lifecycle decides whether that work survives a pause, a crash or a weekend. Solari runs AI Sandboxes from the same account and API as its cloud browsers and desktops, with pause, snapshot, revert and fork built into every machine. This guide follows a sandbox from create to fork and shows what each stage keeps.
What Makes a Machine an Agent Sandbox
The definition starts with the older security meaning of the word. A sandbox separates a running program from the system around it and gives it a controlled set of resources. An agent sandbox turns that boundary into a machine an agent drives by API: it runs commands, executes code that keeps its state, works on files and hands back results.
On Solari the default dedicated tier is a microVM of its own, separated from the host by a hypervisor rather than a shared kernel. The hardened tier is the same machine with all outbound network blocked, for code nobody has reviewed. The shared tier is cheaper and starts faster, running each sandbox as a process tree inside a VM shared only with the organization's other shared sandboxes.
The boundary is part of the definition; the rest is what happens to the machine over time. The figure maps each stage of that life to what it keeps and the call behind it.
Creating a Sandbox: Size, Template and Idle Rules
Every lifecycle starts with a create call, and the choices made there stay with the machine. A single call to create a Solari sandbox sets the template, a CPU count from 1 to 8, the memory size and the idle rule:
The size sticks across snapshot, pause and resume, so a sandbox never comes back smaller than it left. A request above the limits is rejected rather than quietly reduced.
The idle rule is what would have saved the opener's weekend. With onTimeout: "pause", the default, a sandbox left idle past its timeout is paused with its state saved; with "kill" it is shut down. What that pause preserves is the next stage.
Paused, Parked and Waiting
Waiting is most of an agent's day, so the lifecycle has two ways to wait. A paused sandbox saves its memory and processes, and resume() brings it back exactly as it was. Pause also frees the machine's slot: a paused machine does not count against the plan's limit on running machines until it resumes.
Parking is the lighter option for short gaps, such as a slow model call. A parked machine has its CPUs frozen while its slot and connections stay held, so the next touch wakes it with nothing to restore. A parked machine still counts against the plan's limit, so parking suits frequent short waits and pausing suits long ones, and Solari desktops share the same lifecycle.
Pause keeps a machine's current state; a snapshot keeps a state the agent can come back to later.
Snapshots, Rewinds and Forks
Snapshots turn a single machine into a starting point for many. A snapshot is the state of a system at a point in time, and on Solari snapshot() saves the sandbox's disk and memory while it keeps running. revert() rewinds the same sandbox to that state under the same id, which suits resetting a test environment between runs.
The fromSnapshot option starts new machines from a snapshot, each fully independent. It works much like a fork of a process: slow setup happens once, and every copy opens already installed and configured.
Two rules for Solari snapshots catch people out. A paused machine must be resumed before it can be snapshotted or reverted, since the pause already holds its state. A snapshot is also tied to the template build it was taken on, and a restore onto a different build is refused at once; the fix is a fresh sandbox from the current template and a new snapshot.
Copies multiply quickly, which brings the lifecycle to its end and to its bill.
Tearing Down and Paying for Each Stage
The last stage has no way back. destroy() shuts a machine down for good and nothing on it can be recovered, so anything worth keeping goes into a snapshot first.
Cost follows the stages. Solari bills a sandbox for the CPU and memory it runs with, and its Professional plan runs a 4 vCPU, 16 GB sandbox at $0.221 per hour. Snapshot storage bills at $0.05 per GB-month after the first 10 GB across an organization. Every snapshot is self-contained, so deleting old ones is the quickest saving unless a machine started from one is still running or paused.
Choosing the Right Setup
An agent sandbox is a machine with a life, and the setup comes down to matching each stage to the job. Pick the isolation tier by how far the code is trusted, keep the default pause-on-idle rule for anything that might wait overnight, and park only for short gaps. Snapshot after slow setup so a lost run forks from a checkpoint instead of starting over, and delete snapshots once newer ones replace them.
Get Started With Solari
For the opener's index job, create a dedicated sandbox that pauses on idle and snapshot it once the dependencies are installed. Solari sandboxes are ready in 90 ms, and over a sandbox's full lifecycle Solari is about 1.3x faster than E2B and almost 3x cheaper per sandbox hour. Start free on Solari and the Free plan's monthly credits cover the first sandbox.
