What is an agent sandbox?
An agent sandbox is an isolated environment in which an AI agent's commands run, so a mistake or a prompt injection can only touch what the sandbox allows. It can be a per-command OS boundary, like Claude Code's or Codex's, or a disposable cloud VM from E2B or Daytona where the whole agent lives.
Part of Glossary: the terms behind MCP, coding agents and shared pages, defined plainly.
The agent wants to run a shell command. The harness starts it inside a boundary the operating system enforces: Seatbelt on macOS, bubblewrap on Linux.
Inside, writes stay within the project and a temp directory, reads of files such as ~/.ssh are denied, and network goes through a proxy with an allowlist.
A command that hits the wall fails. The agent can ask to retry it unsandboxed, and that request is where your approval comes back in.
Cloud sandboxes move the whole agent instead: E2B and Daytona start an isolated Linux machine on demand, the agent works there, and you discard it afterwards.
A sandbox limits what a command can touch. It doesn't decide whether the command runs; that stays with permission modes and with you.
Source: Claude Code docs: sandboxing
Agent sandbox versus permission prompts
A permission prompt asks you before something runs. A sandbox limits what it can reach once it does. Claude Code's docs put it plainly: the sandbox is not a permission mode. The distinction matters because the two fail differently. Prompts fail when you get tired and press Enter, or when an instruction hidden in a web page talks the agent into a command that looks harmless. A sandbox doesn't get tired. It also doesn't care why a command wants to read ~/.aws/credentials; the read is denied either way.
The two also compose. Claude Code's auto-allow setting runs sandboxed commands without prompting while keeping prompts for anything that escapes the box. Codex's lower-risk preset is --sandbox workspace-write --ask-for-approval on-request: work freely inside the workspace, ask when you need to go outside it. Cursor's Auto-review runs shell commands in a sandbox when it can and sends the rest to a classifier.
Example: a build that needs the network
Your agent runs npm install inside Claude Code's sandbox. The install can write node_modules because it's under the working directory. Then it tries to fetch packages and fails, because the sandbox routes connections through a local proxy whose allowed-domains list starts empty. The agent reports the failure, and you add the registry host. From then on the install works, and a dependency's postinstall script that tries to phone a different host still can't.
That first failure is the feature. It surfaces every outbound connection once, which is how you learn what your tooling actually talks to.
When to use which kind
Use the OS-level sandbox for day-to-day work on your own machine. It's on your files, it's fast, and the agent can still use your editor, your git and your MCP servers. Know its edges: on Claude Code, file tools, hooks and MCP servers run outside it, docker is incompatible with it, and anything that isn't TCP can't leave.
Use a cloud sandbox when the agent runs unattended or on behalf of many users. E2B describes its sandbox as an isolated Linux VM you create with Sandbox.create(), pause with its full state preserved, and run continuously for up to 24 hours on Pro or 1 hour on Hobby. Daytona gives each sandbox its own kernel, filesystem and network stack, with 1 vCPU, 1 GB of RAM and 3 GiB of disk by default, and deletes ephemeral ones when they stop. Both exist so that an agent's shell is never your shell.
Common mistakes
- Treating the sandbox as the only control. Claude Code's sandbox inherits the agent's environment variables, secrets included, unless you set it to mask or deny them. Fence the credentials too.
- Excluding commands to make them work. An excluded command runs with your full access. Add the host or path it needs instead.
- Running without checking it started. Without
failIfUnavailable, Claude Code falls back to running unsandboxed when the sandbox can't start, and native Windows never sandboxes at all. - Pairing a sandbox with no prompts and calling it safe. Codex's
danger-full-accesswithapproval_policy = "never"is full access, as the docs name it. The sandbox has to be on for the no-prompt mode to mean anything.
FAQ
- Is an agent sandbox the same as a permission mode?
- No, and the Claude Code docs say so directly. A permission mode decides whether a tool call runs at all. The sandbox restricts what a command can access once it does run. You can have either without the other; together, the sandbox lets you prompt less because the blast radius is smaller.
- Does an agent sandbox stop prompt injection?
- It contains it. A hijacked command still runs, but it can't read your SSH keys or post them to a host that isn't on the allowlist. That is the whole point: assume some instruction will slip through and make sure it can't reach anything that matters.
- What is the difference between a local agent sandbox and a cloud one like E2B?
- A local sandbox wraps each command on your own machine and lets the agent keep using your files and tools. A cloud sandbox is a separate Linux VM you create from an SDK; the agent runs there and your laptop is never in reach. Local is convenient; cloud is for agents you don't watch.
Stop sending HTMLover Slack.
Create an account in a minute, connect your coding agent, and make your first board.