How to use sandbox mode with SDK?

[chad-fossa]

based on https://www.anthropic.com/engineering/claude-code-sandboxing

Looks like sandboxing is available generally.

Based on https://code.claude.com/docs/en/sandboxing

Looks like /sandbox is available in the UI

How to enable it in the SDK? Is it just "IS_SANDBOX=1" env var, or is there additional config available? does it respect workingDirectory param?

[evrimalacan]

I am also interested in the sandbox support.

About IS_SANDBOX variable: I think it serves a different purpose than the recent feature they announced as Claude Code Sandboxing. This flag enables the agent to run as the root user with bypassPermissions. I am not aware of any other use case.

[mishkinf]

Bug Report: Sandbox mode stalls due to blocked file watcher

I've been trying to use sandbox mode programmatically and discovered a bug that causes queries to hang.

Environment

• SDK version: 0.1.75
• Platform: macOS (Darwin 25.1.0)
• Node.js: v22.21.1

Reproduction

import { query } from '@anthropic-ai/claude-agent-sdk';

const response = query({
  prompt: 'Say hello',
  options: {
    model: 'claude-sonnet-4-5-20250929',
    sandbox: { enabled: true },
    permissionMode: 'acceptEdits'
  }
});

for await (const message of response) {
  console.log(message.type); // Only prints 'system', then hangs
}

Expected Behavior

Query completes normally with sandbox isolation.

Actual Behavior

Query emits system init message then hangs indefinitely. stderr shows:

Error: UNKNOWN: unknown error, watch '/var/folders/.../T/claude-mcp-browser-bridge-<user>'
    at FSWatcher.<computed> (node:internal/fs/watchers:254:19)
    at watch (node:fs:2549:36)

Root Cause Analysis

1. When sandbox: { enabled: true }, the SDK uses macOS's sandbox-exec to create an isolated environment
2. The Claude Code CLI process tries to watch /var/folders/.../T/claude-mcp-browser-bridge-* for MCP browser bridge communication
3. The macOS sandbox blocks this watch() syscall
4. This causes an unhandled promise rejection that stalls the process

What Doesn't Help

• ignoreViolations: { file: ['/var/folders/*'] } - only catches app-level violations, not OS-level blocks
• Environment variables - the watcher runs regardless
• @anthropic-ai/sandbox-runtime is installed

Suggested Fix

The sandbox profile should either:

1. Allow watching the SDK's own temp directories
2. Or disable file watchers for MCP browser bridge when sandbox is enabled

Without sandbox, queries complete normally (system → assistant → result).

[hughescr]

I'm hitting the same issue using the SDK on macOS - the SDK internally is trying to watch a unix socket, which it can't do on macOS:

Error: EOPNOTSUPP: unknown error, watch '/var/folders/1j/l769161n2xb6qfm9hm9gw1tw0000gn/T/9aeccxl6i68.sock'
    at watch (unknown)
    at new FSWatcher (node:fs:29:31)
    at watch (node:fs:296:23)
    at CFB (/Users/craig/code/hughescr/isambard/node_modules/@anthropic-ai/claude-agent-sdk/cli.js:448:6515)
    at J23 (/Users/craig/code/hughescr/isambard/node_modules/@anthropic-ai/claude-agent-sdk/cli.js:448:11678)
    at _watchWithNodeFs (/Users/craig/code/hughescr/isambard/node_modules/@anthropic-ai/claude-agent-sdk/cli.js:448:6996)
    at _handleFile (/Users/craig/code/hughescr/isambard/node_modules/@anthropic-ai/claude-agent-sdk/cli.js:448:7722)
    at _addToNodeFs (/Users/craig/code/hughescr/isambard/node_modules/@anthropic-ai/claude-agent-sdk/cli.js:448:10730)
    at processTicksAndRejections (native:7:39)

The Claude Code CLI works for me just fine in sandbox mode - but the SDK seems to be attempting this fs.watch on a unix socket which is EOPNOTSUPP on macOS.

[hughescr]

const fs = require('fs');
const net = require('net');
const sock = `/tmp/test-${Date.now()}.sock`;

net.createServer().listen(sock, () => {
  try { fs.watch(sock); console.log('watch succeeded'); }
  catch (e) { console.log('watch failed:', e.code, e.message); }
  fs.unlinkSync(sock);
  process.exit();
});

On linux: watch succeeded
On macOS: watch failed: EOPNOTSUPP EOPNOTSUPP: unknown error, watch '/tmp/test-1767120030846.sock'

[hughescr]

Note: bun gives EOPNOTSUPP whereas regular nodejs gives UNKNOWN for the error.