Updated: Claude Code Sandbox

Changes

By default, Claude Code runs commands through its `Bash` tool as your user.
While this works, you will likely encounter lots of permission dialogs. It's also debatable if your coding agent should have the same permissions as yourself.
Claude Code can run its code in a sandbox. This card explains how to configure it.
## What the sandbox does and doesn't do
A sandbox is not a silver bullet. Commands are still executed.
However, the sandbox limits file system access and network traffic.
The default configuration in Claude Code is fairly relaxed. We have a separate card on restricting it.
### What it does
- Outbound network traffic is blocked by default and requires explicit approval. You can allowlist hosts.
- It restricts read and write file system access.
  - By default, anything inside your home directory is readable.
  - By default, writing is allowed only to the project directory.
- It provides a temporary file location where Claude Code can write files to without touching your project directory.
### What it does NOT do
- It is NOT a security boundary against malicious code. Treat it as guardrails, not a jail.
- It does NOT restrict `Read` and `Write` tools. Those follow their own rules, but do respect the sandbox's `filesystem` settings. See our [card on restricting Claude Code's configuration](/makandra/626588).
## How to enable the sandbox
In Claude Code, simply prompt `/sandbox` to open the sandbox configuration.
There are 3 modes.
1. Sandbox BashTool, with auto-allow
2. Sandbox BashTool, with regular permissions
3. No Sandbox
The "auto-allow" mode runs commands in the sandbox without confirmation. If a command fails in the sandbox, Claude Code will run it unsandboxed.
Unsandboxed executions will use your regular permission settings, i.e. commands that you allowlisted will run without confirmation, any others will prompt you to confirm.
Enabling the sandbox will write this to your project's `.claude/settings.local.json` file:
```json
{
+  "permissions": {
+    "deny": [
+      "Edit(~/.claude/settings.json)",
+    ]
+  },
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true
  }
}
```
You may want to also put this into your `~/.claude/settings.json` to enable the sandbox globally.
Tip: Test the sandbox on a per-project basis first before committing to it globally.
### Linux packages
On Linux, you _may_ need to install two packages first.
Claude Code will tell you if that is necessary.
```
sudo apt-get install bubblewrap socat
```
* `bubblewrap` is the tool which sandboxes file system access.
* `socat` is used to sandbox network traffic.
### Strict sandbox mode
In the `/sandbox` dialog, switch to the "Overrides" menu to enable "Strict sandbox mode". This will prevent running commands unsandboxed, unless they are explicitly allowlisted.
Effectively, this will add `"allowUnsandboxedCommands": false` to your configuration's `sandbox` values.
> [IMPORTANT]
> I strongly suggest you enable strict sandbox mode.
> Just switch it on and see if it works for you. It likely will.
The sandbox has one caveat:
When Claude Code detects a Rails application, the `config` directory becomes read-only for Claude's `BashTool` by default and there is no way to change this. Claude may then run into issues when e.g. rebasing or merging commits.
Our [default sandbox configuration](/makandra/626588-restricting-claude-codes-sandbox-configuration) contains a solution for that.
## Database access from the sandbox
You likely want Claude Code to be able to access your database from the sandbox.
This is a bit tricky because it cannot access `localhost` listeners, apparently.
Our [default database configuration](https://makandracards.com/makandra-orga/6127-alle-schritte-um-einen-neuen-linux-computer-zu-installieren#section-dev-postgresql) does allow PostgreSQL access through a Unix Socket.
Hence, you need to do two things:
* Have a `database.yml` without `host` entry inside the sandbox.
* Allow socket access in the sandbox if you want your database to be reachable from the sandbox,
First, adjust your `database.yml` to look roughly like this:
```yaml
default: &default
  adapter: postgresql
  encoding: unicode
  pool: <%= ENV.fetch('RAILS_MAX_THREADS') { 5 } %>
development:
  <<: *default
  <%= 'host: localhost' unless ENV['SANDBOX_RUNTIME'] %>
  database: your_app_development
test:
  <<: *default
  database: your_app_test<%= ENV['TEST_ENV_NUMBER'] %>
```
Then, open your project's `.claude/settings.local.json` or your global `~/.claude/settings.json` and add a `network` key with `{ "allowAllUnixSockets": true }`:
```json
{
  // ...
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "network": {
      "allowAllUnixSockets": true
    }
  },
  // ...
}
```
Note that `socat` cannot limit _which_ sockets are accessible. This means that all sockets on your system are available from the sandbox.
We consider the risk acceptable; without it, your Claude Code cannot run tests in the sandbox and either can't perform its job properly or has to run unsandboxed more often.