Claude Sandbox for VS Code

Makes VS Code the IDE of a Claude Code session that runs inside claude-sandbox: Claude sees your editor selection, shows proposed edits as diffs in VS Code for you to accept or reject, and reads the workspace's diagnostics. It speaks Claude Code's IDE protocol (MCP over a WebSocket), the role Anthropic's own extension plays for an unsandboxed Claude. claude-sandbox itself is not changed.

Status: stage 1. The bridge works; the terminal launcher is not built yet. Run Claude Sandbox: Copy launch command and paste the copied claude --settings '…' into a devcontainer terminal in the workspace folder.

How it works

1. The extension listens on a Unix socket in the workspace root (.claude-sandbox-vscode-<port>.sock, mode 0600), which the jail can see.

2. claude-sandbox is given --settings with CLAUDE_CODE_SSE_PORT and SessionStart/SessionEnd hooks. Inside the jail the start hook starts socat (TCP 127.0.0.1:<port> to the socket) unless it already runs, and once it listens writes Claude Code's lock file (~/.claude/ide/<port>.lock, with the auth token), never over an existing one. The end hook removes it on a real exit (not on /clear or /resume).

3. Claude Code connects; the extension checks the token and serves four MCP tools: openDiff, close_tab, closeAllDiffTabs, getDiagnostics.

One linked Claude session per VS Code window, in a devcontainer with claude-sandbox installed: while it is connected, another connection is refused. Other Claude sessions run sandboxed without the IDE link.

The full design and the protocol notes are in docs/design.md.

Related MCP server: vscode-agent-bridge

Security

The extension host runs outside the sandbox with your full privileges, and anything inside the sandbox can read the token and reach the socket, so every message is treated as hostile (trust boundary):

• Only the four tools above; nothing that runs code, opens URLs or writes files.

• openDiff reads only real paths inside a workspace folder, never in .git, one path component at a time without following symlinks (a symlink swapped in after the check is refused).

• The extension never writes a workspace file: Accept hands the text back and Claude writes it from inside the sandbox. Closing a diff is a rejection. Accept and Reject work from either side of the diff.

• Diagnostics and selections are sent only for workspace files.

• The host never writes into the sandbox's ~/.claude; the in-sandbox hook writes the lock file, and every value in its shell command is validated and quoted. The host deletes nothing in the workspace either (its own socket goes when the link closes).

• The hand-written WebSocket server has no runtime dependencies: messages are capped at 16 MiB (from the frame header), at most 4 connections in their handshake and one linked session, a handshake timeout, backpressure on output (a client that stops reading is not read, and is dropped past 32 MiB queued), a ping every 30 s (a client that answers nothing is dropped), permessage-deflate refused, parsed JSON never merged into objects, and nothing from the sandbox logged unescaped.

• The token appears in claude-sandbox's argv. Other users cannot use it (the socket is 0600); processes running as you are already trusted.

Every rule has a test in test/hostile/ or test/unit/; the mapping is in docs/design.md.

Out of scope (residual risk). VS Code on a workspace the sandbox can write is exposed whether or not this extension is installed: .vscode/settings.json (interpreter paths, tasks) and .git/config (fsmonitor, filter drivers) run on the host. Keep such workspaces untrusted in VS Code's Workspace Trust, or review the agent's changes to them before reopening.

Development

Linux, Node 22.18 or later (tests run the TypeScript directly), and socat for the end-to-end hook test.

npm ci
npm run typecheck
npm test            # node --test: test/unit and test/hostile
npm run build       # esbuild → dist/extension.cjs
npm run package     # .vsix via @vscode/vsce

License

MIT, Copyright (c) 2026 Diamond Light Source Ltd.