How to sandbox an AI agent, and what a sandbox does not cover

A sandbox is a limit on what an AI agent can do that holds even when the agent is wrong, confused or manipulated. That is different from asking the model to be careful, or from showing a person a confirmation prompt. This guide explains what an agent sandbox covers, the main ways to build one, what two widely used coding agents do, and where sandboxes leak. It was checked on October 31, 2026 against the vendors' own documentation, and it does not rely on news reports of specific incidents.

What a sandbox is, and what it is not

Three questions define an agent sandbox.

• What can it read and write? Filesystem limits decide whether a command can touch only the project folder or the whole machine, including credential files.
• Where can it send data? Network limits decide whether a command can reach any server or only an approved list. Without them, file limits only partly help, because anything the agent can read it may be able to send out.
• What can it run? Isolation of the process, from system-call filtering up to a separate kernel or virtual machine, decides how much of the host a compromised process can reach.

A sandbox is not a permission prompt. A prompt asks a person; a sandbox constrains the process whether or not anyone is watching. The two work together. Anthropic's security documentation notes that a Bash command you approve can still write anywhere your user account can, and recommends turning on sandboxing to restrict Bash at the operating system level. OpenAI's Codex documentation draws the same line: the sandbox defines what Codex can technically do, and the approval policy defines when it must stop and ask.

Ways to isolate an agent

These options sit on a spectrum from light to heavy. Each trades convenience against how much stands between a compromised process and the host. The descriptions below are the projects' own.

• Operating-system sandboxing of a process. The OS restricts one process and its children. Claude Code uses the macOS Seatbelt framework and, on Linux and WSL2, bubblewrap. Codex documents an OS-enforced sandbox on each platform it supports. This is light and fast, and it suits an agent running on a developer's machine.
• Containers. Docker's documentation describes isolation built on kernel namespaces and control groups, with a restricted set of Linux capabilities. It also warns that default capabilities and mounts may provide incomplete isolation, alone or combined with kernel vulnerabilities, and that a bind-mounted host directory can let a container alter the host filesystem. Containers are a good baseline and they share the host kernel, so they are only as strong as their configuration.
• A userspace kernel (gVisor). gVisor describes itself as an application kernel written in Go that intercepts an application's system calls and acts as the guest kernel, so the application does not talk to the host kernel directly. The stated aim is to reduce container-escape risk. The stated costs are reduced compatibility, since not every system call is implemented, and higher overhead for workloads that make many of them.
• Micro virtual machines (Firecracker). Firecracker runs workloads in lightweight VMs that use the Linux KVM, combining hardware-virtualization isolation with container-like speed. Its design leaves out unneeded devices to shrink the attack surface, and its README says overall security depends on a well-configured Linux host.

None of these is automatically right. Code you generate and run on behalf of anonymous users needs a stronger boundary than a coding assistant working in your own repository.

What two coding agents actually do

Claude Code

Anthropic's documentation describes the Bash sandbox as an OS-enforced boundary around shell commands and the processes they start. It has two layers. For the filesystem, commands can write to the working directory and a temporary directory; reads are allowed across most of the machine unless denied, and the documentation says that includes credential files such as those under ~/.ssh and ~/.aws, so those need protecting by configuration. For the network, commands have no direct route out: connections go through a proxy on the machine that checks each host against a list of allowed domains, and the list starts empty.

The documentation is explicit about what the sandbox does not cover. File tools, MCP servers and hooks run outside it and follow permission rules instead. The sandbox is off by default. If it cannot start because of a missing dependency or an unsupported platform, commands run unsandboxed unless you set the option that makes Claude Code exit instead. Commands you list as excluded run with your full access. For sensitive work, Anthropic recommends running the whole process inside the sandbox runtime or a dev container, and using virtual machines for untrusted content.

OpenAI Codex

OpenAI's documentation says Codex runs locally with an OS-enforced sandbox, typically limiting it to the current workspace, plus an approval policy that controls when it must stop and ask. By default the agent runs with network access turned off. The documentation warns against modes that remove the sandbox and approvals, and warns that prompt injection can lead the agent to follow untrusted instructions, especially when web search or network access is enabled.

The pattern is the same in both: a narrow default, an explicit way to widen it, and a documented caution that the wider settings carry risk.

Where sandboxes leak

A sandbox is only as good as its configuration and its coverage. These are the common gaps, taken from the documentation above and from how the pieces fit together.

• Readable secrets. If credentials are readable inside the sandbox, anything running there can read them.
• Open network paths. One broadly allowed destination can be enough to send data out. A filesystem limit does not help once data can leave.
• Things that run outside it. Tools, plug-ins and servers that sit outside the sandbox boundary have whatever access they were given, as with MCP servers and hooks in Claude Code. Our guide to MCP security covers that side.
• Silent fallback. If the sandbox fails to start and the tool carries on without it, you have no sandbox. Decide whether the agent should fail closed.
• Escape hatches. Excluded commands, retry-without-sandbox options and full-access modes are designed in. Know who can switch them on.
• Shared kernel and mounts. Containers share the host kernel, and a mounted host directory is a path into the host.
• Over-broad agency. OWASP lists Excessive Agency as LLM06:2025 in its Top 10 for LLM Applications. A sandbox does not reduce what the agent is permitted to do inside its boundary.

A practical checklist

Items marked (docs) follow behavior described in the vendor and project documentation above. Items marked (ours) are our own engineering recommendations.

Boundary

• Allow writes only in one working directory, and keep that directory separate from anything you cannot afford to lose. (docs, ours)
• Keep credential files and tokens out of reach of the process, rather than relying on the agent not to read them. (docs, ours)
• Block outbound network access by default and allow named destinations only. (docs)
• Use a fresh, disposable environment per task or session for untrusted input, and discard it afterwards. (ours)
• Set limits on CPU, memory, time and disk, so a runaway process stays contained. (ours)
• Choose the isolation level from the threat: an OS sandbox for your own repository, a container or stronger for code from outside, a VM for untrusted content. (docs, ours)

Configuration

• Check that the sandbox is actually on, and make the agent stop if it cannot start. (docs)
• Keep a short, reviewed list of exceptions, and control who can add to it. (docs, ours)
• Do not mount sockets, host directories or credentials into a container unless you need to. (docs, ours)
• Treat tools that run outside the sandbox as separate trust decisions. (docs)

Testing and operations

• Test the sandbox itself: try to read a secret, write outside the folder and reach a blocked host, and confirm each is refused. Our post on AI agent testing environments covers building the environment for this. (ours)
• Log commands, file writes and network requests so you can see what an agent did. (ours)
• Keep a person in the loop for actions with outside effects, such as sending, paying and deleting. (ours)

What this does not solve

A sandbox limits damage, not intent. The model can still be steered by text it reads, and anything the agent is allowed to do inside the boundary remains possible. That is why a sandbox belongs next to least-privilege access, defences against prompt injection and review of risky actions. For the broader list, see our AI agent security checklist and our explainer on identity and access management for AI agents.

How we approach this

When we build agents that run code or use tools, we begin with the question of what the worst thing the agent could do inside its boundary would be, and we shrink the boundary until that is acceptable. Then we test the boundary directly, not only the agent. If you want an outside review of how an agent is contained, that is part of our AI governance and security work.

Sources: Claude Code, sandboxing, Claude Code, security, OpenAI Codex, agent approvals and security, Docker Engine security, gVisor documentation, Firecracker, OWASP Top 10 for LLM Applications. All read October 31, 2026. Vendor settings change often, so check the current pages before configuring.