The sandbox, in plain words

What a sandbox is

A sandbox is a fenced-off space where a program can run without reaching everything else on the computer.

Think of a sandpit in a park with a fence around it. Children can dig whatever they like inside, and the fence keeps them away from the road. Nobody has to watch every shovel.

On a computer, the fence is built by the operating system: the base software that runs the computer and decides which program may touch which file, such as macOS, Linux or Windows. Because the operating system builds the wall, the wall holds whatever command the agent chose to run.

The problem it solves

Claude Code is Anthropic’s AI coding agent. It does its work partly by running commands in a shell, the program that reads typed commands and runs them (see What a terminal is). The docs say it can run any command you could run, so those commands can reach what you can reach.

Many commands start other programs. A program started by another program is a subprocess, and it can open files by itself.

That matters for secrets. You can add a deny rule, a line in a settings file that tells Claude Code never to allow one action. A settings file is a small text file where Claude Code reads its options. The rule Read(./.env) tells the agent never to read your .env file, the file where many apps keep their keys (see .env files and API keys).

The permissions docs say what that rule checks: the agent’s own file tools, and file commands it recognises in the shell, such as cat. They also say what it doesn’t check: a command that reads files without naming them, such as grep -r, which searches every file in a folder, or a script that opens files itself. So a one-line script that prints .env gets the key anyway, because the command that started it never named .env.

What the Claude Code sandbox does

Turning it on

The sandbox is off by default. To turn it on, type /sandbox in a Claude Code session. A panel opens, and on its Mode tab you choose one of two modes:

• Auto-allow: commands that run inside the wall run without asking you first.
• Regular permissions: you still get the normal question before each command, even inside the wall.

The wall is the same in both modes. Only the asking differs. Auto-allow is picked for you by default. Switch to regular permissions if you want to keep approving each command.

The panel saves your choice for the current project only. To turn the sandbox on everywhere, set sandbox.enabled to true in your personal settings file, ~/.claude/settings.json in your home folder.

What it covers

The wall goes around the shell commands the agent runs and every program those commands start. It limits two things:

• Files: by default, commands can change files only in your project folder and a temporary folder. They can still read most of the computer unless you block a path.
• Network: commands have no direct route to the internet. Every connection goes through a checkpoint on your machine that compares the website’s name with your list.

Your deny rule goes onto the wall

The sandbox docs say your Read deny rules are added to the wall too. In practice, your Read(./.env) rule now also blocks programs inside the wall, including the one-line script. Here is the rule as it sits in your project’s .claude/settings.json:

{
  "permissions": {
    "deny": ["Read(./.env)"]
  }
}

• permissions holds the rules about what the agent may do.
• deny is the list of things it may never do.
• Read(./.env) means: never read the .env file in this project folder.

A list of allowed websites

An allowlist is a list of the only things allowed. Everything else is refused. By default the sandbox’s list starts empty. When a command inside the wall tries a website that isn’t on it, what happens depends on how Claude Code asks you for permission. In the usual setting, Manual mode, you get a question. In auto mode, a different setting from the sandbox’s Auto-allow, a second AI model reviews the agent’s actions instead of you. There, an unlisted site is refused unless that model approves it for that one command. Sites you’ve told the agent to always allow count as listed.

To refuse every unlisted website with no question at all, turn on strictAllowlist in your personal settings file. The docs say it has no effect in a project’s settings file.

{
  "sandbox": {
    "network": {
      "strictAllowlist": true,
      "allowedDomains": ["registry.npmjs.org"]
    }
  }
}

• sandbox holds the sandbox options.
• network holds the internet rules.
• strictAllowlist: true means: refuse any website not on the list, instead of asking.
• allowedDomains is the list. Here it holds one website, a place many JavaScript tools download from. Put the sites you trust there.

Where it runs

The sandbox runs on macOS, Linux and WSL2. WSL2 is the Windows Subsystem for Linux, version 2: Linux running inside Windows. On plain Windows, Claude Code runs commands with no sandbox. To use it on a Windows computer, run Claude Code inside WSL2. Microsoft’s Install WSL page shows how.

What it does not cover

The sandbox docs are clear that the wall surrounds shell commands only. These stay outside:

• The agent’s own built-in tools. When Claude Code reads or edits a file with its own file tools, it isn’t using the shell, so the wall never sees it. Its web tools also sit outside. Your deny rule is what stops the file tools.
• MCP servers, add-ons that give the agent extra tools (see What an MCP server is). Local ones run with your full access, and so do hooks, small programs Claude Code runs at set moments.
• Environment variables. An environment variable is a named value your computer hands to every program it starts, and some keys live there instead of in a file. By default, commands inside the wall still receive them. The docs offer a fix (see the box below).
• The retry outside the wall. When the wall blocks a command, the agent can ask to run it again outside the wall. If you say yes, it runs with no wall. To turn this retry off, turn on Strict sandbox mode on the /sandbox panel’s Overrides tab.
• A sandbox that can’t start. If a needed part is missing or your system isn’t supported, Claude Code runs commands without the wall, by default. A setting can make it stop at startup instead (see the box below).

For the curious: the settings behind the gaps

These go in your personal settings file, ~/.claude/settings.json. The docs say Claude Code ignores credentials entries in a project’s settings files.

{
  "sandbox": {
    "credentials": {
      "envVars": [{ "name": "MY_KEY", "mode": "deny" }]
    },
    "allowUnsandboxedCommands": false,
    "failIfUnavailable": true
  }
}

• envVars with "mode": "deny" removes the variable MY_KEY before each sandboxed command runs. Put your key’s real name there.
• allowUnsandboxedCommands: false is Strict sandbox mode: no retry outside the wall.
• failIfUnavailable: true makes Claude Code stop at startup if the sandbox can’t start.

Caution

The docs say the sandbox reduces risk but isn’t a complete wall. Treat it as one layer, not the only one.

The two limits together: the wall holds what the shell starts; the deny rule stops the agent's own file tools.Swipe sideways to see the whole diagram →

Two limits, together

• The deny rule stops the agent’s own hands: its file tools and the simple file commands it types.
• The sandbox fences in everything the shell starts, apart from the gaps above: scripts, test runs, builds, and any program they open.

Each one covers what the other can’t see. Set up both before you give the agent a job.