sandbox-vibe

English

Sandbox Docker plug-and-play para vibe coding assistido por IA — Claude Code rodando isolado, com bootstrap idempotente de plugins/MCPs e limites de segurança aplicados por padrão.

Quando você deixa um agente de IA editar seu código, três coisas precisam valer ao mesmo tempo:

1. O agente não pode apagar ~/, vazar credenciais ou rodar rm -rf no host.
2. O agente pode ler e escrever apenas nos projetos que você autorizar.
3. Você não perde tempo reconfigurando plugins, MCPs e language servers toda vez que sobe um novo container.

O sandbox-vibe entrega os três através de um template Docker de quatro arquivos, distribuído como esta CLI.

Quickstart

A partir do projeto que você quer sandboxar:

npx sandbox-vibe init     # wizard interativo
npx sandbox-vibe up       # build + sobe o REPL do Claude

O wizard pergunta o caminho do workspace, sibling mounts opcionais, sua stack (suporte LSP para PHP / .NET / Python / Go / Rust), plugins, MCP servers e limites de recursos. Ele grava os quatro arquivos do sandbox mais um config.json em .sandbox-vibe/ na raiz do projeto e atualiza o .gitignore para você.

O primeiro up roda o bootstrap (instala marketplaces, plugins, MCPs, language servers) e abre o REPL do Claude. Todo up subsequente pula o bootstrap e abre o REPL em milissegundos.

Quando você muda a lista de plugins ou MCPs, basta rodar up de novo — a CLI detecta a mudança automaticamente e refaz o bootstrap uma vez.

O que você ganha

• Isolamento enforcado pelo kernel — usuário não-root, cap_drop: ALL, no-new-privileges, pids: 128, tmpfs /tmp efêmero. O agente não consegue alcançar o sistema de arquivos do host, suas chaves SSH ou seus outros projetos.
• Volume do home do Claude per-project — sessões, tokens de marketplace e plugins instalados ficam restritos ao projeto que os criou. Sem vazamento de credenciais entre projetos.
• Bootstrap idempotente — plugins, MCPs e language servers instalam uma vez no primeiro run e são pulados a partir daí. Mudar a configuração dispara um bootstrap novo automaticamente.
• Saída para a internet funciona, LAN do host não — network_mode: bridge permite que MCPs alcancem a internet pública mas bloqueia acesso ao seu roteador, NAS ou outros dispositivos da LAN.

Requisitos

• Node.js 20 ou superior (para a CLI em si).
• Docker Desktop ou Docker Engine com Compose v2 (para o container do sandbox).

Comandos

| Comando | O que faz | | --- | --- | | sandbox-vibe init | Wizard interativo que escreve .sandbox-vibe/ com os quatro arquivos do sandbox e um config.json. | | sandbox-vibe init --non-interactive | Mesma coisa, mas usa defaults (adequado para CI). | | sandbox-vibe init --force | Sobrescreve um .sandbox-vibe/ existente sem confirmação. | | sandbox-vibe up | Builda as imagens do sandbox e cai no REPL do Claude. | | sandbox-vibe up --shell | Igual, mas abre um shell bash em vez do REPL do Claude. | | sandbox-vibe build | Builda as imagens do sandbox sem iniciar o REPL (--no-cache para reconstruir do zero). | | sandbox-vibe reset --all | Remove o volume de home do projeto — sessões, plugins e marker de bootstrap (--yes pula a confirmação). | | sandbox-vibe reset --marker | Re-executa o bootstrap no próximo up, mantendo sessões e plugins instalados. | | sandbox-vibe logs | Imprime o log de bootstrap do projeto a partir do volume de home. | | sandbox-vibe bump-marker | Força re-bootstrap no próximo up (útil se você editou o entrypoint à mão). |

Documentação

A documentação completa fica no repositório GitHub:

• Architecture — split base / override, fases do bootstrap, defaults de segurança, threat model.
• Manual setup — clonar e editar o template à mão, sem a CLI.
• Customization — adicionar um language server, adicionar um MCP server, mudar limites de CPU / memória / PID.
• Troubleshooting — mensagens de erro comuns e causas raiz.
• Security — disclosure de vulnerabilidade, fronteira do threat model.
• Contributing — fluxo de PR, regras de commit, setup local.
• Changelog — histórico de versões.

Licença

MIT — veja LICENSE.