An agent sandbox is an isolated execution environment in which AI agents run code, shell commands, browsers and other tools under strictly limited access to files, networks, credentials and system resources. It is also called an agent execution sandbox, and its purpose is to let an autonomous system act on a real computer while containing the consequences of errors, misuse or manipulation.
In artificial intelligence, the sandbox has become a standard component of coding agents, computer-use agents and code execution tools. Because a language model can be steered by untrusted input such as prompt injection, the safety of an agent cannot rest on the model behaving well; it must also rest on what the environment allows.
How an agent sandbox contains actions
An agent sandbox works by placing a boundary between the agent’s actions and the host system, so that every command executes inside a constrained space with its own filesystem, process tree and network rules. The agent harness sends tool calls into this space and reads back outputs, while the sandbox enforces limits the model cannot override.
Effective sandboxes combine several independent control layers, because a single mechanism rarely covers every path an agent might take. The table lists the layers most designs include.
| Layer | What it restricts | Typical mechanism |
|---|---|---|
| Filesystem isolation | Which files can be read or written | Mount namespaces, read-only mounts, overlays |
| Process isolation | Visibility of other processes | PID namespaces, separate virtual machine |
| Network egress control | Which hosts the agent can reach | Allowlists, proxies, firewall rules |
| System call filtering | Which kernel operations are allowed | seccomp profiles, gVisor |
| Resource limits | CPU, memory, disk and run time | cgroups, quotas, timeouts |
| Secret handling | Exposure of credentials and tokens | Scoped short-lived tokens, injection proxies |
The sandbox is usually ephemeral: it starts from a known image, lives for one task or session and is destroyed afterward. This fresh-state principle prevents malicious files or altered configuration from persisting between runs.
Isolation technologies and their strength
Agent sandboxes are built on a spectrum of technologies that trade isolation strength against startup time and overhead. The choice depends on whether the agent runs trusted internal code or arbitrary code influenced by outside content.
| Technology | Isolation strength | Startup time | Typical use |
|---|---|---|---|
| Language-level sandbox | Low | Milliseconds | Restricted interpreters, WebAssembly runtimes |
| OS-level sandbox | Moderate | Milliseconds | Local coding agents on a developer machine |
| Container | Moderate | Under a second to seconds | Hosted code execution with shared kernel |
| User-space kernel | High | About a second | gVisor-style syscall interception |
| MicroVM | High | Roughly 100 ms to a few seconds | Multi-tenant agent platforms such as Firecracker-based services |
| Full virtual machine | Very high | Tens of seconds | Computer-use agents with a desktop |
A frequent misconception is that a standard container is a security boundary for hostile code. Containers share the host kernel, so a kernel vulnerability can allow escape; multi-tenant platforms that execute untrusted agent code therefore tend to prefer microVMs or user-space kernels.
Sandboxing compared with related controls
An agent sandbox limits what is technically possible, whereas agent permissions and human-in-the-loop review limit what is authorized or approved. These controls complement one another and are not substitutes.
| Control | Question it answers | Enforced by |
|---|---|---|
| Agent sandbox | What can the agent physically reach | Operating system or hypervisor |
| Agent permissions | Which tools and actions are allowed | Agent harness policy |
| Human-in-the-loop | Should this specific action proceed | Human approval step |
| Agent observability | What did the agent actually do | Logs, traces and trajectories |
| Agent identity | On whose behalf is the agent acting | Credentials and access management |
Mature deployments apply defense in depth: the harness asks for approval on risky tools, the sandbox blocks access outside the workspace, and observability records each step so that incidents can be reconstructed.
Designing a sandbox for an agent
A well-designed agent sandbox starts from deny by default and grants only the access a task demonstrably needs. The following practices reflect common engineering guidance for coding and browsing agents.
- Mount only the project workspace as writable and keep system directories read-only.
- Route outbound traffic through a proxy with a domain allowlist, for example package registries and the source code host.
- Provide short-lived, narrowly scoped tokens rather than personal credentials or long-lived API keys.
- Set hard limits on run time, memory and disk to stop runaway loops and resource exhaustion.
- Snapshot or checkpoint state so that a failed run can be discarded without affecting the host.
- Log every command and network request for audit and agent evaluation.
Local sandboxes for developer machines, such as those built on Linux namespaces with seccomp or on macOS sandbox profiles, keep latency low and let the agent work on real files. Hosted platforms instead run each session in a remote microVM, which isolates tenants from one another at the cost of copying the workspace.
Risks a sandbox does not remove
An agent sandbox reduces the blast radius of a compromised agent, but it does not make the agent trustworthy. Several risks remain and must be addressed by other controls.
| Residual risk | Why the sandbox misses it | Mitigation |
|---|---|---|
| Data exfiltration through allowed hosts | Permitted domains can receive stolen data | Narrow allowlists, content inspection |
| Damage inside the workspace | The agent may delete or corrupt project files | Version control, checkpoints |
| Misuse of granted tokens | Valid credentials work as intended | Least privilege, approval for sensitive calls |
| Sandbox escape | Kernel or hypervisor flaws exist | Patching, stronger isolation tier |
| Over-permissive configuration | Convenience settings widen access | Reviewed policies, periodic audits |
The most common mistake is granting broad network access for convenience, which turns a contained agent into one that can send secrets anywhere. A second mistake is mounting the home directory, which exposes SSH keys, browser profiles and cloud credentials to the agent.
Put simply
An agent sandbox is a closed workroom for an AI helper. The helper can use tools, write code and run programs inside the room. It cannot wander into the rest of the computer or the network without permission.
Think of a lab with a glove box. Scientists handle risky materials through sealed gloves, so a spill stays inside. The key takeaway is that a sandbox limits the harm of mistakes. It does not make the helper smarter. It simply keeps errors and tricks contained.
In practice
A software team lets a coding agent fix failing tests in a large repository overnight. Each task starts in a fresh microVM containing a copy of the repository, with outbound traffic limited to the internal package mirror and the code hosting service. The agent receives a token that can only open pull requests on that one repository, and every session ends after 60 minutes.
One night, a dependency’s README contains hidden text instructing the agent to upload environment variables to an external server. The agent attempts the request, but the proxy blocks the unknown domain and logs the attempt. The team reviews the trace the next morning, removes the dependency, and the incident causes no credential leak and no damage outside the disposable environment.