Agent sandbox (AI)

What is an agent sandbox?

An agent sandbox is a restricted environment where an AI agent runs the commands it decides to run. Inside it, the agent can create files, install packages, execute scripts and call APIs. Outside it, your laptop, your file shares and your production database stay out of reach.

The word sandbox is older than AI agents and usually means something else. In a data or software team it often means a copy of an environment for experimentation, a development tier next to test and production. That kind of sandbox exists so people can try things without breaking the live system. An agent sandbox exists for a different reason: the code inside it was written by a model a second ago, based on text that may have come from a customer email, a web page or a pull request comment, and nobody read it before it ran.

So the question an agent sandbox answers is not "is this environment safe to experiment in". It is "if this command turns out to be hostile, how far does it get".

What the sandbox actually restricts

Two boundaries do the work, and both have to hold.

Filesystem. The agent gets write access to the project directory it is working in and a temporary directory, and nothing else. Claude Code's sandboxed Bash tool works this way: by default, commands can write only to the working directory and the session temp directory, and cannot modify shell configuration files or system binaries. Reads are the interesting part. Claude Code's default still allows reading the rest of the computer, which includes files like ~/.aws/credentials and ~/.ssh/, so blocking those is a separate setting rather than something you get for free.

Network. Outbound traffic goes through a proxy that only lets approved hosts through. OpenAI's Codex CLI takes the strict end of this: its default local mode, workspace-write, lets the agent edit inside the workspace with network access off unless you explicitly turn it on. Claude Code pre-allows no domains at all and prompts the first time a command needs a new one.

The enforcement happens at the operating-system level rather than in the agent's own code, which is the point. Claude Code and Codex both build on Seatbelt, the sandbox framework built into macOS, and on bubblewrap on Linux and WSL2. Because the kernel enforces the boundary, it holds for every child process the command spawns, and it holds regardless of what the model thought it was running.

Neither half is useful alone. Anthropic's own documentation is direct about it: without network isolation a compromised agent could exfiltrate sensitive files like SSH keys, and without filesystem isolation a compromised agent could backdoor system resources to gain network access.

How a sandbox differs from a permission layer

Most agent products ship both, and they are easy to confuse because they both feel like "security settings".

A permission or approval layer decides whether an action runs. It sits in front of the tool call, reads the command, and either allows it, blocks it, or asks you. Codex describes this as its approval policy, with modes that range from asking before anything mutates state to never asking at all. This is the layer Human-in-the-Loop (HITL) review sits in.

A sandbox decides what an action can reach once it runs. It has no opinion about intent. A command that was approved for a perfectly good reason still cannot write outside the working directory.

The practical difference shows up when the approval layer is wrong. Approvals are evaluated on the command string, or by a classifier reading it, so a command that does more than its name suggests can slip through. The sandbox does not care what the command was called. That is why the two layers are usually stacked: approvals catch obviously bad decisions in advance, the sandbox limits the ones that got through.

It also explains a rule that shows up in every vendor's docs in some form. If you turn off the prompts and let an agent run unattended, the isolation boundary becomes the only thing left protecting your machine.

Why prompt injection turns this into a security control

An agent sandbox looks like a convenience feature. You approve fewer commands, work moves faster. The reason it is more than that is prompt injection.

An agent reads untrusted text constantly: web pages, repository issues, support tickets, PDFs, tool output from other systems. Any of that can contain instructions aimed at the model rather than at you. The model has no reliable way to tell an instruction from data, so you have to assume that sooner or later a hostile instruction reaches it and gets acted on.

Once you assume that, the sandbox stops being about tidiness. It is the thing that decides whether a successful injection means a junk file in a temp directory or a copy of your SSH key posted to someone else's server. OpenAI puts the warning next to the network setting for exactly this reason: enabling network access or web search means prompt injection can cause the agent to fetch and follow untrusted instructions.

Which brings up the part that matters most for a data team, and the part sandboxing does not fix on its own. If the agent process has your production database connection string sitting in an environment variable, the isolation is decorative. The agent does not need to escape the sandbox, because everything it needs to do damage is inside the sandbox with it, and the network allowlist probably includes the warehouse it is supposed to query.

This is why credential handling is treated as its own control rather than a side effect of isolation. Claude Code can unset named environment variables before each sandboxed command, or mask them: the command sees a placeholder value, and the proxy swaps in the real credential only for the hosts you named. The command, and anything it logs, never holds the real secret. The general form of the rule is least privilege: an agent that only needs to read three tables should hold a credential that only reads three tables, sandbox or no sandbox.

Where agent sandboxes run

The options differ in how much they cover and how much they cost you to run.

1. An OS sandbox on your own machine. No containers, no infrastructure. It wraps the commands the agent runs, which also means the parts of the session that are not shell commands can fall outside it. In Claude Code, MCP servers and hooks are separate processes that run unconstrained on the host unless you wrap the whole thing.

2. A container or dev container. The whole agent process goes inside, usually with a default-deny firewall on egress. This is the common choice for teams who already have container infrastructure and CI runners.

3. A virtual machine. Its own kernel, and in cloud or microVM deployments its own virtualised hardware. Slower to provision, appropriate when you are running code you genuinely do not trust.

4. A managed sandbox service. Azure Container Apps dynamic sessions provide Hyper-V isolated, prewarmed environments that Microsoft positions for exactly this, running AI-generated code without risking your production systems, with sessions destroyed after a cooldown period. Google's GKE Agent Sandbox takes a similar line with gVisor and Kata Containers, and applies a default-deny network posture so sandboxed code cannot reach internal networks it was not granted.

The managed services exist because the ephemeral part is genuinely awkward to build yourself. A sandbox that survives between runs accumulates whatever the last run left in it.

What to watch out for with agent sandboxes

Secrets already inside the boundary
Check what is in the environment the agent inherits, not just what it can reach. Sandboxed commands typically inherit the parent process environment, credentials included.

Allowlists that are wider than they look
Allowing a broad domain can open a path for data exfiltration. Anthropic flags this directly for entries like github.com, because a proxy that decides on hostname without inspecting TLS can be worked around. An allowlist is only as narrow as its widest entry.

Escape hatches
Most implementations let a command that fails under isolation retry outside it, since otherwise ordinary tools break. That is a reasonable default and a real hole. If you are relying on the sandbox as a control, turn the escape hatch off and accept the friction.

What sits outside the boundary
Per-command sandboxes cover shell commands. Built-in file tools, MCP servers and hooks may not be inside. Know which of your session actually runs isolated.

Sandbox as a substitute for scoping the work
Isolation limits damage from an action the agent should not have been able to take. It does not replace deciding which tools the agent gets. An agent that only needs to draft a report does not need write access to the warehouse, in any environment.