Sandbox & Secure Storage

Every Bash command Claude runs could, in principle, read your SSH keys, exfiltrate files, or write to your settings. The sandbox system prevents that at the OS level — before any process can open a file or make a network call. This lesson covers:

Claude Code doesn't implement sandbox primitives itself. It wraps @anthropic-ai/sandbox-runtime — the BaseSandboxManager — through a thin adapter that adds settings integration, worktree awareness, and Claude-specific security rules. The public surface is a single SandboxManager object.

Platform backends

The sandbox backend is chosen automatically at runtime:

// sandbox-adapter.ts — memoized dependency check
const checkDependencies = memoize((): SandboxDependencyCheck => {
  const { rgPath, rgArgs } = ripgrepCommand()
  return BaseSandboxManager.checkDependencies({
    command: rgPath,
    args: rgArgs,
  })
})

// memoized platform check
const isSupportedPlatform = memoize((): boolean => {
  return BaseSandboxManager.isSupportedPlatform()
})

// SandboxDependenciesTab.tsx — Linux dep check display
// bwrap: bubblewrap (required)
// socat: network proxy (required)
// seccomp filter: optional — blocks unix domain sockets
bwrapMissing   && "apt install bubblewrap"
socatMissing   && "apt install socat"
seccompMissing && "npm install -g @anthropic-ai/sandbox-runtime"

Users select sandbox behavior through /sandbox, which renders SandboxSettings with three choices:

Mode is derived from two boolean settings: sandbox.enabled and sandbox.autoAllowBashIfSandboxed. There is also a sandbox.allowUnsandboxedCommands flag that controls whether commands explicitly excluded from sandboxing (sandbox.excludedCommands) are still permitted to run outside the sandbox.

// SandboxSettings.tsx
type SandboxMode = 'auto-allow' | 'regular' | 'disabled'

const getCurrentMode = (): SandboxMode => {
  if (!currentEnabled) return "disabled"
  if (currentAutoAllow) return "auto-allow"
  return "regular"
}

// sandbox-adapter.ts — mapping mode → settings
// auto-allow:  { enabled: true,  autoAllowBashIfSandboxed: true  }
// regular:     { enabled: true,  autoAllowBashIfSandboxed: false }
// disabled:    { enabled: false }
async function setSandboxSettings(options: {
  enabled?: boolean
  autoAllowBashIfSandboxed?: boolean
  allowUnsandboxedCommands?: boolean
}): Promise<void> {
  updateSettingsForSource('localSettings', {
    sandbox: {
      ...existingSettings?.sandbox,
      ...options,
    },
  })
}

Excluding specific commands

Some tools — like Docker daemon management or hardware-touching commands — cannot run inside the sandbox. The /sandbox exclude "pattern" command appends a pattern to sandbox.excludedCommands in local settings. The adapter also exposes addToExcludedCommands() for programmatic exclusion after a sandbox violation event.

// commands/sandbox-toggle/sandbox-toggle.tsx — /sandbox exclude subcommand
if (subcommand === 'exclude') {
  const cleanPattern = commandPattern.replace(/^["']|["']$/g, '')
  addToExcludedCommands(cleanPattern)
  // writes to localSettings: sandbox.excludedCommands
}

// sandbox-adapter.ts — policy lock detection
function areSandboxSettingsLockedByPolicy(): boolean {
  const overridingSources = ['flagSettings', 'policySettings'] as const
  for (const source of overridingSources) {
    const settings = getSettingsForSource(source)
    if (
      settings?.sandbox?.enabled !== undefined ||
      settings?.sandbox?.autoAllowBashIfSandboxed !== undefined ||
      settings?.sandbox?.allowUnsandboxedCommands !== undefined
    ) return true
  }
  return false
}

The sandbox enforces network access at the OS level. Claude Code translates its permission rules and settings into a NetworkRestrictionConfig that BaseSandboxManager enforces via the platform backend.

Domain allow/deny lists

Allowed domains come from two sources that are merged together:

1. sandbox.network.allowedDomains — explicit list in settings JSON
2. permissions.allow rules of the form WebFetch(domain:example.com)

Denied domains come from permissions.deny rules following the same WebFetch(domain:...) pattern.

// sandbox-adapter.ts — convertToSandboxRuntimeConfig()
for (const ruleString of permissions.allow || []) {
  const rule = permissionRuleValueFromString(ruleString)
  if (rule.toolName === WEB_FETCH_TOOL_NAME &&
      rule.ruleContent?.startsWith('domain:')) {
    allowedDomains.push(rule.ruleContent.substring('domain:'.length))
  }
}
// Same pattern for deniedDomains using permissions.deny

// sandbox-adapter.ts — initialize()
const wrappedCallback: SandboxAskCallback = async (hostPattern) => {
  if (shouldAllowManagedSandboxDomainsOnly()) {
    logForDebugging(
      `[sandbox] Blocked network request to ${hostPattern.host} (allowManagedDomainsOnly)`
    )
    return false  // silently deny
  }
  return sandboxAskCallback(hostPattern)
}

Additional network settings

The filesystem configuration is built from four lists — allowWrite, denyWrite, allowRead, denyRead — that are assembled from multiple sources and passed to BaseSandboxManager.

Always-allowed write paths

Two paths are unconditionally writable regardless of user settings: the current working directory ('.') and the Claude temp directory. This is the minimum required for any useful work.

// sandbox-adapter.ts — baseline writable paths
const allowWrite: string[] = ['.', getClaudeTempDir()]

Always-denied write paths (security hardcoded)

Several paths are unconditionally denied to prevent sandbox escape via settings manipulation:

• All settings.json and settings.local.json files for every settings source
• The managed settings drop-in directory
• .claude/skills in both original cwd and current cwd — skills run unsandboxed and have full Claude capabilities
• Bare git repo sentinel files (HEAD, objects, refs, hooks, config) — to block the git core.fsmonitor escape vector (CVE pattern, tracked as issue #29316)

// sandbox-adapter.ts — settings escape prevention
const settingsPaths = SETTING_SOURCES.map(source =>
  getSettingsFilePathForSource(source)
).filter((p): p is string => p !== undefined)
denyWrite.push(...settingsPaths)

// skills escape prevention
denyWrite.push(resolve(originalCwd, '.claude', 'skills'))

// sandbox-adapter.ts — post-command scrub
function scrubBareGitRepoFiles(): void {
  for (const p of bareGitRepoScrubPaths) {
    try {
      rmSync(p, { recursive: true })
    } catch {
      // ENOENT is the expected case — nothing was planted
    }
  }
}

Path resolution: permission rules vs. sandbox.filesystem

Two different path-resolution conventions exist side-by-side, and mixing them up is a documented footgun (issue #30067):

// resolvePathPatternForSandbox — permission-rule convention
// "/foo/**" → "${settingsRootDir}/foo/**"
if (pattern.startsWith('/') && !pattern.startsWith('//')) {
  const root = getSettingsRootPathForSource(source)
  return resolve(root, pattern.slice(1))
}

// resolveSandboxFilesystemPath — sandbox.filesystem convention
// "/Users/foo/.cargo" → "/Users/foo/.cargo" (absolute, as written)
return expandPath(pattern, getSettingsRootPathForSource(source))

// sandbox-adapter.ts
if (worktreeMainRepoPath && worktreeMainRepoPath !== cwd) {
  allowWrite.push(worktreeMainRepoPath)
}

Live config refresh

The sandbox config is not static. Every time the user updates a permission or settings file, a settingsChangeDetector subscription fires refreshConfig(), which calls BaseSandboxManager.updateConfig(newConfig) synchronously. This means granting a new file-edit permission takes effect immediately — no restart needed.

// sandbox-adapter.ts — live settings subscription
settingsSubscriptionCleanup = settingsChangeDetector.subscribe(() => {
  const settings = getSettings_DEPRECATED()
  const newConfig = convertToSandboxRuntimeConfig(settings)
  BaseSandboxManager.updateConfig(newConfig)
})

Claude Code stores OAuth tokens (and legacy API keys) through a SecureStorage interface with two concrete implementations: macOS Keychain and plaintext fallback. The adapter selects the right implementation at runtime and composes them with a createFallbackStorage() combinator.

macOS Keychain storage

Credentials are stored in the macOS Keychain as a generic password item using Apple's security(1) command-line tool. The service name is derived from a stable hash of the config directory path so multiple Claude instances with different CLAUDE_CONFIG_DIR values get separate keychain entries:

// macOsKeychainHelpers.ts — service name derivation
export function getMacOsKeychainStorageServiceName(
  serviceSuffix: string = '',
): string {
  const isDefaultDir = !process.env.CLAUDE_CONFIG_DIR
  const dirHash = isDefaultDir
    ? ''
    : `-${createHash('sha256').update(configDir).digest('hex').substring(0, 8)}`
  return `Claude Code${OAUTH_FILE_SUFFIX}${serviceSuffix}${dirHash}`
}

The credential JSON is serialized to hex before being written. This avoids escaping issues in security(1)'s argument parser, and also defeats naive plaintext-grep rules in enterprise endpoint security tools (e.g. CrowdStrike):

// macOsKeychainStorage.ts — write path
const hexValue = Buffer.from(jsonString, 'utf-8').toString('hex')

// Prefer stdin so process monitors see only "security -i", not the payload
const command =
  `add-generic-password -U -a "${username}" -s "${serviceName}" -X "${hexValue}"\n`

if (command.length <= SECURITY_STDIN_LINE_LIMIT) {
  result = execaSync('security', ['-i'], { input: command })
} else {
  // Payload too large for stdin buffer (4032B limit): fall back to argv
  result = execaSync('security', ['add-generic-password', '-U', ...])
}

// macOsKeychainHelpers.ts
export const KEYCHAIN_CACHE_TTL_MS = 30_000

export const keychainCacheState: {
  cache: { data: SecureStorageData | null; cachedAt: number }
  generation: number  // incremented on every invalidation
  readInFlight: Promise<SecureStorageData | null> | null
} = { cache: { data: null, cachedAt: 0 }, generation: 0, readInFlight: null }

Startup prefetch

keychainPrefetch.ts fires two security subprocesses in parallel at the very top of main.tsx, before the ~65ms of module evaluation. By the time the app's async initializers need credentials, the results are already cached and the sync security spawn is avoided entirely.

// keychainPrefetch.ts — parallel startup reads
export function startKeychainPrefetch(): void {
  if (process.platform !== 'darwin' || prefetchPromise || isBareMode()) return

  // Fire both subprocesses immediately — they run in parallel with
  // each other AND with main.tsx import evaluation (~65ms saved)
  const oauthSpawn  = spawnSecurity(getMacOsKeychainStorageServiceName(CREDENTIALS_SERVICE_SUFFIX))
  const legacySpawn = spawnSecurity(getMacOsKeychainStorageServiceName())

  prefetchPromise = Promise.all([oauthSpawn, legacySpawn]).then(([oauth, legacy]) => {
    if (!oauth.timedOut)  primeKeychainCacheFromPrefetch(oauth.stdout)
    if (!legacy.timedOut) legacyApiKeyPrefetch = { stdout: legacy.stdout }
  })
}

Plaintext fallback storage

On Linux, or when the macOS Keychain is unavailable (e.g. an SSH session), credentials fall back to ~/.config/claude/.credentials.json with permissions set to 0o600. A warning is emitted on every write:

// plainTextStorage.ts — write path
writeFileSync_DEPRECATED(storagePath, jsonStringify(data), { encoding: 'utf8' })
chmodSync(storagePath, 0o600)  // owner-only read/write
return {
  success: true,
  warning: 'Warning: Storing credentials in plaintext.',
}

Fallback storage combinator

On macOS, createFallbackStorage(primary, secondary) wraps both implementations with carefully ordered migration logic:

// fallbackStorage.ts — update() with migration
update(data: SecureStorageData) {
  const primaryDataBefore = primary.read()
  const result = primary.update(data)

  if (result.success) {
    // First-time migration to keychain: delete secondary (plaintext)
    // so the stale .credentials.json doesn't shadow the fresh keychain entry
    if (primaryDataBefore === null) secondary.delete()
    return result
  }

  // Keychain write failed — use plaintext fallback
  const fallbackResult = secondary.update(data)
  if (fallbackResult.success) {
    // Best-effort: remove stale keychain entry so it can't shadow
    // the fresh plaintext data (login loop fix, issue #30337)
    if (primaryDataBefore !== null) primary.delete()
    return { success: true, warning: fallbackResult.warning }
  }

  return { success: false }
}

When a sandboxed command is blocked, the violation event is stored in SandboxViolationStore. Two UI surfaces consume this:

• stderr annotation: annotateStderrWithSandboxFailures() appends a human-readable explanation to the command's stderr when a violation matches.
• SandboxDoctorSection: rendered in the assistant's response area, showing which path or domain was blocked with suggestions on how to allow it.

Violation tag stripping is also needed when displaying error messages in the UI — the <sandbox_violations> XML block that appears in raw stderr is removed for display:

// sandbox-ui-utils.ts — strip violation XML from display text
export function removeSandboxViolationTags(text: string): string {
  return text.replace(
    /<sandbox_violations>[\s\S]*?<\/sandbox_violations>/g,
    '',
  )
}