Agent Sandbox: How to Safely Run and Test AI Agents

Learn what an agent sandbox isolates, how containers, gVisor, and microVMs differ, and how to set up a sandbox for AI agents that run generated code.

Agent Sandbox: How to Safely Run and Test AI Agents cover

Key takeaways about agent sandbox

  • An agent sandbox is an isolated runtime where an AI agent executes generated code, with limits on filesystem access, network egress, CPU, memory, and lifetime.

  • A Docker container shares the host kernel, while gVisor adds a user-space kernel, and Kata Containers or Firecracker give each sandbox its own guest kernel.

  • Model calls, approvals, and long-lived credentials stay in the agent harness outside the sandbox, so generated code reaches only working files and scoped mounts.

  • AI agent sandbox security starts with egress denied by default, an allowlist for the package registry and model API, and one disposable sandbox per task.

  • BAND lets sandboxed agents work together in a shared room with @mention routing, while each agent keeps its own runtime, workspace, and credentials.

What Is an Agent Sandbox?

An agent sandbox is an execution boundary around code an AI agent generates and runs, with set limits on the files, network hosts, compute, and time that code can use.

The usual objection is "my agent already runs in Docker." A container gives the agent a private filesystem view and process table. Every system call from inside still reaches the host’s Linux kernel, so a kernel vulnerability can potentially become an escape path.

The Kubernetes SIG Apps project Agent Sandbox draws the same line in its scope note. It describes itself as "a sandbox orchestrator" that "delegates low-level container isolation" to runtimes such as gVisor or Kata Containers. The orchestrator handles lifecycle, and the runtime under the pod decides how strong the boundary is.

Why AI Agents Need Isolated Execution Environments

An AI agent sandbox earns its cost when the agent runs code no person has read, against files no person has checked.

Take a finance analytics agent that answers questions about customer-uploaded spreadsheets. Asked why third-quarter margin dropped, it writes a pandas script, runs it, and reads the output. The script and spreadsheet are new every time, and a cell can hold text to steer the model.

Run as a plain process, that script inherits the agent's reach: other customers' uploads on the host filesystem, environment variables holding the model API key and database password, the internal network, and as much CPU as one bad loop can take. A bug gets there as easily as an attack does.

How Agent Sandboxing Works

Agent sandboxing splits an agent into a trusted control side and an untrusted execution side, then puts a boundary around the second.

The harness stays outside the sandbox.

OpenAI's Sandbox Agents guide calls the two sides harness and compute. The harness owns the agent loop, model calls, approvals, and recovery state. Compute is where model-directed work touches files, runs commands, and installs dependencies. The sandbox runs code "with narrow credentials and mounts," while auth, audit logs, and human review stay "outside any one container."

For the finance agent, the model key and database connection live in the harness, and the sandbox receives one spreadsheet and a scratch directory.

What the boundary enforces

Most agent sandbox designs need controls in the same four areas: filesystem scope (which paths are mounted, and whether they are writable), network egress (which hosts the code can reach), resource limits (CPU, memory, process count), and lifetime. A sandbox nobody tears down keeps every file the last task wrote.

Types of Agent Sandboxes: Containers, VMs, and Cloud Environments

Agent sandboxes fall into four isolation tiers, ordered by how directly code can touch the host kernel. A managed cloud sandbox runs one of the four underneath, so ask any provider which one.

Sandbox type

Host kernel

Isolation strength

Startup cost

Fit for the finance agent

Process-level sandbox (seccomp, Landlock, macOS Seatbelt)

Shared

Low: filters system calls and paths for one process

Close to none

Trusted local tools only

Standard container (Docker with runc)

Shared

Moderate: namespaces and cgroups, one kernel bug from the host

Low

Internal users running reviewed code

User-space kernel (gVisor)

Shielded: gVisor's Sentry intercepts every application system call and makes only its own limited host calls

Strong

Low, with overhead on system-call-heavy work

A sound default for untrusted Python

MicroVM (Kata Containers, Firecracker)

Separate guest kernel per sandbox

Strongest of the four

Varies: Kata adds a VM boot, Firecracker targets under 125 ms

Multi-tenant uploads on shared hardware

Managed cloud sandbox

Depends on the runtime underneath

Same as that runtime

Can be cut with warm pools, which the Kubernetes project supports

Ask which of the four rows it runs

On Kubernetes, the choice is the pod's RuntimeClass. The finance agent's uploads come from customers, so the shared-kernel rows are out, and a microVM is the stronger pick when tenants share hardware.

Agent Sandbox Security Risks and Best Practices

AI agent sandbox security centers on one entry in OWASP's Top 10 for Agentic Applications, published in December 2025: ASI05, Unexpected Code Execution, where natural-language paths lead to code running on the system.

Risks a sandbox contains

A configured sandbox caps the damage when generated code deletes files, forks until the host stalls, or sends data to a server named in a poisoned cell:

  • Deny egress by default and allowlist the hosts each task needs.

  • Keep long-lived secrets out, and let a proxy or the harness inject credentials per request.

  • Give each task or tenant its own sandbox.

  • Cap CPU, memory, process count, and wall-clock time.

  • Destroy the sandbox on exit, or snapshot it for inspection.

Risks a sandbox does not contain

Three decisions sit outside any sandbox: which tools the agent may call, which other agents it may contact, and what data it may send to a host you allowed. If the finance agent may post to an approved reporting API, the sandbox will let it post the entire customer table there.

How to Set Up a Sandbox for AI Coding Agents

A coding agent sandbox holds the repository's toolchain, the working copy, and little else. Six steps cover one agent:

  • Pick the boundary from the table above. A container suits your repo on your laptop, and untrusted dependencies belong in gVisor or a microVM.

  • Build an image pinned to the repo's toolchain: the language version, the package manager, and the lockfile CI uses.

  • Mount only the working copy, and leave the home directory with its SSH keys on the host.

  • Allow egress to the package registry and, if the agent loop runs inside the sandbox, the model API. Block the rest.

  • Inject credentials from outside through the harness or a host-side proxy, scoped to the task.

  • Set a teardown rule: delete on exit, or snapshot when a person will review the run.

For many agents with separate tokens and worktrees, see the guide to infrastructure for coding agents.

Managing Sandboxed Agents in Multi-Agent Development Workflows

In a multi-agent development workflow, each agent gets its own sandbox, and work moves between sandboxes only as a named artifact.

Put a reviewer agent in the coder's sandbox, and it can write where the coder writes, so its review covers files it could have changed. Give it a read-only checkout of the pushed branch instead. Shared state travels the same way, as a branch, a single-writer volume, or a message. A shared scratch directory works until two agents overwrite each other and nothing records which one did it.

Credentials stay per agent too, so the test runner can hold a CI token the coder never sees. The order in which these agents run belongs to the stages of a coding workflow. Isolation also removes the shared filesystem the agents coordinated through, yet they still need to pass work, ask questions, and wait on approvals. A branch name cannot carry a question.

How BAND Connects Agents That Run in Separate Sandboxes

Sandboxes isolate one agent at a time, yet the work still crosses from one sandbox to the next. When sandboxed agents hand work across, BAND gives them a shared room where each message reaches only the agents it @mentions. A participant nobody @mentions is not triggered, and a reviewer sees only what the coder sends it, without the coder's tool calls.

BAND’s Docker Sandbox kit runs an agent workspace inside a Docker Sandbox microVM, keeping the agent’s execution environment separate from the host. Credentials should remain outside the sandbox where possible and be exposed only through narrowly scoped mechanisms required by the task. When Codex is configured to request approval for an action, and BAND’s approval mode is manual, the request is posted in the room and waits for a participant to approve or decline it. BAND and Docker announced the integration on September 24, 2026.

BAND does not draw the boundary itself. Docker Sandboxes, a Kubernetes runtime, or your cloud provider does that, and BAND carries the conversation across it. It is not an eval suite or a model monitor either, and as of November 2026, the Docker kit guide targets macOS only. See coordinating coding agents with BAND, the docs to connect coding agents, and the BAND platform.

Book a demo

FAQs about agent sandbox

The message means Codex cannot continue until its local execution sandbox is available and configured. On Windows, Codex uses native OS-level isolation to restrict the commands it runs, including filesystem writes and network access. The available sandbox implementation and setup requirements can change between Codex versions, so check OpenAI’s current Windows sandbox documentation if setup fails or administrator access is required. OpenAI's Windows sandbox guide covers each mode.

No. An AI regulatory sandbox is a supervised setting where AI providers develop and test systems with a national authority before market launch. Article 57 of the EU AI Act requires each member state to have at least one operational national sandbox by August 2, 2027. An agent sandbox is a runtime boundary around code. The two share a word and little else.

The code gets whatever the host can reach: other workloads, mounted secrets, the cloud metadata endpoint, and the internal network. Container escapes trace to kernel bugs, runtime bugs such as runc's CVE-2019-5736, or misconfigurations such as a mounted Docker socket. Secrets kept in the harness or a proxy are at least not sitting in the sandbox when it happens.

A persistent sandbox keeps its filesystem and identity across sessions instead of deleting them after each task. The Kubernetes agent-sandbox project gives each Sandbox a stable hostname, storage that survives restarts, and pause and resume. The cost is leftover state. Whatever one task wrote, including anything a poisoned input planted, waits for the next task to read.

Ask for evidence instead of a feature list: which kernel your workload shares with other tenants, the default egress policy, whether secrets enter the sandbox, how long data persists after teardown, and whether a written threat model exists. The Kubernetes agent-sandbox project publishes its own threat model, so asking a vendor for one is fair.