all postsblog / ai agent sandboxes

blog

How to Create an AI Agent Sandbox (Step by Step, 2026)

written by
Ajay Kumar
published
reading time
10 min read
topics

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 install into, 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 finally block 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.
A useful test for your design: assume the model has been told by a malicious README to read your cloud credentials and send them somewhere. Walk through each clause and ask what stops it. If the answer to any step is "the model probably wouldn't", that clause isn't done.

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.

Three ways to build an AI agent sandbox
Docker containerDIY Firecracker microVMManaged platform
Isolation boundaryNamespaces + cgroups on a shared host kernelOwn guest kernel behind KVMDepends on the vendor — check whether it is a container, gVisor, or a microVM
Time to first sandboxMinutesDays for one VM; months for a fleetMinutes
Create latencyFast for small imagesSeconds on a cold boot unless you build snapshot-restoreVendor-dependent; verify against their docs
What you operateDocker hosts, image hygiene, seccomp profilesKernel, rootfs images, tap networking, jailer, snapshot store, scheduler, guest agentAn API key and a bill
Good fitYour own trusted code, local dev, low-risk internal toolsSandboxing is your product and you want to own the boundaryThe 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.

bash
# 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:

json
{
  "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.

The DIY path is the right call if sandboxing is the product you sell or compliance requires you to own the boundary. It is a poor call if you need a sandbox by Friday so your agent can run pandas.

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.

python
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 job

A few design choices in there are load-bearing, and they map straight back to the checklist:

  • One tool, one string in. A single run_code tool taking a shell command is easier for models to use well than ten narrow tools, and you can still add read_file/write_file later via sbx.filesystem if 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 cat of 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=60 per command, ttl_seconds=600 idle backstop, and range(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

  1. Pick the boundary to match the threat: containers for your own code, microVMs for code a model wrote for a stranger.
  2. Give the agent a disposable, copy-on-write filesystem and a deliberate network policy.
  3. Set a per-command timeout, an idle backstop, and a step budget for the task.
  4. Expose one run_code tool; return errors and truncated output as results.
  5. Kill the sandbox in a finally, and keep a server-side reaper for when that never runs.
  6. 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.

faq

Frequently asked questions

How do I create a sandbox for an AI agent?

Choose an isolation boundary (a hardened container for trusted code, a microVM for untrusted model-written code), give it a disposable filesystem, a network policy, per-command and idle timeouts, and a guaranteed teardown. Then expose it to the model as a single tool such as run_code that takes a command and returns stdout, stderr, and the exit code. You can build it with Docker, with Firecracker directly, or use a managed sandbox API that does the VM plumbing for you.

Is Docker good enough as an AI agent sandbox?

For your own trusted code and local development, a container with dropped capabilities, no network, a read-only root, and resource limits is reasonable. For code a model generated on behalf of untrusted users, it is weaker: every container shares the host kernel, so a kernel vulnerability or misconfiguration can reach the host and other tenants. MicroVMs such as Firecracker give each sandbox its own guest kernel behind hardware virtualization.

What is the minimal Firecracker config for a sandbox VM?

A boot-source with kernel_image_path and boot_args, a drives entry with drive_id, path_on_host, is_root_device, and is_read_only, a machine-config with vcpu_count and mem_size_mib, and optionally a network-interfaces entry with iface_id and host_dev_name pointing at a tap device. That boots a VM, but a usable agent sandbox also needs a rootfs image, tap networking, copy-on-write clones, the jailer, a guest agent for exec, and usually snapshot-restore for fast creates.

How should an LLM call the sandbox?

Through tool calling. Define one tool, for example run_code, with a JSON Schema input of a single command string. When the model returns a tool call, run the command in the sandbox with a timeout, then send back stdout, stderr, and exit code as the tool result, truncated so large output doesn't flood the context. Return errors as results so the model can correct itself, and cap the number of tool-calling steps per task.

Should each agent task get a new sandbox?

For independent, one-shot executions, yes: a fresh sandbox per task gives a clean slate and the strongest separation between runs. For coding and data-analysis agents that build up state across turns, keep one sandbox per conversation so installed packages and files persist, with an idle timeout as a backstop and an explicit kill when the conversation ends.

links

Keep reading

more posts

Related posts

More in AI agent sandboxes · See AI agent sandboxes on PandaStack

pandastack

Run code in a microVM in one API call.

50–100 ms cold start. Fork, snapshot, and scale to zero.

measured on the host; your network round trip is extra