What Is an AI Agent Sandbox: Isolation, State and Setup

The pull request came from the coding agent just before lunch, and its test step wanted to install a package nobody on the team recognized. A reviewer left the obvious comment in the thread: where does that install actually run, and what else can it reach?

That comment is the case for an agent sandbox. An agent sandbox is an isolated machine, created by API, where an AI agent runs the code it writes without reaching anything outside its walls; when the job ends, the machine is paused, rewound or deleted. Solari runs agent sandboxes as microVMs with files, commands, snapshots and pause and resume, from the same account as its cloud browsers and desktops. This guide walks through what a sandbox isolates, how it keeps state, what it costs and how to start one.

What an Agent Sandbox Isolates

The word is older than agents, so the definition is the place to begin. A sandbox is a security mechanism for separating running programs, so that untrusted code gets a controlled set of resources and nothing else. For an agent, untrusted code means anything the model wrote or downloaded.

The risk is not only buggy code. A model that reads a web page can pick up instructions planted there, a pattern OWASP describes as prompt injection, and then run whatever it was told. The sandbox limits the damage: the command still runs, but on a machine that holds no production credentials and can be thrown away.

What separates a sandbox from a folder on a laptop is the boundary itself, and boundaries come in different strengths.

How Strong the Boundary Is

Sandboxes differ mainly in what sits between the agent's code and the host. A container shares the host's kernel and relies on Linux namespaces to limit what a process can see. A microVM gives each sandbox its own kernel behind a hypervisor, so code that escapes its processes still meets a virtual machine wall.

Solari offers three isolation tiers, picked with the isolation field at create time.

Dedicated is the default and runs as a microVM of its own. Hardened is the same machine with all outbound network blocked, which suits code nobody has reviewed. Shared is cheaper and starts faster, but it runs inside a VM shared with the organization's other shared sandboxes and refuses file operations and manual pause. No tier ever puts two organizations on the same VM.

Isolation decides what the agent can break; the next question is what it can keep.

How a Sandbox Keeps State Between Steps

Agents rarely finish in a single call, so a sandbox has to hold its work between steps. On Solari, runCode remembers Python variables and imports between calls, and named shells keep the working directory and exported variables from command to command.

Longer gaps are handled by pause and snapshots. Pausing saves the machine's state, and the next connect() picks up where it left off; an idle sandbox pauses by default rather than being killed. A snapshot is a named save point taken while the machine keeps running: revert() rewinds the sandbox to it, and fromSnapshot starts fresh copies, so an agent can install dependencies once and fork ready machines from there. The rule that trips people up, spelled out in the snapshots docs, is that a paused machine must be resumed before it can be snapshotted.

Keeping state has a cost, and so does the machine itself.

What an Agent Sandbox Costs

Solari bills sandboxes for the CPU and memory they run with. On the Professional plan the rate is $0.0245 per vCPU-hour and $0.0077 per GB-hour, and the Free plan costs $0 with $3 of monthly credits. At a zero balance new sandboxes stop launching instead of running up an overage.

Snapshots add storage at $0.05 per GB-month, with the first 10 GB free across an organization, so deleting the ones an agent no longer needs keeps that line small.

Size is also set per sandbox, which is where setup begins.

How to Start an Agent Sandbox on Solari

Starting a sandbox takes an API key, the @solarisdk/sandbox package and a create call. A dedicated sandbox runs with 1 to 8 CPUs and up to 16 GB of memory, chosen at create time and kept across pause and resume, so the sketch below sets both before it runs a setup command, saves a checkpoint and pauses. Every option it uses is described in the sandboxes docs.

import { SandboxClient } from "@solarisdk/sandbox"

const sandboxes = new SandboxClient({ apiKey: process.env.SOLARI_API_KEY! })
const sbx = await sandboxes.create({ template: "base", cpu: 4, memMb: 8192 })
await sbx.connect()

await sbx.commands.run("sh", { args: ["-c", "pip install requests"] })
const snapId = await sbx.snapshot("after-setup")
await sbx.pause()

import { SandboxClient } from "@solarisdk/sandbox"

const sandboxes = new SandboxClient({ apiKey: process.env.SOLARI_API_KEY! })
const sbx = await sandboxes.create({ template: "base", cpu: 4, memMb: 8192 })
await sbx.connect()

await sbx.commands.run("sh", { args: ["-c", "pip install requests"] })
const snapId = await sbx.snapshot("after-setup")
await sbx.pause()

import { SandboxClient } from "@solarisdk/sandbox"

const sandboxes = new SandboxClient({ apiKey: process.env.SOLARI_API_KEY! })
const sbx = await sandboxes.create({ template: "base", cpu: 4, memMb: 8192 })
await sbx.connect()

await sbx.commands.run("sh", { args: ["-c", "pip install requests"] })
const snapId = await sbx.snapshot("after-setup")
await sbx.pause()

Two habits matter once this runs. A sandbox id and its control URLs are credentials that let whoever holds them run commands as root, so keep them out of logs and tickets. And when the agent also needs a screen, a Solari desktop shares the same lifecycle with a graphical display.

With those pieces in place, the choice comes down to a few rules.

Choosing the Right Setup

An agent sandbox is the right home for any code a model wrote, and the boundary should match how far that code is trusted: dedicated for everyday work, hardened for code nobody has read, shared only for quick commands where cost matters most. Pause covers the gaps inside a job and snapshots cover setup that should not be repeated. Because the same account also runs cloud browsers, the Solari introduction is the place to see how a sandbox and a browser pair up for a single agent.

Get Started With Solari

The first step is to start a dedicated sandbox, run the agent's setup in it, and take a snapshot that later runs can fork from. 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. Create a free Solari account and the Free plan's credits cover the first sandbox.