claude-sandbox Technical Wiki

Pages

1. OverviewWhat claude-sandbox is, its core design goals (isolation without Container Use, host worktree as source of truth), and how it integrates with Superset workspaces and Claude Code.
2. Setup and Superset IntegrationPrerequisites, building the image, copying the .superset/ launcher into a repo, configuring a Superset agent, and the first workspace launch flow.
3. The launch.sh LauncherThe host-side script that performs preflight checks, detects prompts via argv/env/stdin, computes stable container names, decides between docker run and docker exec for reattach, and assembles all Docker arguments.
4. Mount Strategies: Worktrees, Symlinks, and GitHow launch.sh bind-mounts the worktree, resolves .git worktree pointers by mounting the parent .git directory, scans external symlinks and mounts their targets, and optionally mounts ~/.ssh read-only.
5. Container Image and EntrypointThe Dockerfile that builds an Ubuntu 24.04 image with Claude Code, uv, Node 22, ripgrep, and a UID-1000 claude user; the minimal entrypoint.sh that sources /workdir/.env before exec.
6. Environment Variables, Customization, and TroubleshootingAll CLAUDE_SANDBOX_* host and container variables, ANTHROPIC_* forwarding, network modes, per-project Dockerfile extension, and the documented failure modes with exact fixes.