To create an AI agent sandbox you need five things wired together: an isolation boundary the model's code cannot cross, a disposable filesystem it can wreck, a network policy, hard timeouts, and a teardown path that runs even when your process doesn't. Then you expose that sandbox to the model as a single tool — usually called run_code or exec — that takes a command and returns stdout, stderr, and an exit code. This guide walks through all of it: the requirements checklist, three ways to build the box (a Docker container, a do-it-yourself Firecracker microVM, a managed platform), and the tool-calling loop that lets an LLM actually use it.
If you want the concept first, What Is an AI Agent Sandbox? covers the definition, and How AI Agent Sandboxes Work traces the request lifecycle in detail. This post is the hands-on version. I build PandaStack, a Firecracker sandbox platform, so the third option is mine — I'll mark where that bias shows, and the first two options are built with nothing of mine at all.
Step 1: write down what the sandbox must do
Skip this and you'll build a container that runs code, call it a sandbox, and discover the missing pieces in an incident review. An agent sandbox is a contract with six clauses. The model's code is untrusted by construction — nobody reviewed it before it ran, and a prompt-injected web page can steer it — so every clause is written assuming the code is trying to get out.
- Isolation boundary — what stands between the agent's code and your host, your secrets, and other tenants. This is the only clause that makes the sandbox safe; the rest make it usable. Process, container, gVisor-style user-space kernel, or a microVM with its own guest kernel, in roughly increasing order of strength.
- Filesystem — a writable root the agent can
pip installinto, write files to, and read back from, which is discarded with the sandbox. Copy-on-write clones of a template image keep this cheap. - Network policy — default-deny, an allowlist (package indexes, one API), or full egress. Unrestricted egress is how exfiltration and abuse happen; no egress means the agent can't install anything. Decide per workload, not per mood. Controlling Network Egress for Untrusted Code goes deep on the mechanics.
- Timeouts at three levels — per command (the infinite loop), per sandbox idle time (the agent that wandered off), and per task (the agent that loops forever calling tools). Plus CPU, memory, disk, and process-count caps so one fork bomb doesn't become everyone's problem.
- Teardown — an explicit kill on the happy path, a
finallyblock on the sad path, and a server-side reaper for the path where your orchestrator crashed. Leaked sandboxes are a bill and an attack surface at the same time. - Observability — every command the model ran, its exit code, how long it took, and which sandbox it ran in, tied back to the conversation. When an agent does something strange, this log is the only witness.
Step 2: pick how you'll build the box
There are three realistic routes. They differ mainly in the strength of the isolation boundary and in how much infrastructure you end up owning.
| Docker container | DIY Firecracker microVM | Managed platform | |
|---|---|---|---|
| Isolation boundary | Namespaces + cgroups on a shared host kernel | Own guest kernel behind KVM | Depends on the vendor — check whether it is a container, gVisor, or a microVM |
| Time to first sandbox | Minutes | Days for one VM; months for a fleet | Minutes |
| Create latency | Fast for small images | Seconds on a cold boot unless you build snapshot-restore | Vendor-dependent; verify against their docs |
| What you operate | Docker hosts, image hygiene, seccomp profiles | Kernel, rootfs images, tap networking, jailer, snapshot store, scheduler, guest agent | An API key and a bill |
| Good fit | Your own trusted code, local dev, low-risk internal tools | Sandboxing is your product and you want to own the boundary | The sandbox is a means to an end |
Option A: a locked-down Docker container
A container is the fastest thing to stand up, and with enough flags it is a respectable box for code you mostly trust. The trick is that almost none of the hardening is on by default — a stock docker run gives the process root inside the container, full egress, unlimited processes, and the default capability set.
# A hardened-ish container for one agent task. Every flag here is
# something the default `docker run` does NOT do for you.
docker run --rm \
--name agent-task-7f3a \
--network none \
--read-only \
--tmpfs /tmp:rw,size=256m \
--tmpfs /work:rw,size=1g \
--memory 1g --memory-swap 1g \
--cpus 1 \
--pids-limit 256 \
--cap-drop ALL \
--security-opt no-new-privileges \
--user 65534:65534 \
--stop-timeout 5 \
python:3.12-slim \
timeout 60 python3 -c 'print(sum(range(10**6)))'
# What you still share with the agent's code: the host kernel.
# Every syscall above lands on the same kernel your other tenants use.That covers the filesystem (read-only root, size-capped tmpfs scratch), network (--network none), resource caps, and a per-command timeout via timeout 60. What it cannot fix is the shared kernel. Every syscall the agent's code makes lands on the same Linux kernel as the host and every other container, so a kernel bug or a misconfigured mount is a path out. A container is a polite suggestion to the kernel, and the kernel has a long history of occasionally ignoring it. For model-written code from strangers, treat this as mitigation, not isolation.
You'll also notice everything else is on you: a reaper for containers whose parent died, an allowlisting proxy if you want any egress at all, and logging of what ran. That's fine for a weekend project. It's a platform team for a product.
Option B: a DIY Firecracker microVM
Firecracker is the VMM behind AWS Lambda: a small KVM-based monitor that boots a Linux guest with its own kernel, a few virtio devices, and very little else. Each sandbox gets a private kernel behind hardware virtualization, which is the strong boundary the container lacked. The minimal config file looks like this:
{
"boot-source": {
"kernel_image_path": "/srv/fc/vmlinux-5.10",
"boot_args": "console=ttyS0 reboot=k panic=1 pci=off"
},
"drives": [
{
"drive_id": "rootfs",
"path_on_host": "/srv/fc/sbx-7f3a/rootfs.ext4",
"is_root_device": true,
"is_read_only": false
}
],
"machine-config": {
"vcpu_count": 2,
"mem_size_mib": 1024
},
"network-interfaces": [
{
"iface_id": "eth0",
"host_dev_name": "tap-sbx7f3a",
"guest_mac": "06:00:AC:10:00:02"
}
]
}Launch it with firecracker --api-sock /tmp/fc.sock --config-file vm.json (check the flag spelling against your Firecracker version) and a guest boots. The field names are the real API resources — boot-source, drives, machine-config, network-interfaces — and the same shapes can be PUT over the API socket one at a time instead; Firecracker config file vs REST API: two ways to boot a microVM compares the two models.
Now the honest part: that JSON is a small fraction of an agent sandbox. Before it is useful you need an uncompressed guest kernel and an ext4 rootfs with your tools installed, a tap device in its own network namespace with NAT and egress rules, a copy-on-write clone of the rootfs per sandbox so you aren't copying gigabytes per create, the jailer so the VMM runs chrooted and unprivileged, and a guest agent (vsock or SSH) so you can actually run a command and read stdout. Cold boots take seconds, so production setups snapshot a booted VM and restore it per create. Then you need a scheduler once there is more than one host. Build vs Buy: Rolling Your Own Firecracker Sandbox tallies the whole list; it is a real engineering project measured in quarters, not afternoons.
Option C: a managed platform (PandaStack's Python SDK)
A managed platform does Option B for you and hands back an API. This is where my bias lives, so here are the facts rather than adjectives. Every PandaStack sandbox is its own Firecracker microVM with its own guest kernel, its own network namespace and TAP device, and a copy-on-write rootfs. There is no warm pool of idle VMs: each create restores a baked template snapshot, at 179 ms p50 (about 203 ms p99) end to end. The very first spawn of a new template cold-boots in about 3 s and bakes the snapshot that later creates restore.
Mapped back to the checklist: the boundary is the microVM; the filesystem is a CoW clone of the template that dies with the VM; per-command timeouts are exec(..., timeout_seconds=60); ttl_seconds on create is an idle timeout (activity resets it, so it is a backstop, not a wall clock); kill() is teardown; and the server reaps idle sandboxes even if your process never comes back. One gap to say plainly: the Python SDK does not expose a per-sandbox egress allowlist, so if your workload needs default-deny networking with a curated list, verify what the platform supports for your account or enforce it in your own proxy. Other managed sandboxes exist with different isolation models and feature sets — Best AI Agent Sandboxes in 2026 compares them, and you should verify any vendor's claims against their docs.
Step 3: wire the sandbox up as a tool the model calls
An LLM can't run code; it can only ask you to. Tool calling is the protocol for that ask: you describe a tool with a name, a description, and a JSON Schema for its inputs; the model replies with a structured call; your code executes it and sends the result back. If tool calling itself is new, What is tool calling for AI agents? explains the message flow. Here is the whole loop with the Anthropic SDK and a PandaStack sandbox — swap in any provider, the shape is identical.
import json
import anthropic
from pandastack import Sandbox, SandboxTimeout
# 1. The tool the model sees. Keep the schema boring and the description honest.
RUN_CODE_TOOL = {
"name": "run_code",
"description": (
"Run a shell command in an isolated Linux sandbox (Ubuntu, Python 3, "
"pip available). Files persist between calls in this conversation. "
"Returns stdout, stderr and exit_code. Commands time out after 60s."
),
"input_schema": {
"type": "object",
"properties": {
"command": {"type": "string", "description": "Shell command to run"},
},
"required": ["command"],
},
}
MAX_OUT = 8_000 # chars; a 40 MB log does not belong in the context window
def run_code(sbx: Sandbox, command: str) -> str:
try:
r = sbx.exec(command, timeout_seconds=60)
except SandboxTimeout:
return json.dumps({"error": "timed out after 60s", "exit_code": 124})
return json.dumps({
"stdout": r.stdout[-MAX_OUT:],
"stderr": r.stderr[-MAX_OUT:],
"exit_code": r.exit_code,
})
# 2. One sandbox per conversation; ttl_seconds is an IDLE timeout backstop.
sbx = Sandbox.create(template="code-interpreter", ttl_seconds=600,
metadata={"conversation": "conv-42"})
client = anthropic.Anthropic()
messages = [{"role": "user", "content": "How many primes are below 1,000,000?"}]
try:
for _ in range(10): # step budget: agents loop, budgets end loops
resp = client.messages.create(
model="claude-sonnet-5-5", max_tokens=2048,
tools=[RUN_CODE_TOOL], messages=messages,
)
messages.append({"role": "assistant", "content": resp.content})
if resp.stop_reason != "tool_use":
break
results = []
for block in resp.content:
if block.type == "tool_use" and block.name == "run_code":
print(f"[{sbx.id}] $ {block.input['command']}") # audit trail
results.append({
"type": "tool_result",
"tool_use_id": block.id,
"content": run_code(sbx, block.input["command"]),
})
messages.append({"role": "user", "content": results})
finally:
sbx.kill() # teardown is not optional, and not a TTL's jobA few design choices in there are load-bearing, and they map straight back to the checklist:
- One tool, one string in. A single
run_codetool taking a shell command is easier for models to use well than ten narrow tools, and you can still addread_file/write_filelater viasbx.filesystemif you want structured file access. - Errors are results, not exceptions. A timeout or a non-zero exit goes back to the model as data so it can fix its own mistake — a traceback in the tool result is the most useful thing a coding model can read.
- Output is truncated. Tool results land in the context window; an unbounded
catof a log will blow your token budget and bury the actual error. Keep the tail, where the error usually is. - Three timeouts, all present.
timeout_seconds=60per command,ttl_seconds=600idle backstop, andrange(10)as the step budget for the whole task. - Teardown in
finally. The sandbox dies whether the loop finished, raised, or hit its step limit. The TTL is for when the process itself dies. - Every command is logged with the sandbox id. Ship that line to your real log pipeline in production, with the conversation id from
metadata.
For framework-specific versions of this same tool — LangChain, LangGraph, CrewAI, and others — see How to give a LangChain agent a code execution tool and its siblings. The sandbox side doesn't change; only the decorator does.
One sandbox per task, or per conversation?
The example keeps one sandbox for the whole conversation so installed packages and written files survive between tool calls, which is what coding and data-analysis agents want. For independent one-shot executions — grading a submission, running a single snippet from an untrusted user — create a fresh sandbox per call and kill it immediately; when a create costs a couple hundred milliseconds that is cheap enough to be the default. For long sessions that go quiet, hibernate() and wake() park the sandbox instead of keeping it running. Stateful vs Ephemeral AI Agent Sandboxes covers the trade-off.
Where agent sandboxes are used
The same box with the same tool shows up in very different products. What changes is the template, the network policy, and how long the sandbox lives.
- Coding agents — clone a repo, install dependencies, run the tests, edit, repeat. Needs a persistent sandbox per session, package-index egress, and often a preview URL for a dev server (
sbx.preview_url(3000)). See How to Build a Sandboxed AI Coding Agent (2026). - Data analysis — the code-interpreter pattern: upload a CSV, let the model write pandas, read back the chart PNG through the filesystem API. Often runs fine with no egress at all.
- Browser agents — a headless browser driven by the model, which means it is loading arbitrary web pages and is the most exposed to prompt injection. Isolation matters more here, not less. See Run AI Browser Agents in Isolated MicroVMs.
- Eval harnesses — run thousands of agent trajectories in parallel, each in a clean, identical environment so results are comparable and one run can't poison the next. Fast create and fork from a prepared snapshot matter. See Running AI Agent Eval Harnesses in Isolated microVMs.
- CI and PR automation — an agent that fixes a failing build or reviews a pull request runs the project's own scripts, which are untrusted code too, especially from forks.
The short version
- Pick the boundary to match the threat: containers for your own code, microVMs for code a model wrote for a stranger.
- Give the agent a disposable, copy-on-write filesystem and a deliberate network policy.
- Set a per-command timeout, an idle backstop, and a step budget for the task.
- Expose one
run_codetool; return errors and truncated output as results. - Kill the sandbox in a
finally, and keep a server-side reaper for when that never runs. - Log every command with its sandbox and conversation ids.
Do those six and you have an agent sandbox. Skip any one and you have a computer that runs whatever a language model says, which is a sentence that should make you a little nervous to type.