#[non_exhaustive]pub struct Sandbox {Show 18 fields
pub enabled: Option<bool>,
pub auto_allow_bash_if_sandboxed: Option<bool>,
pub excluded_commands: Option<Vec<String>>,
pub allow_unsandboxed_commands: Option<bool>,
pub ignore_violations: Option<BTreeMap<String, Vec<String>>>,
pub network: Option<SandboxNetwork>,
pub filesystem: Option<SandboxFilesystem>,
pub credentials: Option<SandboxCredentials>,
pub ripgrep: Option<Ripgrep>,
pub enable_weaker_network_isolation: Option<bool>,
pub enable_weaker_nested_sandbox: Option<bool>,
pub bwrap_path: Option<String>,
pub socat_path: Option<String>,
pub fail_if_unavailable: Option<bool>,
pub enabled_platforms: Option<Vec<Platform>>,
pub allow_apple_events: Option<bool>,
pub allow_nested_user_namespaces: Option<bool>,
pub extra: Extra,
}Expand description
sandbox.
Isolate the Bash commands Claude runs from your filesystem and network with
sandboxing. Turn the sandbox on with
enabled, then narrow or widen what sandboxed commands can touch with the filesystem,
network, and credentials sub-objects.
Docs: sandbox.
Fields (Non-exhaustive)§
This struct is marked as non-exhaustive
Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.enabled: Option<bool>Turn on sandboxing for Bash commands. When
you pick a mode in the /sandbox panel, Claude Code writes this key to
.claude/settings.local.json for the current project; set it in
~/.claude/settings.json to sandbox every project.
- Values: Boolean
true: Claude Code sandboxes Bash commandsfalse: Bash commands run unsandboxed
- Default:
false - Scope: any settings file, with limits on project and local settings.
Docs: enabled.
auto_allow_bash_if_sandboxed: Option<bool>Let Claude Code run sandboxed Bash commands without a permission prompt. Commands that
can’t run in the sandbox still go through the regular permission flow, and deny rules
and content-scoped ask rules such as Bash(git push *) still apply; a bare Bash ask
rule is skipped for sandboxed commands. Set it to false to send sandboxed commands
through the regular permission flow too, which the /sandbox Mode tab calls regular
permissions mode.
- Values: Boolean
true: Claude Code runs sandboxed Bash commands without a permission prompt, except in the cases that Auto-allow mode describes;CLAUDE_CODE_SUBPROCESS_ENV_SCRUBturns auto-allow offfalse: sandboxed commands go through the regular permission flow, so your allow rules and permission mode decide. The/sandboxMode tab calls this regular permissions mode
- Default:
true - Scope: any settings file.
Docs: autoAllowBashIfSandboxed.
excluded_commands: Option<Vec<String>>Name commands that Claude Code runs outside the sandbox, such as tools that don’t work
under it. Each entry uses the same syntax as the content of a Bash(...) permission
rule: an exact
command, a prefix such as docker *, or a wildcard pattern. A pattern with no wildcard
is an exact match, so docker matches only docker with no arguments.
- Values: array of command patterns
- Default: unset, so no command is excluded
- Scope: any settings file, with limits on project and local settings.
Docs: excludedCommands.
allow_unsandboxed_commands: Option<bool>Let Claude retry a command outside the sandbox with the dangerouslyDisableSandbox
parameter after the sandbox blocks it. When it’s false, Claude Code ignores that
parameter. While the sandbox is running, commands Claude runs are then sandboxed unless
they match an
excludedCommands
entry.
- Values: Boolean
true: Claude can retry a command outside the sandbox with thedangerouslyDisableSandboxparameter after the sandbox blocks itfalse: Claude Code ignores that parameter, so while the sandbox is running, commands Claude runs are sandboxed unless they match anexcludedCommandsentry
- Default:
true - Scope: any settings file, with a limit on project and local settings.
Docs: allowUnsandboxedCommands.
ignore_violations: Option<BTreeMap<String, Vec<String>>>Silence sandbox violation reports for paths you expect a command to probe and be
refused, such as a tool that checks /etc/hosts on startup, so those denials don’t show
up as violations or in what Claude sees. The sandbox still blocks the access; only the
report is suppressed. Keys are substrings to match against the command, with *
matching every command, and values are substrings of the violation to ignore for that
command, such as a filesystem path.
- Values: object mapping a command substring to an array of violation substrings, usually paths
- Default: unset, so every violation is reported
- Scope: any settings file, with limits on project and local settings.
Docs: ignoreViolations.
network: Option<SandboxNetwork>Control which hosts, ports, and sockets sandboxed commands can reach. The sandbox routes outbound traffic through a proxy that enforces these lists; see Network isolation for how the proxy decides and when it prompts.
- Values: object with the sub-keys below
- Default: unset, so no domains are pre-allowed and your permission mode decides what happens to each new host
- Scope: any settings file.
strictAllowlist,allowManagedDomainsOnly, andtlsTerminateare read from fewer sources, as their entries say.
Docs: network.
filesystem: Option<SandboxFilesystem>Control which paths sandboxed commands can read and write. By default they can write to
the working directory, the per-user temp directory, and directories you add with
--add-dir, /add-dir, or permissions.additionalDirectories, and can read the rest
of the filesystem, including credential files. Widen or narrow that with the four path
lists, or switch the filesystem layer off with disabled.
- Values: object with
allowWrite,denyWrite,denyRead, andallowReadarrays, plus theallowManagedReadPathsOnlyanddisabledBooleans - Default: unset, so the default read and write boundaries apply
- Scope: any settings file.
Docs: filesystem.
credentials: Option<SandboxCredentials>Declare the credential files and environment variables to protect from sandboxed
commands. Each entry
names a file path or a variable name and a mode: deny hides the credential
inside the sandbox, and mask shows sandboxed commands a placeholder while the sandbox
proxy substitutes the real
value on outbound requests. Claude Code protects only the entries you list; there is no
built-in credential deny list.
- Values: object with
files,envVars,allowPlaintextInject,awsPairs, andsigv4 - Default: unset, so no credentials are protected
- Scope: any settings file. Claude Code honors
maskentries,allowPlaintextInject,awsPairs, andsigv4only from user settings, managed settings, and the--settingsflag.
Docs: credentials.
ripgrep: Option<Ripgrep>Point the sandbox at a ripgrep binary of your own instead of the one Claude Code uses,
for example when your platform needs a differently built rg.
- Values: object with
command, the path to the ripgrep binary, and optionalargs, an array of arguments to prepend - Default: unset, so the sandbox uses the same ripgrep binary as Claude Code. That
is the bundled binary unless you set
USE_BUILTIN_RIPGREPto0 - Scope: user or managed.
Docs: ripgrep.
enable_weaker_network_isolation: Option<bool>Let sandboxed commands on macOS reach the system TLS trust service,
com.apple.trustd.agent. Go-based tools such as gh, gcloud, and terraform need it
to verify TLS certificates when you use
network.httpProxyPort
with a MITM proxy and a custom CA. This reduces security by opening a potential data
exfiltration path through the trust service.
- Values: Boolean
true: sandboxed commands on macOS can reachcom.apple.trustd.agentfalse: sandboxed commands on macOS can’t reach the system TLS trust service
- Default:
false - Scope: any settings file, with limits on project and local settings.
Docs: enableWeakerNetworkIsolation.
enable_weaker_nested_sandbox: Option<bool>Run the Linux sandbox inside an unprivileged Docker container, where bubblewrap can’t
mount a fresh /proc. Instead the inner sandbox bind-mounts the container’s existing
/proc, which exposes process information that a fresh mount would hide. This reduces
security; use it only when the outer container already provides the isolation you need.
- Values: Boolean
true: the inner sandbox bind-mounts the container’s existing/procinstead of mounting a fresh onefalse: the sandbox mounts a fresh/proc, which doesn’t work in an unprivileged Docker container
- Default:
false - Scope: any settings file, with limits on project and local settings.
Docs: enableWeakerNestedSandbox.
bwrap_path: Option<String>Point the sandbox at a bubblewrap binary installed outside PATH, such as a vendored
copy on an air-gapped host. Claude Code uses the path both for the startup dependency
check and when it wraps each sandboxed command.
- Values: string, an absolute path; Claude Code drops a relative path and falls back
to
PATHlookup - Default: unset, so Claude Code finds
bwraponPATH - Scope: managed. Claude Code reads it only from managed settings so that a user, project, or local file can’t point the sandbox at a different binary.
Docs: bwrapPath.
socat_path: Option<String>Point the sandbox network proxy at a socat binary installed outside PATH.
- Values: string, an absolute path; Claude Code drops a relative path and falls back
to
PATHlookup - Default: unset, so Claude Code finds
socatonPATH - Scope: managed.
Docs: socatPath.
Make Claude Code exit with an error at startup when sandbox.enabled is true but the
sandbox can’t start because the platform doesn’t support it or the dependency check
fails. Without this key, Claude Code runs commands unsandboxed. Managed deployments that
require sandboxing as a security gate can use this setting.
- Values: Boolean
true: Claude Code exits with an error at startup whensandbox.enabledistruebut the sandbox can’t start. If the sandbox passes that check and then fails to initialize, the session keeps running and Claude Code refuses each sandboxed commandfalse: Claude Code runs commands unsandboxed when the sandbox can’t start
- Default:
false - Scope: any settings file, with limits on project and local settings.
Docs: failIfUnavailable.
enabled_platforms: Option<Vec<Platform>>Limit the entire sandbox configuration to the listed platforms. On platforms not in the list the sandbox config is inert: no sandbox, no auto-allow, no startup warning, and no failIfUnavailable exit. When omitted, all supported platforms are included.
- Values: array of strings
- Default: unset
Docs: enabledPlatforms.
allow_apple_events: Option<bool>Let sandboxed commands on macOS send Apple Events, which open, osascript, and tools
that open URLs in a browser need; without it they fail with error -600. This removes
code-execution isolation: sandboxed commands can launch other applications unsandboxed
with no user prompt, and can send AppleScript commands to running applications such as
Terminal, subject to the per-app macOS automation-consent prompt (TCC).
- Values: Boolean
true: sandboxed commands on macOS can send Apple Eventsfalse: sandboxed commands on macOS can’t send Apple Events, soopenandosascriptfail with error-600
- Default:
false - Scope: user or managed.
Docs: allowAppleEvents.
allow_nested_user_namespaces: Option<bool>Let sandboxed commands on Linux and WSL2 create user namespaces, which Chromium’s and
Electron’s own sandbox, a nested bubblewrap, and unshare need. If you set this key to
true, you turn off a security boundary: code from a sandboxed command can end up
running outside the sandbox. For rootless Podman or Buildah, use
excludedCommands
instead, because the sandbox stops them in other ways too.
- Values: Boolean
true: sandboxed commands can create user namespacesfalse: this key allows nothing extra, and the sandbox’s default applies
- Default:
false - Scope: user or managed. A
truecounts from~/.claude/settings.json, JSON passed with--settings, or managed settings.
Docs: allowNestedUserNamespaces.
extra: ExtraKeys Claude Code accepts here that this crate doesn’t model (newer or undocumented ones), kept as written so the document round-trips.