IDE integration does not work inside Docker Desktop sandboxes

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

When running Claude Code inside a Docker Desktop sandbox (docker sandbox run claude ~/my-project), the IDE integration with VS Code on the macOS host does not work. The /ide command cannot discover or connect to the VS Code extension's WebSocket server.

Environment

• Host: macOS with Docker Desktop (sandboxes feature)
• Sandbox: Ubuntu 25.10 (aarch64) microVM
• VS Code: Running natively on macOS host with anthropic.claude-code extension
• Claude Code: Running inside the Docker sandbox

Root Cause Analysis

After deep research into the IDE communication protocol, the following issues prevent the connection:

1. WebSocket server is unreachable from the sandbox

The VS Code extension binds its WebSocket server to 127.0.0.1:<port> on the host. Docker sandboxes run inside a microVM with hypervisor-level isolation. The sandbox cannot access host localhost services — the VM boundary prevents direct TCP access. The sandbox's HTTP proxy (host.docker.internal:3128) only supports HTTP/HTTPS, not WebSocket upgrades or raw TCP.

2. Lock files are not shared

The lock file at ~/.claude/ide/<port>.lock exists on the macOS host filesystem. The sandbox only syncs the workspace directory, not the user's ~/.claude/ directory.

3. Environment variables are not forwarded

CLAUDE_CODE_SSE_PORT, ENABLE_IDE_INTEGRATION, and FORCE_CODE_TERMINAL are set by the VS Code extension in the host's integrated terminal, but the sandbox launches Claude Code in its own isolated shell.

4. PID validation fails across VM boundary

The CLI validates the IDE connection using ps -o ppid= -p <pid> (see #14153). The VS Code PID from the host doesn't exist inside the sandbox VM, so validation fails.

Existing Env Vars That Could Help

• CLAUDE_CODE_IDE_HOST_OVERRIDE — could point to host.docker.internal if WebSocket traffic could traverse the boundary
• CLAUDE_CODE_IDE_SKIP_VALID_CHECK — could bypass PID validation

Suggested Solutions

Short-term (Claude Code side):

1. Allow the VS Code extension to optionally bind to 0.0.0.0 instead of 127.0.0.1 (opt-in setting), so it's reachable from sandbox VMs via host.docker.internal
2. Document CLAUDE_CODE_IDE_HOST_OVERRIDE and CLAUDE_CODE_IDE_SKIP_VALID_CHECK for sandbox/container use cases
3. Support passing the auth token via environment variable (eliminating the lock file dependency)
4. Skip or relax PID validation when IS_SANDBOX=1 is set (Docker sandbox sets this automatically)

Longer-term (coordination with Docker):

1. Work with Docker to support WebSocket/TCP port forwarding in sandboxes (similar to docker run -p)
2. Explore an alternative communication channel that works through the sandbox's HTTP proxy

Related Issues

• #14153 — Selection context not passed in DevContainer (related PID validation issue)
• Docker sandbox networking docs: https://docs.docker.com/ai/sandboxes/network-policies/
• Docker sandbox architecture docs: https://docs.docker.com/ai/sandboxes/architecture/

Impact

Docker Desktop sandboxes are a compelling security model for running AI coding agents. However, losing IDE context (file selections, diagnostics, diff views) significantly reduces the value of the integration. As sandbox adoption grows, this will affect more users.