Configure sandboxing

Customize sandbox behavior through your settings.json file. See Settings for the complete configuration reference.

By default, sandboxed commands can write to the current working directory, the session temp directory, and any directories you've added with --add-dir, /add-dir, or permissions.additionalDirectories. If subprocess commands like kubectl, terraform, or npm need to write outside those directories, use sandbox.filesystem.allowWrite to grant access to specific paths:

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": ["~/.kube", "/tmp/build"]
    }
  }
}

These paths are enforced at the OS level, so all commands running inside the sandbox, including their child processes, respect them. This is the recommended approach when a tool needs write access to a specific location, rather than excluding the tool from the sandbox entirely with excludedCommands.

When you define the same filesystem array in multiple settings scopes, Claude Code merges them, combining paths from every scope rather than replacing one scope's array with another's.

If you exclude a source with --setting-sources on the CLI or settingSources in the Agent SDK, Claude Code ignores its sandbox.filesystem entries, its Edit permission rules, and its Read deny rules when building the sandbox configuration. Requires Claude Code v2.1.246 or later.

When you edit these filesystem lists during a session, Claude Code applies the change to the running session, so the next sandboxed command runs under the new paths.

Path prefixes control how paths are resolved:

Prefix	Meaning	Example
/	Absolute path from filesystem root	/tmp/build stays /tmp/build
~/	Relative to home directory	~/.kube becomes $HOME/.kube