Chromium Says No usable sandbox! Inside Claude Code's Sandbox: What --no-sandbox, excludedCommands and allowNestedUserNamespaces Each Give Up

Running Chromium, Playwright or rootless Podman inside Claude Code's Sandbox on Linux or WSL2 often ends in No usable sandbox!. The official sandbox page gives three ways out, and each gives up something different. This article puts them side by side. The facts come from the official sandbox page and changelog; I did not test the three approaches on my own machine, so the trade-offs are the docs' statements plus my own tidying.

The problem

The docs say that on Linux and WSL2 commands in the sandbox cannot create user namespaces by default, so tools that rely on them fail. Listed symptoms: Chromium exits with No usable sandbox!; unshare -U true prints 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.

Option 1: start the browser with --no-sandbox

For Chromium or Electron, pass --no-sandbox. Claude Code's sandbox stays as it is; the cost is that the browser runs web content without its own sandbox. If the tests only open local pages you control, that cost is small; if they open external URLs, the risk sits at the browser layer. That is my judgment; the docs only say it gives up the browser's own isolation.

Option 2: excludedCommands, taking the whole command out of the sandbox

Put a command pattern in sandbox.excludedCommands and matching commands run outside the sandbox with your full access:

{
  "sandbox": {
    "enabled": true,
    "excludedCommands": ["npx playwright test *"]
  }
}

The docs list several rules that catch people:

• End the pattern with *; a pattern with no wildcard is an exact match, so docker matches only docker with no arguments.
• Every command in the call must match: npm ci && docker compose build stays sandboxed unless another entry covers npm ci.
• Matching is on the text of the call: a script or make target that calls a tool internally does not match, and neither does /usr/local/bin/docker. For a browser, match the test command, not the browser.
• A redirect to a file, a cd or $(...) keeps the whole call sandboxed.

The docs add a warning: Claude can edit a script in your working directory before running it, and an excluded command has your full access, so excluding a command that runs a script also lets that script's contents out of the sandbox. Excluded commands still go through the normal permission flow; in auto mode the classifier reviews them; in bypassPermissions mode they run without a prompt unless an ask rule matches.

Option 3: allowNestedUserNamespaces

Added in v2.1.305:

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

The docs say to set it in ~/.claude/settings.json, not the project's .claude/settings.json, and that a repository cannot turn it on. The benefit is that Chromium or Electron keeps its own sandbox and nested bubblewrap or unshare can run. The cost is stated in a warning box: you turn off a security boundary, code from a sandboxed command can end up running outside the sandbox, you should not rely on any sandbox restriction, including protected paths and credentials.files, to stop a malicious command, and in auto-allow mode that command can run without a prompt. The page also says a command beginning with unshare stays sandboxed whatever excludedCommands says, and that this setting alone is not enough for rootless Podman or Buildah, which the sandbox stops in other ways too.

How to choose

• Only Chromium or Electron tests, on content you own: start with option 1, the smallest scope.
• Podman, Buildah, or scripts that run a browser: the docs point to excludedCommands and expect you to accept that those commands have full access.
• You want the browser's own sandbox kept, or need nested bubblewrap: option 3, with the warning above accepted, and the docs suggest checking with your security team first if you have one.
• If the session sets CLAUDE_CODE_SUBPROCESS_ENV_SCRUB=1: the docs say every command then runs sandboxed and none of these settings have an effect; use --no-sandbox for Chromium or Electron and run other tools yourself outside Claude Code.

The ordering (smallest scope first, then exclusion, namespaces last) is my recommendation based on how the docs describe each option, not on a comparison test I ran.