All settings

Settings index

Model and responses

advisorModel

• Scope: Any file
• Type: string, one of the aliases "fable", "opus", or "sonnet", which resolve to Claude Code’s current default version of that model family, or a full model ID such as "claude-opus-5-5"
• Default: unset, so the advisor is off
• Per-session overrides: --advisor takes precedence over this key for one session. CLAUDE_CODE_DISABLE_ADVISOR_TOOL turns the advisor off, and this key can’t turn it back on

{
  "advisorModel": "opus"
}

alwaysThinkingEnabled

• Scope: Any file
• Type: Boolean
  • true: no effect; thinking is already on
  • false: Claude Code turns extended thinking off for every session
• Default: unset, so thinking is on for models that support it
• Per-session overrides: MAX_THINKING_TOKENS takes precedence over this key for one session: 0 turns thinking off, under the same model and provider limits as false, and a positive value turns thinking on even when this key is false. On adaptive-reasoning models the number itself is ignored

{
  "alwaysThinkingEnabled": false
}

availableModels

• Scope: Any file. Deploy it in managed settings to enforce it for an organization.
• Type: array of model aliases or IDs
• Default: unset, so every model is available

{
  "availableModels": ["sonnet", "haiku"]
}

availableModelsMatch

• Scope: Managed. Claude Code ignores the key in user, project, and local settings and in --settings, with a warning
• Type: string, one of:
  • "prefix": a model ID entry permits its version and any model ID that extends it with another segment
  • "exact": a model ID entry permits only the version it names, so "claude-opus-5" permits Opus 5 but not claude-opus-5-5. An entry such as "claude-opus-4-5" also permits its dated Anthropic model ID claude-opus-4-5-20251101. A family alias such as "opus" still permits the whole family, and best, opusplan, and default entries are ignored
• Default: "prefix"

{
  "availableModels": ["claude-opus-5", "claude-sonnet-5"],
  "availableModelsMatch": "exact"
}

deniedModels

• Scope: Managed. Claude Code ignores the key in user, project, and local settings and in --settings, with a warning
• Type: array of model aliases or IDs
  • A family alias such as "opus" blocks every model in that family
  • A model ID such as "claude-opus-5-5" blocks that version in every spelling, including dated and provider-specific IDs
  • A model ID with no minor version, such as "claude-opus-5", also blocks later minor versions such as Opus 5.5. Write "claude-opus-5-0" to block Opus 5 alone
  • best, opusplan, and default entries are ignored
• Default: unset, so no model is blocked

{
  "availableModels": ["opus", "sonnet"],
  "deniedModels": ["claude-opus-5-5"]
}

effortLevel

• Scope: Any file
• Type: string, one of:
  • "low": the least reasoning, for short, scoped, latency-sensitive tasks that aren’t intelligence-sensitive
  • "medium": reduces token usage for cost-sensitive work that can trade off some intelligence
  • "high": balances token usage and intelligence
  • "xhigh": deeper reasoning at higher token spend
• Default: unset
• Per-session overrides: --effort takes precedence over this key for one session, and CLAUDE_CODE_EFFORT_LEVEL takes precedence over both

{
  "effortLevel": "xhigh"
}

enforceAvailableModels

• Scope: Any file
• Type: Boolean
  • true: when Default would resolve to a model outside availableModels, Claude Code resolves it to the first available model in the list
  • false: this key doesn’t change how Default resolves
• Default: false

{
  "availableModels": ["sonnet", "haiku"],
  "enforceAvailableModels": true
}

fallbackModel

• Scope: Any file
• Type: array of model aliases or IDs; "default" expands to the default model
• Default: unset, so a failed request isn’t retried on another model
• Per-session overrides: --fallback-model takes precedence over this key for one session

{
  "fallbackModel": ["claude-sonnet-5", "claude-haiku-4-5"]
}

fastMode

• Scope: Any file
• Type: Boolean
  • true: Claude Code turns fast mode on for sessions where it’s available. On Fable 5.2, you must also run /fast while using Fable 5.2
  • false: fast mode stays off
• Default: unset, so fast mode is off
• Per-session overrides: CLAUDE_CODE_DISABLE_FAST_MODE turns fast mode off for one session, and this key can’t turn it back on

{
  "fastMode": true
}

fastModePerSessionOptIn

• Scope: Any file
• Type: Boolean
  • true: a saved fastMode: true no longer turns fast mode on at session start, so each person runs /fast in each session they want it; a fastMode: true passed with --settings still counts for that session unless managed settings set this key
  • false: a saved fastMode: true works as fastMode describes
• Default: false

{
  "fastModePerSessionOptIn": true
}

language

• Scope: Any file
• Type: string, any language name, such as "japanese", "spanish", or "french"; Claude Code doesn’t validate it
• Default: unset; session titles then match the language of your conversation

{
  "language": "japanese"
}

maxEffortLevel

• Scope: Any file. Deploy it in managed settings to enforce it for an organization. When several scopes set a cap, the lowest applies, so a cap set in one scope can’t be raised from another
• Type: string, one of "low", "medium", "high", "xhigh", or "max". A "max" value sets no cap
• Default: unset, so no cap applies
• Per-model caps: add maxEffortLevel to a model’s modelSettings entry. That entry replaces this key for the model only within the settings source that sets both, such as your user settings or one managed source. Set "max" there to exempt the model from that source’s cap; Claude Code still applies caps from other sources

{
  "maxEffortLevel": "medium",
  "modelSettings": {
    "claude-sonnet-4-6": {
      "maxEffortLevel": "max"
    }
  }
}

model

• Scope: Any file
• Type: string, a model alias or full model ID
• Default: unset, so Claude Code uses your account’s default model
• Per-session overrides: --model takes precedence over ANTHROPIC_MODEL, and both take precedence over this key for one session, including over a managed model; an availableModels list still applies to the pick

{
  "model": "claude-sonnet-5"
}

modelOverrides

• Scope: Any file
• Type: object mapping model ID to provider model ID
• Default: unset

{
  "modelOverrides": {
    "claude-opus-4-6": "arn:aws:bedrock:us-east-1:123456789012:inference-profile/example"
  }
}

modelPicker

• Scope: User or managed. Claude Code reads the key from managed settings, --settings, and user settings, and ignores it in project and local settings so a repository you clone can’t relabel the picker. The highest of those three that sets the key supplies the whole lineup, and Claude Code never combines lineups from two sources.
• Type: object with an options array of rows and an optional replaceBuiltInOptions Boolean
• Default: unset, so the picker shows the built-in lineup

{
  "modelPicker": {
    "options": [
      { "model": "us.anthropic.claude-opus-4-8", "label": "Opus (production)" },
      {
        "model": "us.anthropic.claude-sonnet-4-6",
        "label": "Sonnet (production)",
        "description": "Day-to-day work"
      }
    ]
  }
}

Fields for modelPicker

• Dropped: a row Claude Code can’t serve, such as a retired model or a model your organization has no access to
• Grayed out: a row you can’t select yet, shown with the reason
• No row survives: Claude Code keeps the built-in lineup, filtered by the allowlist as usual

modelPricing

• Scope: Managed. Deploy the key through server-managed settings, an MDM policy, a managed-settings.json file, or a policy helper. Claude Code ignores it in user, project, and local settings, in --settings, and on Windows in the user-writable HKCU registry. With server-managed settings, each session reports costs at list price until that session’s settings fetch has confirmed the setting. A host application that embeds Claude Code and sets CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST can supply a table of its own through the SDK managedSettings option, which Claude Code uses only when no managed source sets the key and only in Claude Code v2.1.246 or later.
• Type: object with an optional multiplier and an optional overrides map
• Default: unset, so Claude Code reports list price unless a host application supplies a table

{
  "modelPricing": {
    "multiplier": 0.85,
    "overrides": {
      "claude-sonnet-4-6": {
        "input": 2.4,
        "output": 12,
        "cacheRead": 0.24,
        "cacheWrite": 3
      }
    }
  }
}

Fields for modelPricing

Which models a modelPricing row applies to

• A built-in model’s ID: a key Claude Code itself uses for a built-in model, whether that key is the model’s own ID, such as claude-sonnet-4-6, or its Bedrock, Agent Platform, or Foundry ID. Claude Code applies the row to every dated snapshot ID and provider-specific ID of that model.
• Any other key: a key that isn’t a built-in model’s ID, such as a gateway model alias. Claude Code applies the row to that one ID only. When a model ID matches one of your keys exactly and also falls under a row keyed by a built-in model’s ID, Claude Code uses the exact match.
• A Bedrock application inference profile: once Claude Code has resolved the profile to the model it routes to, through your modelOverrides map or the bedrock:GetInferenceProfile lookup, Claude Code applies that model’s row to the profile.

modelSettings

• Scope: Any file
• Type: object mapping a model name to an object with any of these fields:
  • effortLevel: one of "low", "medium", "high", or "xhigh"
  • maxEffortLevel: the highest effort level the model may run at
  • autoCompactWindow: a number of tokens from 100000 to 1000000, or "auto" for the window tuned for the model. /autocompact saves here. For that model, the value takes precedence over a top-level autoCompactWindow in the same settings file. Requires Claude Code v2.1.288 or later
• Default: unset

{
  "modelSettings": {
    "claude-opus-5-5": {
      "effortLevel": "high"
    }
  }
}

outputStyle

• Scope: Any file
• Type: string, the name of a built-in or custom output style
• Default: unset, so Claude Code uses the default style

{
  "outputStyle": "Explanatory"
}

promptCacheTtl

• Scope: Any file
• Type: string, one of:
  • "5m": the cache holds for five minutes
  • "1h": the cache holds for an hour
• Default: unset, so each main-conversation request gets its default lifetime
• Per-session overrides: FORCE_PROMPT_CACHING_5M takes precedence over everything else, then CLAUDE_CODE_PROMPT_CACHE_TTL, then this key, and last ENABLE_PROMPT_CACHING_1H

{
  "promptCacheTtl": "1h",
  "subagentPromptCacheTtl": "5m"
}

showThinkingSummaries

• Scope: Any file
• Type: Boolean
  • true: you see full thinking summaries when you expand thinking with Ctrl+O
  • false: the Anthropic API redacts thinking blocks and Claude Code shows a collapsed stub
• Default: false

{
  "showThinkingSummaries": true
}

subagentPromptCacheTtl

• Scope: Any file
• Type: string, one of:
  • "5m": the cache holds for five minutes
  • "1h": the cache holds for an hour
• Default: unset, so each of these requests gets its default lifetime
• Per-session overrides: FORCE_PROMPT_CACHING_5M takes precedence over everything else, then CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL, then this key, then ENABLE_PROMPT_CACHING_1H, which asks for the one-hour lifetime on every request. For where a subagent’s own frontmatter value ranks, see Choose the TTL yourself

{
  "subagentPromptCacheTtl": "1h"
}

switchModelsOnFlag

• Scope: Any file. Appears in /config as Switch models when a message is flagged, with the options Switch automatically and Ask each time.
• Type: Boolean
  • true: Claude Code switches to the fallback model and continues
  • false: in an interactive session Claude Code pauses so you can choose between switching and editing the prompt; where no dialog can show, such as a -p run, the flagged request ends as an error
• Default: unset. Claude Code switches automatically, though it may ask first in an interactive session

{
  "switchModelsOnFlag": false
}

ultracode

• Scope: Any file
• Type: Boolean
  • true: sessions start with ultracode on when dynamic workflows are enabled for you and your model supports xhigh
  • false: sessions start with ultracode off
• Default: unset, so ultracode is off
• Per-session overrides: /effort ultracode turns ultracode on for one session without this key, and /effort ultracode off turns it off for one session when this key is true. The --effort ultracode flag also turns it on for one session, at xhigh effort

{
  "ultracode": true
}

Permission settings

allowManagedPermissionRulesOnly

• A repository’s .claude/ directory
• Your ~/.claude/skills/ and ~/.claude/commands/ directories, including skills synced from claude.ai
• An --add-dir directory
• Plugins declared with a .claude-plugin manifest inside ~/.claude/skills/ or the project’s .claude/skills/
• Plugins loaded for one session only, whose ids end in @inline, when all of these hold:
  • The session is a Code session or Cowork session, other than a cloud session, for which the Claude Desktop app itself starts Claude Code
  • Your managed settings set the key, not only an embedding host’s parent settings
  • The session runs Claude Code v2.1.305 or later

• Scope: Managed
• Type: Boolean
  • true: managed settings become the only settings source of permission rules
  • false: Claude Code applies permission rules from user, project, local, and --settings files in addition to the managed ones
• Default: unset, so Claude Code applies permission rules from user, project, and local settings and from --settings, in addition to the managed ones

{
  "allowManagedPermissionRulesOnly": true
}

autoMode

• Scope: User or managed
• Type: object with environment, allow, soft_deny, and hard_deny arrays of prose rules, plus the classifyAllShell Boolean
• Default: unset, so the classifier uses only its built-in rules

{
  "autoMode": {
    "soft_deny": ["$defaults", "Never run terraform apply"]
  }
}

autoMode.classifyAllShell

• Scope: User or managed. Read wherever autoMode is read.
• Type: Boolean
  • true: while auto mode is active, Claude Code sends every Bash and PowerShell command through the classifier and suspends your shell allow rules; outside auto mode the rules still apply
  • false: auto mode suspends only allow rules that could run arbitrary code, such as Bash(*) and Bash(python *); a command that any other allow rule matches skips the classifier unless it carries per-command allowed domains, and every other shell command goes through it
• Default: false

{
  "autoMode": {
    "classifyAllShell": true
  }
}

disableAutoMode

• Scope: Any file. Most useful in managed settings, where users can’t override it. Also accepted under permissions as permissions.disableAutoMode.
• Type: the string "disable"
• Default: unset

{
  "disableAutoMode": "disable"
}

permissions

• Scope: Any file
• Type: object with allow, ask, deny, additionalDirectories, blockReadsOutsideWorkingDirectories, blockWritesOutsideWorkingDirectories, defaultMode, denyInsteadOfPrompting, disableBypassPermissionsMode, and disableAutoMode
• Default: unset

{
  "permissions": {
    "allow": ["Bash(npm run *)"],
    "ask": ["Bash(git push *)"],
    "deny": ["Read(./.env)"],
    "defaultMode": "acceptEdits"
  }
}

useAutoModeDuringPlan

• Scope: User, local, or managed. A repository can’t turn it off for you.
  • A false in any of these files or in --settings turns it off, unless you leave that user or local file out with an option such as --setting-sources. Ignoring a left-out file requires Claude Code v2.1.314 or later
• Type: Boolean
  • true: the same as unset; when auto mode is available, the classifier reviews shell commands during planning
  • false: you get a permission prompt for every command outside the built-in read-only set
• Default: true

{
  "useAutoModeDuringPlan": false
}

permissions.allow

• Scope: Any file
• Type: array of permission rule strings
• Default: unset
• Per-session overrides: --allowedTools adds allow rules for one session, and a deny rule from any settings file still blocks a tool it names

{
  "permissions": {
    "allow": ["Bash(git diff *)", "Read(~/.zshrc)"]
  }
}

Permission rule syntax

permissions.ask

• Scope: Any file
• Type: array of permission rule strings
• Default: unset

{
  "permissions": {
    "ask": ["Bash(git push *)"]
  }
}

permissions.deny

• Scope: Any file
• Type: array of permission rule strings
• Default: unset
• Per-session overrides: --disallowedTools adds deny rules for one session alongside this key

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(./config/credentials.json)",
      "Bash(curl *)"
    ]
  }
}

permissions.additionalDirectories

• Scope: Any file, with limits on the sandbox write access that project and local entries give
• Type: array of directory paths
• Default: unset
• Per-session overrides: --add-dir and /add-dir add directories for one session alongside this key

{
  "permissions": {
    "additionalDirectories": ["../docs/"]
  }
}

permissions.blockReadsOutsideWorkingDirectories

• Actions no mode auto-approves covers when a shell command that reads such a path prompts you
• Sandboxed commands under the block covers what a sandboxed command can read

• Scope: Any file. A true in any file applies, so a repository can turn the block on for itself but can’t lift yours.
• Type: Boolean
  • true: Claude’s file tools refuse reads outside the working directories
  • false: the same as unset; the block still applies if another file sets true
• Default: unset, so reads outside the working directories follow your permission mode

{
  "permissions": {
    "blockReadsOutsideWorkingDirectories": true
  }
}

Sandboxed commands under the block

• Filesystem isolation is off through sandbox.filesystem.disabled
• allowManagedReadPathsOnly is set
• The path of the directory you started Claude Code in contains a glob character such as *, ?, or [

• ~/.gitconfig
• The config, ignore, and attributes files under $XDG_CONFIG_HOME/git, which defaults to ~/.config/git
• Files your global git configuration names through [include], [includeIf], core.excludesFile, or core.attributesFile

permissions.blockWritesOutsideWorkingDirectories

• Scope: Any file. A true in any file the session loads applies, so a repository can turn the block on for itself but can’t lift yours. In a cloud session, Claude Code might not apply the key, because the file tools run in a container that is itself the boundary.
• Type: Boolean
  • true: turns the block on
  • false: the same as unset; the block still applies if another file sets true
• Default: unset, so writes outside the working directories follow your permission mode. The block is also on while Claude Code can’t read the permissions object in your managed settings.

{
  "permissions": {
    "blockWritesOutsideWorkingDirectories": true
  }
}

What the write block refuses and what stays writable

• Claude Code settings files: Claude Code refuses these writes inside the working directories too, because a settings file can lift the block. Edit settings files yourself.
• A directory that only repository settings add: one that additionalDirectories lists only in .claude/settings.json, or in .claude/settings.local.json unless git reports that file as untracked
• A subagent’s worktree: an isolation: worktree subagent’s file edits are refused when its worktree sits outside the working directories
• Auto memory in a directory the repository chose: a directory that autoMemoryDirectory names in repository settings

Let one directory through the read or write block

permissions.defaultMode

• Scope: Any file. auto and bypassPermissions don’t take effect from project or local settings, so set them in ~/.claude/settings.json instead. Before v2.1.257, bypassPermissions took effect from any file. For conversations the VS Code extension starts, Claude Code reads only user, managed, and --settings values.
• Type: string, one of:
  • "default": Claude Code runs only reads without asking
  • "acceptEdits": Claude Code also runs file edits and common filesystem commands such as mkdir and mv without asking
  • "plan": Claude Code reads and plans but blocks edits until you approve a plan
  • "auto": Claude Code runs without routine prompts; before actions such as shell commands and network requests run, a background classifier checks that they align with your request
  • "dontAsk": Claude Code auto-denies every call that would otherwise prompt, though a mod you installed can still approve some of those calls. File reads inside your working directories, other actions that need no approval, and pre-approved tools still run, apart from reads from network paths
  • "bypassPermissions": Claude Code runs everything without asking
  • "manual": an alias for "default"
• Default: unset
• Per-session overrides: --permission-mode, and its equivalent --dangerously-skip-permissions for bypassPermissions, take precedence over this key for one session

{
  "permissions": {
    "defaultMode": "acceptEdits"
  }
}

permissions.denyInsteadOfPrompting

• Scope: User or managed, and --settings. A repository can’t set it for you.
• Type: Boolean
  • true: Claude Code denies calls that would otherwise prompt
  • false: the same as unset; calls are still denied if another of these sources sets true
• Default: unset, so a call that needs approval prompts you

{
  "permissions": {
    "defaultMode": "auto",
    "denyInsteadOfPrompting": true
  }
}

What else denyInsteadOfPrompting stops

• Question and plan tools: Claude Code leaves out AskUserQuestion, EnterPlanMode, and ExitPlanMode, so a session in plan mode can’t leave it on its own. A teammate in an agent team keeps EnterPlanMode and ExitPlanMode
• MCP elicitation: Claude Code cancels an elicitation request unless an Elicitation hook answers it
• Permission hosts: Claude Code doesn’t ask your canUseTool callback or --permission-prompt-tool. To approve calls from code, answer from a PermissionRequest hook. Some calls are denied before any hook is asked, such as a critical-path removal in auto mode that no ask rule covers.
• Classifier billing notice: where the notice about billed classifier requests would open a dialog, Claude Code doesn’t show it and denies the actions that need those requests

Messages from denyInsteadOfPrompting

Permission for this tool use was denied. It requires approval, and this session has no approval surface

no approval surface in this session; permission request denied automatically

20 actions were refused and no work went ahead in between, so Claude stopped.

permissions.disableBypassPermissionsMode

• Scope: Any file. Typically set in managed settings to enforce organizational policy.
• Type: the string "disable"
• Default: unset
• Per-session overrides: this key takes precedence over --dangerously-skip-permissions, which Claude Code rejects while the key is set

{
  "permissions": {
    "disableBypassPermissionsMode": "disable"
  }
}

skipAutoPermissionPrompt

• Scope: User or managed. A repository can’t set it for you.
• Type: Boolean
  • true: Claude Code skips the notice
  • false: the same as unset; the notice appears once unless another of these files sets true
• Default: unset, so the notice appears once

{
  "skipAutoPermissionPrompt": true
}

skipDangerousModePermissionPrompt

• Scope: User, local, or managed, and files passed with --settings. Background sessions count only user and managed settings. An untrusted repository can’t skip the dialog for you.
• Type: Boolean
  • true: Claude Code skips the confirmation dialog before a session enters bypassPermissions mode
  • false: the same as unset; the dialog appears unless another of these files sets true
• Default: unset, so the dialog appears

{
  "skipDangerousModePermissionPrompt": true
}

Sandbox settings

sandbox

• Scope: Any file
• Type: object with enabled, failIfUnavailable, autoAllowBashIfSandboxed, excludedCommands, allowUnsandboxedCommands, enableWeakerNestedSandbox, enableWeakerNetworkIsolation, allowAppleEvents, allowNestedUserNamespaces, bwrapPath, socatPath, ignoreViolations, and ripgrep, plus the filesystem, network, and credentials objects
• Default: unset, so Claude Code runs commands without a sandbox

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["docker *"],
    "filesystem": {
      "allowWrite": ["/tmp/build", "~/.kube"],
      "denyRead": ["~/.aws/credentials"]
    },
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org"]
    }
  }
}

sandbox.enabled

• Scope: Any file, with limits on project and local settings
• Type: Boolean
  • true: Claude Code sandboxes Bash commands
  • false: Bash commands run unsandboxed
• Default: false

{
  "sandbox": {
    "enabled": true
  }
}

sandbox.failIfUnavailable

• Scope: Any file, with limits on project and local settings
• Type: 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

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

sandbox.autoAllowBashIfSandboxed

• Scope: Any file
• Type: 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

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": false
  }
}

sandbox.excludedCommands

• Scope: Any file, with limits on project and local settings
• Type: array of command patterns
• Default: unset, so no command is excluded

{
  "sandbox": {
    "excludedCommands": ["docker *"]
  }
}

• A command starting with sudo, eval, or xargs
• A cd, pushd, or popd, wherever it appears in the call
• A command substitution, a subshell, or a control-flow block such as if or for
• A redirection, such as docker build . > build.log or a <<EOF heredoc, other than one that only duplicates a file descriptor, as 2>&1 does
• A command name that comes from a variable
• A git clone, git init, git worktree add, git worktree move, or git bundle create with a path argument that is absolute, starts with ~, or contains a .. segment

sandbox.allowUnsandboxedCommands

• Scope: Any file, with a limit on project and local settings
• Type: 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

{
  "sandbox": {
    "enabled": true,
    "allowUnsandboxedCommands": false
  }
}

sandbox.filesystem

• Scope: Any file
• Type: object with allowWrite, denyWrite, denyRead, and allowRead arrays, plus the allowManagedReadPathsOnly and disabled Booleans
• Default: unset, so the default read and write boundaries apply

{
  "sandbox": {
    "filesystem": {
      "allowWrite": ["/tmp/build", "~/.kube"],
      "denyRead": ["~/.aws/credentials"]
    }
  }
}

Sandbox path prefixes

Where wildcards work in sandbox paths

~/keys/*.pem              the entry
/home/alice/keys/*.pem    its full path
 ^^^^                     the first directory name, home

Directory names with brackets, braces, or parentheses

app/
└── [slug]/
    └── page.tsx

• Brackets such as [slug]: in every list on macOS, and in denyRead and allowRead on Linux and WSL2, the brackets in ./app/[slug] are also a pattern. The entry then also matches any path under app named with one character from slug, such as app/s or app/g. With that entry in allowRead, or in allowWrite on macOS, sandboxed commands can reach those paths as well. Rename any they shouldn’t reach.
• Brackets such as [user-id] or [post-id], where the hyphen’s left character sorts after its right: ./app/[user-id] covers only the directory with exactly that name, in every list on every platform. Before v2.1.304, sandboxed commands on Linux and WSL2 failed to start while denyRead or allowRead held such an entry.
• Braces and parentheses: these are ordinary characters, so ~/data/{keys,tokens} covers one directory named {keys,tokens}, not two alternatives. To cover ~/data/keys and ~/data/tokens, add each as its own entry.

sandbox.filesystem.allowWrite

• Scope: Any file, with limits on project and local settings
• Type: array of path strings, using the sandbox path prefixes
• Default: unset, so sandboxed commands can write to the working directory, the per-user temp directory, directories you’ve added with --add-dir or /add-dir, and directories in permissions.additionalDirectories

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

sandbox.filesystem.denyWrite

• Scope: Any file
• Type: array of path strings, using the sandbox path prefixes
• Default: unset

{
  "sandbox": {
    "filesystem": {
      "denyWrite": ["/etc", "/usr/local/bin"]
    }
  }
}

sandbox.filesystem.denyRead

• Scope: Any file
• Type: array of path strings, using the sandbox path prefixes
• Default: unset, so sandboxed commands keep the default read access, which includes credential files such as ~/.aws/credentials

{
  "sandbox": {
    "filesystem": {
      "denyRead": ["~/.aws/credentials"]
    }
  }
}

sandbox.filesystem.allowRead