Claude Code adds a sandbox setting for tools that need user namespaces

On Linux and WSL2, commands inside the Claude Code sandbox can't create user namespaces. Tools that depend on them fail. Version 2.1.305 adds a setting to allow it, and the docs are blunt about the cost.

What fails today

The sandboxing docs list the symptoms:

• Chromium exits with No usable sandbox!
• unshare -U true prints unshare: unshare failed: Operation not permitted
• Rootless Podman prints cannot clone: Operation not permitted, or stops earlier with read-only file system on one of its own folders

The setting

Set sandbox.allowNestedUserNamespaces to true in ~/.claude/settings.json:

{
  "sandbox": {
    "allowNestedUserNamespaces": true
  }
}

The 2.1.305 changelog describes it as letting sandboxed commands on Linux create user namespaces, for Chromium and rootless podman. It also says the setting "lets them get around the sandbox's file protections."

The docs say to put it in user settings, not the project's .claude/settings.json. The settings index lists its scope as user or managed, and the managed-settings section says a repository can't turn it on. It requires Claude Code v2.1.305 or later.

What you give up

Both the sandbox and settings pages warn that this setting turns off a security boundary. Code from a sandboxed command can end up running outside the sandbox. Don't rely on protected paths or sandbox.credentials.files entries to stop a malicious command. In auto-allow mode, such a command can run without a permission prompt.

The docs suggest checking with your security team first if you have one.

It doesn't fix everything

• Podman and Buildah. The docs say this setting alone isn't enough for rootless Podman or Buildah, because the sandbox stops them in other ways too. For those, the docs suggest a sandbox.excludedCommands pattern such as podman *. Matching commands run outside the sandbox with your full access.
• unshare. A command that begins with unshare stays sandboxed whatever excludedCommands pattern you list, because unshare can start any other program.
• Chromium and Electron. The alternative to this setting is starting the browser with --no-sandbox. The Claude Code sandbox stays as it is, but the browser runs web content without its own sandbox. The new setting keeps the browser's own sandbox, at the price above.
• Scrubbed sessions. With CLAUDE_CODE_SUBPROCESS_ENV_SCRUB set to 1, every command runs sandboxed and the docs say these settings have no effect. Use --no-sandbox for the browser and run other tools yourself outside Claude Code.

What this means

If a test suite drives headless Chromium inside the sandbox, you now have a choice between disabling the browser's sandbox and weakening Claude Code's. Neither is free. Pick on purpose, and keep the setting out of repository files. The Claude Code sheet tracks the current sandbox settings.