ClaudeCode.Sandbox (ClaudeCode v0.29.0)

View Source

Top-level sandbox configuration struct.

Maps to the SandboxSettings type in the TS SDK. Provides bash command sandboxing with filesystem and network isolation.

See the official sandboxing documentation for full details.

Fields

  • :enabled - Enable bash sandboxing (macOS, Linux, and WSL2).
  • :auto_allow_bash_if_sandboxed - Auto-approve bash commands when sandboxed.
  • :allow_unsandboxed_commands - Allow commands to run outside sandbox via dangerouslyDisableSandbox parameter. When false, the escape hatch is disabled.
  • :enable_weaker_nested_sandbox - Enable weaker sandbox for unprivileged Docker environments (Linux and WSL2 only). Reduces security.
  • :excluded_commands - Commands that should run outside the sandbox.
  • :ignore_violations - Map of violation categories to ignore.
  • :ripgrep - Custom ripgrep binary configuration (%{command: path, args: [flags]}).
  • :filesystem - Filesystem isolation settings. See ClaudeCode.Sandbox.Filesystem.
  • :network - Network isolation settings. See ClaudeCode.Sandbox.Network.

Examples

Explicit sub-struct construction:

sandbox = ClaudeCode.Sandbox.new(
  enabled: true,
  auto_allow_bash_if_sandboxed: true,
  filesystem: ClaudeCode.Sandbox.Filesystem.new(
    allow_write: ["/tmp/build"],
    deny_read: ["~/.aws/credentials"]
  ),
  network: ClaudeCode.Sandbox.Network.new(
    allowed_domains: ["*.example.com"],
    allow_local_binding: true
  )
)

Auto-wrapping from keyword lists (sub-structs are created automatically):

sandbox = ClaudeCode.Sandbox.new(
  enabled: true,
  filesystem: [allow_write: ["/tmp/build"], deny_read: ["~/.aws/credentials"]],
  network: [allowed_domains: ["*.example.com"], allow_local_binding: true]
)

Summary

Types

t()

Functions

new(opts)

Creates a new Sandbox struct.

to_settings_map(sandbox)

Converts to the camelCase map expected by the CLI.

Types

t()

@type t() :: %ClaudeCode.Sandbox{
  allow_unsandboxed_commands: boolean() | nil,
  auto_allow_bash_if_sandboxed: boolean() | nil,
  enable_weaker_nested_sandbox: boolean() | nil,
  enabled: boolean() | nil,
  excluded_commands: [String.t()] | nil,
  filesystem: ClaudeCode.Sandbox.Filesystem.t() | nil,
  ignore_violations: %{required(String.t()) => [String.t()]} | nil,
  network: ClaudeCode.Sandbox.Network.t() | nil,
  ripgrep: map() | nil
}

Functions

new(opts)

@spec new(keyword() | map()) :: t()

Creates a new Sandbox struct.

Accepts a keyword list or map (atom, string, or camelCase string keys). Unknown keys are ignored.

When :filesystem or :network is a keyword list or map (not already a struct), it is automatically wrapped into the corresponding ClaudeCode.Sandbox.Filesystem or ClaudeCode.Sandbox.Network struct via their new/1.

Examples

iex> ClaudeCode.Sandbox.new(enabled: true, filesystem: [allow_write: ["/tmp"]])
%ClaudeCode.Sandbox{enabled: true, auto_allow_bash_if_sandboxed: nil, allow_unsandboxed_commands: nil, enable_weaker_nested_sandbox: nil, excluded_commands: nil, ignore_violations: nil, ripgrep: nil, filesystem: %ClaudeCode.Sandbox.Filesystem{allow_write: ["/tmp"], deny_write: nil, deny_read: nil}, network: nil}

to_settings_map(sandbox)

@spec to_settings_map(t()) :: map()

Converts to the camelCase map expected by the CLI.

Nil fields are omitted. Nested filesystem and network structs delegate to their own to_settings_map/1 -- if the result is an empty map, the key is omitted entirely.