Sandboxing and agent permissions: which limits to set and what each one does
A sandbox limits which files and domains an agent's commands can reach; permissions decide which tools it may use. How the two layers work together in practice.
What does each layer control?
Permissions act before a tool runs. They decide whether the agent can read a file, edit code, fetch a web page or run a command, and whether it needs your approval to do so. They are evaluated against the action the agent wants to take.
The sandbox acts while the command runs. It limits it at the operating system level: which directories it can write to, which domains it can contact, which environment variables it inherits. It applies to shell commands and the processes they start.
The practical difference: a permission says “you may run npm test”. The sandbox says “and while it runs, it can only write to this folder and has no internet access except to these domains”.
This article covers the technical limits. For the screens where a person decides, read approving an agent’s actions and permission UX for agents.
Why do you need both?
Because each fails in a different way. Permissions depend on the rule being right and on the person approving well. Claude Code’s documentation warns that a Bash rule is matched against the command text the agent writes, not against the program in every form it can be invoked, so a block rule is not a security boundary around that program. The sandbox, by contrast, protects you even when a command does something its name does not suggest, because the restriction sits on the process.
Claude Code puts it this way: the two layers are complementary, and sandbox restrictions still apply even if a prompt injection (malicious text hidden in something the agent reads) fools the model.
What does Claude Code’s sandbox actually isolate?
According to the documentation, the sandbox is off by default and is turned on with /sandbox or with sandbox.enabled in settings. It runs on macOS, Linux and WSL2; on native Windows, commands run unsandboxed. When it is on:
| Access | Default behavior |
|---|---|
| Writes | The working directory, the per-user temp directory and any directories you added |
| Reads | Most of the machine, including credential files such as ~/.ssh and ~/.aws/credentials |
| Network | No direct route out; everything goes through a proxy that only passes allowed domains, and the list starts empty |
| Environment variables | Inherited from Claude Code, including any secrets in its environment |
Three details surprise people:
- Default read access is broad. Closing it takes configuration (for example,
denyRead). - The file tools (read, edit, write),
WebFetchandWebSearchdo not go through the sandbox: they follow permissions. Hooks and local MCP servers also run outside it. - With the sandbox on, the Bash commands that stay inside it run without asking (auto-allow mode). To keep them going through the normal permission flow, set
sandbox.autoAllowBashIfSandboxedtofalse.
Also, if a command fails on a restriction, Claude may retry it without the sandbox using the dangerouslyDisableSandbox parameter; who approves that retry depends on the permission mode. You can block it with allowUnsandboxedCommands: false.
What permission modes exist?
| Mode (settings value) | What it does |
|---|---|
Manual (default) | Asks for permission the first time each tool is used |
Accept edits (acceptEdits) | Accepts file edits and common commands such as mkdir, mv or cp inside the working directory |
Plan (plan) | Explores and reads, but does not edit your source until you approve the plan |
Auto (auto) | A classifier reviews actions instead of the person; the documentation says it reduces prompts but does not guarantee safety |
Don’t ask (dontAsk) | Denies everything that would prompt; meant for CI and locked-down scripts |
Bypass permissions (bypassPermissions) | Turns off prompts and safety checks, except for a few actions no mode approves |
The documentation warns that bypass mode should be used only in isolated environments such as containers or virtual machines, and that it offers no protection against prompt injection. Plan mode has its own article: plan mode.
How do Codex and Cursor handle it?
Both also separate the two layers, under different names.
Codex (OpenAI) has three sandbox modes, read-only, workspace-write and danger-full-access, and a separate approval policy (on-request, never or a granular policy). In version-controlled folders the recommended setting is workspace-write with on-request; in folders without version control, read-only. Network access is off by default. The --dangerously-bypass-approvals-and-sandbox flag (alias --yolo) removes both sandbox and approvals, and the documentation itself marks it as not recommended.
Cursor runs terminal commands in a sandbox: it can write inside the workspace, protects paths such as .git/hooks and .cursorignore, and blocks the network by default except what sandbox.json allows plus a list of package-manager domains. Its run modes are called Auto-review, Allowlist and Run Everything. Its documentation warns that “Auto-review is not a security boundary”: the classifier can allow calls you would have blocked, or the reverse.
Names change between tools and versions, so check the current documentation before configuring anything.
When should you NOT rely on the sandbox alone?
- When you allow broad domains. The documentation warns that allowing domains such as
github.comcan create paths for data exfiltration, because the proxy decides from the domain name without inspecting encrypted traffic. - When you allow Unix sockets. Allowing the Docker socket (
/var/run/docker.sock), for example, effectively grants access to the host system. - When you grant write access to risky paths, such as directories with executables on the
PATHor shell configuration files (.bashrc,.zshrc). - When the sandbox is off, or on native Windows, and the agent runs on your machine with your credentials in plain view.
- When you also need to isolate hooks and MCP servers: the documentation then suggests running all of Claude Code inside its sandbox runtime or a dev container.
To keep several agents’ work in separate copies of the repository, see git worktrees for agents. Worktrees separate files; they do not replace the sandbox.
Example
Illustrative example: an agent is going to debug a failing test. You turn the sandbox on, allow it to run npm test without asking, and add only the package registry to the allowed domains. Its writes are limited to the project folder. Because default read access is broad, you add ~/.ssh to denyRead in the sandbox settings. If the test needs a cloud database, you add that domain to the allowed domains, not to the “run without asking” list. Result: the agent moves forward without asking about what is safe, and every exception is written in a file another person can review.
Common mistakes
- Treating the sandbox as just another permission. It is an operating system barrier with a different scope.
- Believing a command block rule is a security barrier. It only covers the way the agent usually writes the command.
- Approving “don’t ask again” for broad commands such as
findwith delete actions. - Allowing wildcard domains without thinking about what can be sent to them.
- Using bypass mode on your work machine.
- Believing the agent cannot read your credentials because it never writes them. Default read access is broad.