Imagine giving an AI coding agent a straightforward job: update a dependency, run the tests, and fix whatever breaks.
To do that work, the agent may need to read files, edit code, install packages, and run shell commands. Those abilities are what make it useful. They are also what make a mistake matter.
A wrong command could overwrite an unrelated file. A package script could inspect credentials on the machine. Instructions hidden in a document or repository could try to redirect the agent toward data it was never supposed to touch. The problem is no longer only whether the model produces a bad answer. The system can act on that answer.
This is why capable agents need sandboxes.
A sandbox is a constrained environment where code and tools can run without receiving normal access to the rest of the machine or network. It narrows the consequences when the agent, a tool, or something in the agent's input behaves badly.
The key word is narrows. A sandbox is an important safety boundary. It is not a complete safety system.
What a Sandbox Actually Limits
A useful sandbox can control several kinds of reach:
- Files: which folders can be read, which can be changed, and whether changes disappear when the task ends.
- Network: whether the agent can connect to the internet, only approved services, or nothing outside the sandbox.
- Processes: which programs can run and how much CPU, memory, or time they can consume.
- Secrets: whether environment variables, authentication tokens, SSH keys, and browser sessions are visible.
- Devices and system services: whether the task can reach cameras, local sockets, Docker, or other powerful host capabilities.
The implementation may be a container, virtual machine, operating-system policy, remote execution service, or a combination of those. The name of the mechanism matters less than the boundary it actually enforces.
If an agent can edit only a temporary copy of one repository, then a mistaken delete command can damage that copy without erasing a personal documents folder. If outbound network access is blocked, code from an untrusted package cannot simply send local data to an arbitrary server. If secrets are absent, the agent cannot expose credentials it never received.
That is containment: assume something will eventually go wrong, then reduce what the failure can reach.
Why Instructions Are Not Enough
It is tempting to solve this with a prompt:
Only change files in this project. Never reveal secrets. Ask before doing anything risky.
Those are useful instructions. They are not a boundary.
Models can misunderstand a request. Tools can fail in surprising ways. A repository can contain malicious or misleading text. A dependency can run installation code. Even a careful agent can construct a command that behaves differently than expected.
An instruction asks the system to behave. A sandbox limits what happens when it does not.
This distinction is especially important with prompt injection. An agent may read a webpage, issue, email, or source file that contains instructions aimed at the model rather than the person. Better prompting and input handling can reduce that risk, but containment changes the consequence. A malicious instruction asking for a credential is less useful when the credential is not available inside the environment.
A Sandbox Is Not a Permission System
Sandboxes and permissions answer different questions.
A sandbox asks:
What can this execution environment reach?
A permission or tool policy asks:
Which capabilities may this agent use?
An approval gate asks:
Which action needs a person to say yes right now?
These controls overlap, but none replaces the others.
Suppose an email agent runs inside a perfectly isolated container. If it has an API token that can send mail as you, it can still send the wrong message. The container may protect the laptop while doing nothing to protect the inbox.
The better design gives the agent a draft tool by default, limits the account or scopes the credential, and requires approval before sending sensitive mail. The sandbox still helps contain local code execution, but the permission and approval layers govern the real-world action.
This is the same distinction behind defining an AI system as a bounded job with explicit tools and authority. In What It Means for AI to Have a Job, the role determines what the agent owns. The sandbox is one way to enforce part of that boundary.
Three Different Agent Jobs
The right sandbox depends on the job.
A coding agent
A coding agent may need a writable copy of a repository, a compiler, a test runner, and access to a package registry. It probably does not need personal files, cloud deployment credentials, a logged-in browser profile, or unrestricted access to the local network.
A strong default is an isolated working copy with only the project mounted, no secrets unless the task requires them, controlled network access, and a clear diff for review. Deployment remains a separate permission.
A research agent
A research agent may need web access and a place to save notes. It may not need shell access at all. If it downloads documents or runs analysis code, those steps can happen in a temporary environment without access to unrelated files.
Network policy is more complicated here because browsing is the job. Instead of pretending the agent can work offline, the system can restrict sensitive destinations, keep credentials out of the browsing environment, log requests, and separate retrieved content from trusted instructions.
A communication agent
A communication agent may work mostly through APIs. A traditional filesystem sandbox provides only part of the protection because the important boundary lives in the tools and credentials.
Can it read every channel or only one? Can it draft a reply, send it, delete messages, invite people, or change permissions? Does it act as itself or as a human user?
For this job, narrow tool scopes and approval rules matter at least as much as process isolation.
The Escape Hatch Can Erase the Boundary
Many agent systems include a way to run a command outside the sandbox when the constrained environment cannot complete the task. Sometimes that is necessary. It is also where a careful design can quietly collapse.
If the agent can elevate itself whenever a command fails, the sandbox is mostly a suggestion. A meaningful escape path should be explicit, narrow, visible, and tied to a reason. It should not turn one blocked package install into general access to the host.
This is where the system should often pause. As When AI Should Ask Instead of Answer argues, asking is part of the work when the next step changes the risk.
The useful question is not simply, “Can the agent continue?” It is, “What new authority would continuing require?”
Safer Defaults
There is no single sandbox configuration for every agent, but a few defaults travel well:
- Start with an empty or temporary environment. Add access deliberately instead of trying to remove it later.
- Expose only the files the task needs. Prefer read-only access until writing is required.
- Control outbound network access. If the task needs the web, decide which destinations and credentials belong in that path.
- Keep secrets out by default. Provide narrow, short-lived credentials only for the action that needs them.
- Separate preparation from execution. Let an agent draft, test, or stage a change without automatically sending, deploying, paying, or publishing.
- Set resource and time limits. A safe task should not be able to run forever or consume the entire machine.
- Keep evidence. Logs, tool calls, diffs, and outputs make review and diagnosis possible.
- Treat elevation as a new decision. Moving outside the sandbox should require a clear reason and an appropriate gate.
These defaults do not make an agent harmless. They make its authority easier to understand.
The Better Mental Model
A sandbox is sometimes described as a locked room for an agent. That is close, but incomplete.
The room may still contain powerful tools. It may have a phone, a company credit card, and keys to another building. Locking the door controls one kind of movement. It does not decide how everything inside the room may be used.
A dependable agent needs layers:
- a sandbox to contain execution
- tool policies and credentials to limit capabilities
- approval gates for consequential actions
- logs and review to make behavior visible
- recovery plans for the changes that still go wrong
The goal is not to make useful agents powerless. It is to give their power a shape.
When an agent can run code or use tools, mistakes stop being only words on a screen. A sandbox gives those mistakes somewhere smaller to land.
