Claude Code Sandbox

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.

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:

{
  "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.

I suggest you try enabling Strict sandbox mode and see if it works for you.

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 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:

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 }:

{
  // ...
  "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.