Claude Sandbox
ac3charland/claude-sandbox
Container isolado para rodar Claude Code com segurança em modo YOLO
Ver no GitHubAmbiente isolado em container para executar Claude Code em modo YOLO contra cópias seguras de projetos. Utiliza git worktrees e firewall default-deny para reduzir o raio de blast, permitindo que agentes de IA rodem código com segurança sem acesso ao filesystem do host ou internet aberta.
Instalação
npx convez-ai ac3charland/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 agentes de IA em projetos sem risco ao sistema host
- Permitir que Claude Code acesse registros de dependências com segurança
- Isolar modificações de código em git worktrees controladas
Veredito

Solução técnica robusta para quem precisa rodar agentes de IA em modo experimental sem comprometer a máquina host. Requer Docker, devcontainer CLI e configuração inicial, mas oferece isolamento real com firewall default-deny e gerenciamento automático via git worktrees.
README
A tradução para o português deste README ainda está na fila.
Claude Code Sandbox
A portable devcontainer setup for running Claude Code in YOLO mode
(--dangerously-skip-permissions) against an isolated copy of a project,
behind a default-deny firewall. It isolates the agent from your host filesystem
and the open internet, reducing the blast radius to a contained workspace plus a
short allowlist of domains. The recommended isolation strategy is a git worktree
(--worktree), though a manual clone works too.
Repo contents
bin/claude-sandbox— the user-facing command: creates a git worktree for the current repo and launches Claude Code against it. Put on yourPATHbysetup.sh.setup.sh— addsbin/to yourPATH(idempotent; detects your shell rc).run.sh— internal launcher invoked bybin/claude-sandbox: resolves the worktree gitdir, builds/starts the container, and drops you into Claude Code..devcontainer/devcontainer.json— container definition (network caps, mounts, env, firewall hook)..devcontainer/Dockerfile— Node + Python (viauv) + Rust toolchains. Multi-arch (Intel and Apple Silicon)..devcontainer/init-firewall.sh— default-deny egress firewall; allowlists only the registries the toolchains need..env— not committed. Holds your auth tokens (Claude OAuth, optional GitHub PAT). Recreated per machine (see setup)..gitignore— keeps.envout of version control.
Prerequisites (per machine)
- macOS, Intel or Apple Silicon — the image is multi-arch, so no edits are needed for either. A new machine just rebuilds the image from scratch the first time (slow once, cached after).
- Docker Desktop, installed and running. Verify with
docker info(this checks the daemon, not just the CLI). - Node.js, plus the devcontainer CLI:
npm install -g @devcontainers/cli - Claude Code on the host:
npm install -g @anthropic-ai/claude-code— needed only to mint the token in step 2. - An active Claude Pro/Max subscription (the token bills against it).
First-time setup on a new machine
-
Clone this repo. Either clone it to
~/claude-sandbox, or use the self-locatingrun.sh(see "Portability" below) so it can live anywhere. -
Mint a long-lived, subscription-billed token:
claude setup-tokenCopy the
sk-ant-oat01-...value it prints — it is not saved anywhere else. -
Create
.envin the repo root (this file is gitignored — never commit it):export CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...your token...chmod 600 .env -
Create a GitHub personal access token (PAT) — only needed if you want the agent to push branches and open PRs from inside the sandbox. Create a fine-grained token at
https://github.com/settings/personal-access-tokens/new, scoped to the repos you'll work on, with these repository permissions:- Contents → Read and write — push commits and branches
- Pull requests → Read and write — open PRs via
gh pr create - Metadata → Read-only — required baseline (selected automatically)
Append it to
.env. Inside the container, SSH remotes are rewritten to HTTPS so this token is used automatically; your host git keeps using SSH.export GITHUB_TOKEN=github_pat_...your token... -
Put the command on your
PATH:./setup.shThis appends a single
PATHline to your shell rc (idempotent) and makes the scripts executable. Open a new shell afterward. Alias it however you like, e.g.alias claudeyolo='claude-sandbox'. -
Verify prerequisites:
docker infoanddevcontainer --versionshould both succeed.
Usage (per project)
Once setup.sh has put claude-sandbox on your PATH, run it from inside any
git repo. It creates an isolated worktree at ~/claude-worktrees/<repo>/<name>
on the host, then mounts only that checkout into the container — so Claude works
on an isolated copy and your real working tree is never exposed. The worktree gets
its own branch and can be reviewed and merged normally when the session ends.
# Auto-named worktree (claude-<timestamp>):
claude-sandbox
# Named worktree:
claude-sandbox -b feature-auth
# Rebuild the container image first:
claude-sandbox -r -b feature-auth
# Anything else is passed straight through to `claude`:
claude-sandbox -b feature-auth --model opus
Run claude-sandbox -h for the full flag list.
Under the hood: run.sh
bin/claude-sandbox is the ergonomic layer; the actual container launch lives in
run.sh, which takes a ready-made workspace path plus any claude flags:
run.sh [--rebuild|-r] /path/to/workspace [claude flags...]
You normally never call this directly — but it means worktree management and
container plumbing stay cleanly separated, and you can point run.sh at a
hand-made clone if you ever want to bypass the worktree workflow (see
"Alternative: manual clone" below).
Alternative: manual clone
If you prefer full control over the isolated copy, clone the repo yourself and pass
the clone path directly — no --worktree needed:
git clone ~/code/projects/myproject ~/code/projects/myproject-sandbox
cd ~/code/projects/myproject-sandbox && git switch -c sandbox/attempt-1
~/claude-sandbox/run.sh ~/code/projects/myproject-sandbox
Pull the work back from your real repo once done:
cd ~/code/projects/myproject
git fetch ~/code/projects/myproject-sandbox sandbox/attempt-1:sandbox/attempt-1
git diff main..sandbox/attempt-1
git merge sandbox/attempt-1
Notes: why these files diverge from Anthropic's reference
These are hard-won fixes. If you ever re-pull the upstream .devcontainer to take
updates, re-apply them or you'll reintroduce the bugs:
- Token in
containerEnv, notremoteEnv.remoteEnvis not reliably injected by a baredevcontainer exec;containerEnvis, and every exec inherits it. Confirm with/statusinside Claude Code — the Auth token field should readCLAUDE_CODE_OAUTH_TOKEN(subscription billing). Never setANTHROPIC_API_KEYanywhere in the chain — it silently takes precedence and switches you to pay-per-token API billing. ipset add -existin the firewall, so CDN-shared IPs (e.g.pypi.organdfiles.pythonhosted.org, both on Fastly) don't abort the fail-closed script when the second domain re-adds an IP the first already added.- Telemetry domains removed from the firewall allowlist (
statsig.anthropic.comet al.).statsig.anthropic.comdoesn't resolve, which would abort the script, and telemetry is disabled viaCLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1anyway. - No comments inside the firewall's
for domain in \ ...list. A#inside a backslash-continued list silently truncates the list and breaks parsing. Keep annotations out of that loop (or convert it to a bash array, where comments are legal). - System Python for
uv(UV_PYTHON_DOWNLOADS=never,UV_PYTHON_PREFERENCE=only-system), souvnever tries to fetch a standalone interpreter from the GitHub release-asset CDN, which the firewall doesn't allow. - Single mount at
/home/node/.claude(claude-sandbox-config). Two volumes at one target fails container creation; the stable-named volume persists trust and session state across rebuilds and across different project clones.
First launch on a fresh machine
The named Docker volumes (claude-sandbox-config, command history) start empty, so
the first build runs from scratch (no cache) and Claude Code will ask you to trust
/workspace once. After that, trust and config persist.