Claude Sandbox
claude-contrib/claude-sandbox
Executa Claude Code em Docker isolado com acesso seguro ao seu projeto
Ver no GitHubPlugin que executa Claude Code em um container Docker isolado, com acesso controlado ao repositório do projeto e ferramentas de desenvolvimento via Nix flakes. Oferece segurança de sandbox sem comprometer a autonomia do Claude para editar código e acessar o contexto do projeto.
Instalação
npx convez-ai claude-contrib/claude-sandbox1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Executar Claude Code em ambiente isolado para proteger o host
- Desenvolver com acesso às mesmas ferramentas do seu ambiente (Nix flakes)
- Colaborar com Claude em repositórios completos de forma segura
- Integrar Claude em CI/CD com sandboxing automático
Veredito

Ferramenta robusta que resolve um problema real: executar Claude Code com segurança sem sacrificar contexto de projeto. Implementação técnica sólida com suporte a Nix, volumes persistentes e detecção de devcontainers. Recomendado para equipes que precisam de isolamento com autonomia.
README
A tradução para o português deste README ainda está na fila.
Claude Sandbox
Sandboxed Docker environment for Claude Code — full autonomy with reduced access to host state.
Run Claude Code in an isolated Docker container with bypassPermissions enabled, Nix flake support, your git repo root mounted read-write (worktree-aware), and automatic devcontainer network detection. One command, two modes: forward to the host binary by default, or sandbox with a flag.
Claude Sandbox is an unofficial community project and is not affiliated with, endorsed by, or sponsored by Anthropic.
How It Works
The claude wrapper script sits in your $PATH ahead of the real binary:
| Mode | Trigger | What happens |
|---|---|---|
| Forward (default) | claude | Finds the host claude binary and runs it directly |
| Sandbox | claude --sandbox | Launches Claude Code inside a Docker container with sandbox-scoped permissions |
claude --sandbox "fix the bug"
└── wrapper detects --sandbox, resolves host identity, volumes, network
└── docker compose starts container, mounts ~/.config (ro), repo root (rw), SSH agent
└── claude-exec.sh creates user (matching host UID/GID), drops privileges
└── claude runs as your user inside the sandbox

The sandbox container comes pre-configured with:
- Nix flakes — auto-activates
flake.nixif present, giving Claude access to the same compilers, linters, and dev tools you use — an equal developer in your environment - Project mount — the git repo root is mounted read-write (falling back to
$PWDoutside a repo), so Claude can read and edit code across the entire repo including worktrees; the container's working directory is set to your actual$PWD - User identity — the container dynamically creates a user matching your host UID, GID, and username, so file ownership on bind mounts is always correct
- Persistent volumes —
~/.cacheand/nixuse dedicated Docker volumes so Nix store and cached artifacts survive container restarts without re-downloading - Devcontainer network — auto-detects a running devcontainer and joins its Docker network, giving Claude access to the same databases, APIs, and services your environment exposes
Isolation Model
The sandbox uses Docker process isolation — Claude runs in a separate container as your user and is isolated from most host state by default. It still has access to the mounts, environment variables, credentials, and network paths listed below.
Isolated:
- Home directory —
$HOMEis not mounted;~/.ssh,~/.gnupg,~/.aws, and other dotfiles are inaccessible - System files — no access to
/etc,/usr, or host-installed packages - Host processes — cannot see, signal, or interact with processes outside the container
- Package installation —
apt,brew, and other system package managers are unavailable
Shared (by design):
~/.config— mounted read-only so that git config (GIT_CONFIG_GLOBAL) and other host settings are available without manual setup;CLAUDE_CONFIG_DIRis mounted separately as read-write so Claude Code can persist its own state. Both must point to paths under~/.config(see Configuration)- Git repo root — mounted read-write for code editing (worktree-aware; falls back to
$PWD) - Extra directories — any path passed via
--add-diror--plugin-diris mounted read-only at the same absolute path inside the container - Credentials — API keys, cloud provider tokens, and
GH_TOKENare forwarded via environment variables (see Configuration) gh claudestate —{XDG_STATE_HOME:-~/.local/state}/gh/claudeis mounted read-write so the gh-claude extension can persist session data inside the container- SSH agent — forwarded when
SSH_AUTH_SOCKis set - Caches —
~/.cacheand/nixuse dedicated Docker volumes (container-only, not host-shared) that persist across container restarts - Network — outbound internet access (required for the Claude API); automatically joins a running devcontainer's Docker network when detected (see Devcontainer Network)
The sandbox reduces host exposure by avoiding a full home-directory mount and by keeping system files and host processes outside the container. It is not a security boundary for data you explicitly share with it, such as your repo, forwarded credentials, SSH agent, devcontainer network, or Docker socket.
Requirements
- Docker with the Compose plugin (
docker) - Claude Code (
claude) - Gum (
gum)
macOS (Homebrew):
brew install --cask docker
brew install gum
Nix:
nix profile install nixpkgs#gum
Install claude separately: Claude Code installation guide
Installation
Using zinit
zinit light claude-contrib/claude-sandbox
Using Nix flakes
nix profile install github:claude-contrib/claude-sandbox
Or in your flake.nix inputs:
inputs.claude-sandbox.url = "github:claude-contrib/claude-sandbox";
Using sheldon
[plugins.claude-sandbox]
github = "claude-contrib/claude-sandbox"
Manual (zsh)
git clone https://github.com/claude-contrib/claude-sandbox.git ~/.claude-sandbox
echo 'source ~/.claude-sandbox/claude-sandbox.plugin.zsh' >> ~/.zshrc
source ~/.claude-sandbox/claude-sandbox.plugin.zsh
Manual (bash)
The claude wrapper is a plain bash script. Add it to your PATH in ~/.bashrc:
git clone https://github.com/claude-contrib/claude-sandbox.git ~/.claude-sandbox
echo 'export PATH="$HOME/.claude-sandbox:$PATH"' >> ~/.bashrc
export PATH="$HOME/.claude-sandbox:$PATH"
Usage
# Forward to host claude (default)
claude
# Run in Docker sandbox
claude --sandbox
# Sandbox with args
claude --sandbox --print "hello"
# Show sandbox wrapper help
claude --sandbox-help
# Debug tracing
DEBUG=1 claude --sandbox
Argument Handling
Some Claude CLI arguments are intercepted by the sandbox wrapper and handled specially before being forwarded to the container:
| Argument | Sandbox behaviour |
|---|---|
--add-dir DIR | The directory is bind-mounted read-only into the container at the same absolute path, then forwarded to claude inside the sandbox |
--plugin-dir DIR | The directory is bind-mounted read-only into the container at the same absolute path, then forwarded to claude inside the sandbox |
# Mount an extra directory read-only inside the sandbox
claude --sandbox --add-dir /path/to/docs
# Mount a plugin directory read-only inside the sandbox
claude --sandbox --plugin-dir /path/to/plugins
Devcontainer Network
If your project uses a devcontainer (VS Code, Codespaces, devcontainer CLI), the sandbox automatically detects the running devcontainer and joins its Docker network. This lets Claude reach services (databases, APIs, etc.) defined in the devcontainer without any extra configuration.
Detection requires:
- A
.devcontainer/devcontainer.jsonor.devcontainer.jsonin the project root - A running devcontainer with the
devcontainer.local_folderlabel matching the project
User-defined compose networks provide DNS-based service discovery.
When a network is detected, you'll see:
Detected devcontainer network 'myproject_default'
Configuration
The full list of host environment variables forwarded to the sandbox is defined in claude-sandbox.env.yml. Forwarded variables may include API keys, cloud provider credentials, proxy settings, and GitHub tokens; anything forwarded should be treated as available to Claude Code and to processes it runs inside the container.
These additional variables are handled specially:
| Variable | Description |
|---|---|
CLAUDE_CONFIG_DIR | Claude Code config directory — defaults to ~/.config/claude, must be under ~/.config |
GIT_CONFIG_GLOBAL | Git global config file — defaults to ~/.config/git/config, must be under ~/.config |
CLAUDE_SANDBOX | Always run in sandbox mode — equivalent to passing --sandbox on every invocation |
DEBUG | Enable debug tracing (set -x) |
Settings
The host ~/.config directory is bind-mounted read-only into the container at the same absolute path, so git config and other host settings are available. CLAUDE_CONFIG_DIR is mounted separately as read-write, so Claude Code can persist its own state. The sandbox ships with a baked-in docker/settings.json that enables bypassPermissions; it is passed via --settings and always takes final precedence.
Sessions
Sessions are shared between host and sandbox modes, so you can start a conversation on the host and continue it in the sandbox (or vice versa):
# Start on the host
claude
# Later, resume the same session in the sandbox
claude --sandbox --resume <session-id>
macOS note: The host Claude Code stores its auth credentials in the macOS Keychain, which is not available inside the container. Run
claudeonce inside the sandbox to log in — the credentials will be saved inCLAUDE_CONFIG_DIR(defaults to~/.config/claude) and reused on subsequent launches.
Troubleshooting
Enable debug tracing to see every command the wrapper executes:
DEBUG=1 claude --sandbox
If the container is in a bad state (stale Nix store, corrupted cache), remove the Docker volumes and start fresh:
docker volume rm claude-nix claude-cache
The claude-contrib Ecosystem
| Repo | What it provides |
|---|---|
| claude-extensions | Hooks, context rules, session automation |
| claude-features | Devcontainer features for Claude Code and Anthropic tools |
| claude-languages | LSP language servers — completions, diagnostics, hover |
| claude-sandbox ← you are here | Sandboxed Docker environment for Claude Code |
| claude-services | MCP servers — browser, filesystem, sequential thinking |
| claude-status | Live status line — context, cost, model, branch, worktree |
License
MIT — use it, fork it, extend it.