# 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.

*Tags: ai, agents, security, permissions*

---


> [!info] Quick Definition
> **Sandboxing** is the isolation the operating system enforces on the commands an agent runs, limiting which files and network domains they can reach. **Permissions** are the rules that decide which tools an agent may use and which need human approval. They are separate layers, and they complement each other.


## 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 [[action-approval|approving an agent's actions]] and [[agent-permissions-ux|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), `WebFetch` and `WebSearch` do 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.autoAllowBashIfSandboxed` to `false`.

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|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.com` can 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 `PATH` or 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|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 `find` with 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.

## Sources

- [Sandboxing (Claude Code documentation)](https://code.claude.com/docs/en/sandboxing)
- [Configure permissions (Claude Code documentation)](https://code.claude.com/docs/en/permissions)
- [Permission modes (Claude Code documentation)](https://code.claude.com/docs/en/permission-modes.md)
- [Run parallel sessions with worktrees (Claude Code documentation)](https://code.claude.com/docs/en/worktrees.md)
- [Agent approvals & security (Codex, OpenAI documentation)](https://developers.openai.com/codex/agent-approvals-security)
- [Run modes (Cursor documentation)](https://cursor.com/docs/agent/security/run-modes)


---

Source: https://www.fernandoux.com/en/wiki/ai/sandboxing-and-permissions/