Skip to main content

Sandbox

Struct Sandbox 

Source
#[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
Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional 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 commands
    • false: 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_SCRUB turns auto-allow off
    • false: sandboxed commands go through the regular permission flow, so your allow rules and permission mode decide. The /sandbox Mode 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.

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 the dangerouslyDisableSandbox parameter after the sandbox blocks it
    • false: Claude Code ignores that parameter, so while the sandbox is running, commands Claude runs are sandboxed unless they match an excludedCommands entry
  • 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, and tlsTerminate are 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, and allowRead arrays, plus the allowManagedReadPathsOnly and disabled Booleans
  • 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, and sigv4
  • Default: unset, so no credentials are protected
  • Scope: any settings file. Claude Code honors mask entries, allowPlaintextInject, awsPairs, and sigv4 only from user settings, managed settings, and the --settings flag.

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 optional args, 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_RIPGREP to 0
  • 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 reach com.apple.trustd.agent
    • false: 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 /proc instead of mounting a fresh one
    • false: 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 PATH lookup
  • Default: unset, so Claude Code finds bwrap on PATH
  • 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 PATH lookup
  • Default: unset, so Claude Code finds socat on PATH
  • Scope: managed.

Docs: socatPath.

§fail_if_unavailable: Option<bool>

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 when sandbox.enabled is true but 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 command
    • false: 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 Events
    • false: sandboxed commands on macOS can’t send Apple Events, so open and osascript fail 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 namespaces
    • false: this key allows nothing extra, and the sandbox’s default applies
  • Default: false
  • Scope: user or managed. A true counts from ~/.claude/settings.json, JSON passed with --settings, or managed settings.

Docs: allowNestedUserNamespaces.

§extra: Extra

Keys Claude Code accepts here that this crate doesn’t model (newer or undocumented ones), kept as written so the document round-trips.

Trait Implementations§

Source§

impl Clone for Sandbox

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Debug for Sandbox

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
Source§

impl Default for Sandbox

Source§

fn default() -> Self

Returns the “default value” for a type. Read more
Source§

impl<'de> Deserialize<'de> for Sandbox

Source§

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>
where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer. Read more
Source§

impl PartialEq for Sandbox

Source§

fn eq(&self, other: &Self) -> bool

Equality operator ==. Read more
1.0.0 (const: unstable) · Source§

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=. Read more
Source§

impl Serialize for Sandbox

Source§

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>
where __S: Serializer,

Serialize this value into the given Serde serializer. Read more
Source§

impl StructuralPartialEq for Sandbox

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> DeserializeOwned for T
where T: for<'de> Deserialize<'de>,

Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.