convez.ai
PluginDevOps & InfraestruturaIntermediário
claude-contrib

Claude Sandbox

claude-contrib/claude-sandbox

Executa Claude Code em Docker isolado com acesso seguro ao seu projeto

Ver no GitHub
InicialPluginScore · de 0 a 100

Plugin 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-sandbox

1 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

Estrelas
0
Forks
0
Acompanhando
1
Saúde
37%
Último commit
há 4 dias
Versão
v0.22.4
Issues abertas
0
Contribuidores
4

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.

Claude CI Release Docker License: MIT

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:

ModeTriggerWhat happens
Forward (default)claudeFinds the host claude binary and runs it directly
Sandboxclaude --sandboxLaunches 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

Demo

The sandbox container comes pre-configured with:

  • Nix flakes — auto-activates flake.nix if 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 $PWD outside 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 — ~/.cache and /nix use 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 — $HOME is 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_DIR is 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-dir or --plugin-dir is mounted read-only at the same absolute path inside the container
  • Credentials — API keys, cloud provider tokens, and GH_TOKEN are forwarded via environment variables (see Configuration)
  • gh claude state — {XDG_STATE_HOME:-~/.local/state}/gh/claude is mounted read-write so the gh-claude extension can persist session data inside the container
  • SSH agent — forwarded when SSH_AUTH_SOCK is set
  • Caches — ~/.cache and /nix use 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

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:

ArgumentSandbox behaviour
--add-dir DIRThe directory is bind-mounted read-only into the container at the same absolute path, then forwarded to claude inside the sandbox
--plugin-dir DIRThe 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:

  1. A .devcontainer/devcontainer.json or .devcontainer.json in the project root
  2. A running devcontainer with the devcontainer.local_folder label 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:

VariableDescription
CLAUDE_CONFIG_DIRClaude Code config directory — defaults to ~/.config/claude, must be under ~/.config
GIT_CONFIG_GLOBALGit global config file — defaults to ~/.config/git/config, must be under ~/.config
CLAUDE_SANDBOXAlways run in sandbox mode — equivalent to passing --sandbox on every invocation
DEBUGEnable 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 claude once inside the sandbox to log in — the credentials will be saved in CLAUDE_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

RepoWhat it provides
claude-extensionsHooks, context rules, session automation
claude-featuresDevcontainer features for Claude Code and Anthropic tools
claude-languagesLSP language servers — completions, diagnostics, hover
claude-sandbox ← you are hereSandboxed Docker environment for Claude Code
claude-servicesMCP servers — browser, filesystem, sequential thinking
claude-statusLive status line — context, cost, model, branch, worktree

License

MIT — use it, fork it, extend it.

Ver o original no GitHub

Bom para

Relacionados