Claude Code Sandboxing: Enable the Bash Sandbox Step by Step

Give the sandbox something to enforce with

On Linux the boundary is real operating-system machinery: bubblewrap jails the process and socat carries traffic out to the proxy. macOS already ships the equivalent, so skip this section there.

1. 1

   Install bubblewrap and socat

   In the Linux distro you will actually run Claude Code in, install the two packages the sandbox needs: sudo apt-get install bubblewrap socat. apt resolves three here - bubblewrap, libwrap0 and socat - and reports 472 kB of archives. On macOS, skip the whole step: Seatbelt is part of the operating system.

   

2. 2

   Install Claude Code with the native installer

   With the dependencies in place, install the CLI: curl -fsSL https://claude.ai/install.sh | bash. The recording uses the native installer rather than npm; the accompanying notes say both routes work, and that sandboxing needs a Claude Code build new enough to ship it.

   

3. 3

   Add the Anthropic sandbox runtime

   The same guide adds one more package: npm install -g @anthropic-ai/sandbox-runtime. That is the runtime Claude Code wraps its Bash tool in, and it is usable on its own around other tools - an MCP server you want fenced to one folder, for example. The frame catches the moment before the project settings exist: .claude/settings.json is open and empty.

   

Describe the boundaries in settings.json

One sandbox object, two sub-objects - filesystem and network. Everything the session does later follows from what you write here.

1. 4

   Write the sandbox object

   Create .claude/settings.json inside the project and add a sandbox key. The recording sets enabled: true and failIfUnavailable: true, so a session that cannot get a sandbox refuses to start instead of quietly running unsandboxed. Under filesystem it puts denyRead: ["../"] and allowRead: ["."] - the project is readable, its parent directory is not. The values on the two lines above (allowUnsandboxedCommands, autoAllowBashIfSandboxed) sit under the editor minimap in this frame, so they are not quoted here.

   

2. 5

   List the domains you actually need

   The network sub-object is where the approval behaviour comes from. The recording leaves allowUnixSockets empty, sets allowAllUnixSockets: false and allowLocalBinding: false, and puts exactly one entry in allowedDomains: example.com. Traffic goes out through a proxy outside the jail, and a domain that is not on the list is not silently dropped - it is asked about.

   

3. 6

   Know which way the defaults run

   The guide's notes spell out the starting position: reads are allowed anywhere in the machine by default, writes only inside the project, minus a few critical files Claude Code needs to run at all. denyRead and allowRead exist to narrow the first of those, because that is the half that touches your SSH keys and .env files. The same notes recommend "allowUnsandboxedCommands": false if you want the escape hatch shut.

   

Start a session and check that it is sandboxed

Claude Code says so on the first screen, and the first command you try proves it.

1. 7

   Launch claude and read the banner

   Start Claude Code in the project. The version line here is v2.1.118, and directly under the welcome box the session prints Your bash commands will be sandboxed. Disable with /sandbox. That line is the check: no banner, no sandbox. Go back to the settings file and the runtime install before you trust anything.

   

2. 8

   Prove the file boundary from bash mode

   Type ! cat ../hello.txt to run a command straight from the prompt. The file exists - it is open in the editor above and listed in the explorer at the home level - but the sandboxed shell answers cat: ../hello.txt: No such file or directory. That is denyRead: ["../"] working: the path is not hidden behind a dialog, it is simply not there.

   

3. 9

   Fetch the domain that is on the list

   ! curl "https://example.com" comes back with 528 bytes and the Example Domain HTML, because that host is the single entry in allowedDomains. The next line, ! curl "https://github.com", is still showing Running... - the proxy has no rule for github.com, so the request waits instead of failing.

   

4. 10

   Reopen the session to confirm it stuck

   The guide's step 8 is the check you should run after any settings change: close claude, start it again, and look for the message saying the session is sandboxed. Settings are read at launch, so an edit that never produced the banner is an edit that never loaded.

   

The network prompt, and what happens after it

This is the approval that replaced the per-command dialog: one question per domain, answered by the proxy rather than by reflex.

1. 11

   Answer the network prompt

   The wait ends in a dialog that is different in kind from per-command approvals: Network request outside of sandbox, the destination on its own Host: line, and the question Do you want to allow this connection? Three options follow - Yes, Yes, and don't ask again for github.com, and No, and tell Claude what to do differently (esc). The middle one is what changes your week: approve a host once and every later request to it is quiet.

   

2. 12

   See what a declined request costs

   The frame after the prompt shows a transfer table of zero-byte rows and curl: (56) CONNECT tunnel failed, response 403: the proxy refused to open the tunnel, so the command ran and got nothing. The video does not show which option was pressed, so read this as the refused outcome rather than a transcript of the click.

   

3. 13

   Remember what the sandbox does not cover

   The caveats section is worth quoting, because it is the most common misunderstanding: Sandboxing only applies to how Claude uses the Bash tool. The built-in Read, Edit and Write tools are configured through Claude Code's Permissions instead. The sandbox is not a box around the whole session - it is a floor under shell commands, and the file tools still need rules of their own.

   

Keep going