[DOCS] Missing documentation for `sandbox.failIfUnavailable` setting

Documentation Type

Missing documentation

Documentation Location

https://code.claude.com/docs/en/settings
https://code.claude.com/docs/en/sandboxing

---

Section/Topic

The sandbox settings reference table in the Settings page (under the sandbox configuration section) and the Sandboxing page's "Configure sandboxing" section. Neither page documents the sandbox.failIfUnavailable setting introduced in v2.1.83.

---

Current Documentation

The Settings page (/docs/en/settings) includes a sandbox configuration table with these keys:

| Key | Description |
|---|---|
| enabled | Enable bash sandboxing. Default: false |
| autoAllowBashIfSandboxed | Auto-approve bash commands when sandboxed. Default: true |
| excludedCommands | Commands that should run outside of the sandbox |
| allowUnsandboxedCommands | Allow commands to run outside the sandbox via dangerouslyDisableSandbox. Default: true |
| filesystem.allowWrite | Additional paths where sandboxed commands can write |
| filesystem.denyWrite | Paths where sandboxed commands cannot write |
| filesystem.denyRead | Paths where sandboxed commands cannot read |
| filesystem.allowRead | Paths to re-allow reading within denyRead regions |
| filesystem.allowManagedReadPathsOnly | (Managed only) Restrict allowRead to managed settings only |
| network.allowUnixSockets | Unix socket paths accessible in sandbox |
| network.allowAllUnixSockets | Allow all Unix socket connections. Default: false |
| network.allowLocalBinding | Allow binding to localhost ports (macOS only). Default: false |
| network.allowedDomains | Domains to allow for outbound traffic |
| network.allowManagedDomainsOnly | (Managed only) Restrict allowed domains to managed settings only |
| network.httpProxyPort | HTTP proxy port for custom proxy |
| network.socksProxyPort | SOCKS5 proxy port for custom proxy |
| enableWeakerNestedSandbox | Weaker sandbox for unprivileged Docker environments |
| enableWeakerNetworkIsolation | Allow access to system TLS trust service (macOS only) |

The Sandboxing page (/docs/en/sandboxing) describes the unsandboxed fallback behavior in a note:

Claude Code includes an intentional escape hatch mechanism that allows commands to run outside the sandbox when necessary. When a command fails due to sandbox restrictions... Claude is prompted to analyze the failure and may retry the command with the dangerouslyDisableSandbox parameter.

Neither page mentions sandbox.failIfUnavailable.

---

What's Wrong or Missing?

The sandbox.failIfUnavailable setting introduced in v2.1.83 is not documented anywhere. This setting controls what happens when sandboxing is enabled but the sandbox cannot start: with failIfUnavailable set to true, Claude Code exits with an error rather than silently falling back to running unsandboxed.

This is a security-relevant setting. Users and enterprise administrators who enable sandboxing to enforce isolation boundaries need to know that by default, a failed sandbox start causes Claude Code to run unsandboxed (the existing behavior), and that failIfUnavailable: true provides a strict-failure mode to prevent that silent downgrade. Without this documentation:

• Users cannot discover the setting exists
• Security-conscious operators have no way to enforce "sandbox or abort" policies
• The settings reference table is incomplete, making it inconsistent with the actual available configuration surface

---

Suggested Improvement

Add failIfUnavailable to the sandbox settings table in the Settings page:

| Key | Description | Example |
|---|---|---|
| failIfUnavailable | When true, exit with an error if sandboxing is enabled but cannot start, instead of running unsandboxed. Useful for strict security policies where silent sandbox bypass is unacceptable. Default: false | true |

On the Sandboxing page, in the "Configure sandboxing" section, add a note alongside the existing allowUnsandboxedCommands documentation:

To prevent Claude Code from running at all when the sandbox fails to start, set sandbox.failIfUnavailable to true. When enabled, Claude Code exits with an error if the sandbox cannot start, rather than falling back to unsandboxed execution. This complements allowUnsandboxedCommands: false, which prevents individual commands from escaping the sandbox, by also enforcing that the sandbox itself must be operational at startup.

Also update the configuration example JSON in the Settings page to illustrate the setting:

{
"sandbox": {
"enabled": true,
"failIfUnavailable": true
}
}

---

Impact

High

Additional Context

Affected Pages:

| Page | URL | Issue |
|---|---|---|
| Settings | https://code.claude.com/docs/en/settings | sandbox.failIfUnavailable absent from sandbox settings table |
| Sandboxing | https://code.claude.com/docs/en/sandboxing | No mention of failIfUnavailable in configuration or security sections |

Total scope: 2 pages

Source: Changelog v2.1.83

Exact changelog entry:

Added sandbox.failIfUnavailable setting to exit with an error when sandbox is enabled but cannot start, instead of running unsandboxed