An agent sandbox is an isolated execution environment that limits what code run by an artificial intelligence (AI) agent can access and change. Agents often write and run their own code, so a sandbox keeps a mistaken or untrusted command away from your host system, production data, and unrelated secrets.
For example, suppose a coding agent is asked to fix a failing test in /workspace/app. The sandbox makes that directory writable, hides the rest of the filesystem, and allows outbound network traffic only to the package registry.
During the run, generated code tries to read the developer’s secure shell (SSH) keys. The read is denied and logged. Later it tries to send project files to an unrelated host. That connection is also denied and logged.
The fix might still be wrong. But the code could not reach the keys or send files through an unapproved route. That is the job of a sandbox: it limits what code can reach, but it does not decide whether an allowed action is a good idea.
Build better agents with Arize
Trace, evaluate, and learn. Build agents that work with Arize AX and start tracing your runs today.
Prefer open source? Try Arize Phoenix for self-hosted, open source agent observability.
Why agent sandboxes matter
An agent often needs to run tests, transform files, or call tools while it works. If that code runs under the developer’s full account, it has the same reach as the developer: home directories, cloud credentials, source repositories, and production services.
A sandbox puts a boundary between the code the agent runs and that wider environment. Sandboxes are useful for:
- Running generated code: Execute tests, scripts, and file changes without giving the code direct access to the host system.
- Protecting credentials: Keep long-lived tokens out of the agent’s environment, or replace them with short-lived, narrowly scoped ones.
- Reducing blast radius: Limit how much damage a wrong or untrusted command can do.
- Investigating failures: Record commands, file changes, and network attempts so you can see what happened inside the boundary.
For more on where sandboxing fits among other controls, see agent security and agent governance.
How an agent sandbox works
Implementations vary. Some rely on operating-system permissions. Others use containers, virtual machines, or managed execution services.
The strength of isolation differs between these approaches. Do not assume that every product using the word sandbox provides the same guarantee.
Most sandboxes control the same four areas:
- Filesystem: The agent sees a limited working directory, often a copy or mounted view of the project. Access outside it is denied or flagged.
- Network: Outbound access is blocked entirely or allowed only to named destinations. This matters when the task needs to install packages.
- Processes and resources: The sandbox limits child processes, execution time, memory, central processing unit (CPU) use, and output size.
- Credentials: Tokens stay out of the environment, or the run receives short-lived, narrowly scoped credentials instead of the user’s long-lived ones.
Anthropic’s Claude Code sandboxing research is a primary source for one implementation’s approach to filesystem and network isolation. Read the documentation for the environment you use, because each implementation’s exact controls differ.
How to set up and test an agent sandbox
A sandbox only protects you if its boundary is written down and tested. Work through three steps.
Write the boundary as a policy
State the boundary in a form someone else can test. Include:
- Readable and writable paths.
- Network mode and allowed hosts.
- Available credentials and their scope.
- Time and resource limits.
- What happens when an action is denied.
The following illustrative policy describes the coding agent from the opening example. Field names vary by sandbox tool, so treat it as a checklist rather than a configuration format.
# Illustrative policy. Field names differ between sandbox tools.
filesystem:
default: deny
writable:
- /workspace/app
network:
mode: allowlist
allowed_hosts:
- "<package registry host>"
credentials:
inherit_user_credentials: false
on_denied_action: block_and_log
Probe the boundary
Next, run deliberate probes. Ask the agent to do each of these:
- Read a file outside the project.
- Write outside the working directory.
- Reach a host that is not on the allowlist.
- Run past the time limit.
Each probe should be denied or stopped in the way the policy states. Until you run these probes, you have not confirmed that the sandbox enforces its policy.
Trace what happens inside
Record commands, exit codes, changed files, requested packages, and network attempts. Tag each record with the agent run identifier.
When a task fails, those records separate a code error from a denied permission. When a task succeeds unexpectedly, they show which allowed path made it possible.
For more on the tracing context, see AI observability.
Common agent sandbox mistakes
Most sandbox problems come from a boundary that is wider than intended or a team that works around it.
- Granting more than the task needs: If the sandbox makes a production database writable and the agent holds valid credentials, deleting rows is an allowed action. Give each run the smallest writable scope, network reach, and credential set that lets the task proceed.
- Leaking access through configuration: Mounts that include home directories, inherited environment variables, shared sockets, or broad network allowlists can quietly widen the boundary.
- Setting resource limits too low: Tight limits cause flaky failures that look like model errors.
- Disabling controls to fix installs: Network allowlists can break package installation and tempt teams to turn controls off. Instead, provide a stated dependency route and record when it is used.
- Assuming the sandbox protects visible data: If the task requires reading sensitive files, those files can still appear in prompts, logs, or outputs. Apply redaction and retention controls to traces as a separate step.
Agent sandbox vs. permission prompts and other controls
A sandbox is often confused with nearby controls. Each one handles a different risk.
A permission prompt asks a human to approve an action. A sandbox limits what the action can affect, whether or not anyone is watching. The two work together. Prompts handle judgment calls inside the allowed scope, and the sandbox limits the damage if judgment fails.
A Python virtual environment is not a sandbox. It organizes packages, but by itself it does not isolate the filesystem or network.
Evaluation is also different. Evaluation checks whether the agent’s behavior meets your criteria. A sandbox constrains where its code runs.
An agent can pass every evaluation and still need a sandbox in production, because evaluations sample behavior rather than bound it. A tightly sandboxed agent can also produce poor work safely. You need both.
For permission design, see access control for agents and the agent policy layer.
Frequently asked questions
Does a sandbox make agent code safe?
No. A sandbox limits what the code can reach and change. Actions inside the allowed scope can still delete data, spend money, or produce wrong results. Combine sandboxing with least-privilege permissions, review, and evaluation.
What should an agent sandbox restrict by default?
Start with the filesystem, network, credentials, child processes, and time and resource use. Deny by default, then allow the specific paths, hosts, and tools the task needs. Write the allowances down and test them with deliberate probes.
Is a container automatically an agent sandbox?
No. A container becomes a sandbox only when its mounts, user, network, credentials, and resource limits are configured as a boundary for untrusted code. A container with the host home directory mounted and full network access provides little isolation.
Should sandbox denials count as agent failures?
Not automatically. Some denials show the control blocking a risky or mistaken action. Others show that the task needs a legitimate path that was not allowed. Log the attempted action so a person can tell the difference.
Putting agent sandboxes to work
Before you call an environment sandboxed, write down its allowed directories, network destinations, time and memory limits, and credential scope. Then probe each boundary and confirm it holds.
Log commands, file changes, and network attempts from inside the sandbox with the run identifier, so failures and escape attempts can be investigated later. If you already trace agent runs in Arize AX or Arize Phoenix, record sandbox events in the same trace as the agent’s other steps.
Arize’s article on observability-driven sandboxing discusses combining these boundaries with observation.
