Docker Sandboxes para executar agentes de codificação

O Docker Sandboxes executa um agente de codificação, como Claude Code, Codex, Copilot ou Cursor, dentro de uma microVM local. A microVM tem seu próprio kernel e seu próprio Docker Engine e compartilha com o host apenas o diretório do seu projeto. Executá-lo localmente é gratuito.

Se você já aprovou uma centena de prompts de ls e npm test em uma única tarde, sabe como a flag de “pular permissões” (“skip permissions”) é tentadora. Provavelmente também sabe da preocupação com o que o agente poderia fazer no seu notebook com essa flag ativada.

Este artigo aborda o que o sandbox isola, como configurá-lo da instalação à primeira sessão, como trazer as alterações do agente para fora, como ele se compara a outras opções e quanto custa. A ferramenta ainda está em versão pré-1.0 e muda rapidamente.

Por que a autonomia total no seu notebook é arriscada

Um agente de codificação em modo de autonomia total executa comandos de shell, instala pacotes e edita arquivos sem pedir permissão, e faz tudo isso com a sua conta de usuário. Isso significa que seu diretório home, suas chaves SSH, suas credenciais de nuvem e seus serviços locais ficam todos ao alcance dele. Um único rm -rf ou git reset --hard equivocado pode apagar trabalho ainda não commitado.

Prompts de aprovação são a defesa habitual, mas eles anulam o propósito de um agente. Tarefas longas param a cada comando e, depois do vigésimo prompt, a maioria das pessoas aprova sem ler. Uma solução melhor é colocar o agente em um lugar onde ele não possa causar muito estrago, em vez de confiar mais nele. Os argumentos gerais a favor do isolamento de agentes são abordados em running coding agents in YOLO mode safely. Este artigo trata de uma ferramenta específica.

Por que o Docker Sandboxes usa uma microVM, e não um contêiner

Um contêiner Docker comum compartilha o kernel do host. Qualquer processo que tenha acesso ao socket do Docker pode iniciar um contêiner privilegiado que monta o seu sistema de arquivos. A própria documentação sobre a superfície de ataque do daemon do Docker alerta que o daemon é executado como root e que apenas usuários confiáveis devem controlá-lo. Agentes frequentemente precisam do Docker, então o atalho óbvio de montar /var/run/docker.sock entrega a máquina inteira a eles.

A documentação sobre camadas de isolamento do Docker afirma que cada sandbox é uma microVM com seu próprio kernel Linux e seu próprio Docker Engine. O agente pode executar docker build e docker run dentro do sandbox sem a configuração privilegiada que o Docker-in-Docker exige, e o daemon do seu host nunca é envolvido.

Configure um Docker Sandbox de ponta a ponta

Instale a CLI sbx, faça login no Docker, forneça ao agente as credenciais do modelo e então execute sbx run a partir do diretório do seu projeto. O tutorial oficial observa que o seu host não precisa nem do Docker Desktop nem do Docker Engine.

Instale com o comando correspondente ao seu sistema operacional:

# macOS
brew trust docker/tap && brew install docker/tap/sbx

# Windows
winget install Docker.sbx

# Ubuntu: add Docker's apt repo, install, then grant KVM access
curl -fsSL https://get.docker.com | sudo REPO_ONLY=1 sh
sudo apt-get install docker-sbx
sudo usermod -aG kvm $USER
newgrp kvm

No Linux, é necessário o KVM, e seu usuário precisa estar no grupo kvm. O Docker testa e oferece suporte ao sbx no Ubuntu. Para outras distribuições, o repositório sbx-releases disponibiliza arquivos de release, mas o Docker não garante que elas funcionem. Consulte a página de instalação para ver os pré-requisitos de cada plataforma.

Em seguida, inicie uma sessão do Claude Code:

sbx login
sbx secret set anthropic        # skip if you use a Claude subscription
cd ~/my-project
sbx run --name my-project claude

• Chave de API: sbx secret set anthropic salva a chave no seu host. O proxy do sandbox a adiciona às requisições de API do agente, de modo que o agente nunca manipula a chave bruta. Para o Codex, use sbx secret set openai. Se você já exportou a chave no seu shell, sbx secret import --dry-run lista as chaves que o sbx consegue ver, e sbx secret import as salva depois que você confirma cada uma.
• Assinatura: você não precisa de um secret. Com o Claude, digite /login depois que o Claude Code iniciar no sandbox. Com o Codex, o sbx executa primeiro o login da OpenAI no seu host e só então cria o sandbox.

Na primeira execução, o sbx pede que você escolha uma política de rede padrão. Depois disso, o agente é iniciado no modo de autonomia total, então o Claude Code não pedirá permissão e você não precisa passar nenhuma flag. Para usar outro agente, troque claude por codex, copilot, cursor ou gemini.

A pasta do seu projeto é a única parte da sua máquina em que o agente pode escrever, e ele pode excluir qualquer coisa ali. Faça commit ou push antes de começar.

Como trazer o trabalho do agente para fora?

No modo padrão, as edições de um agente no Docker Sandbox aparecem imediatamente na working tree do seu host. Revise-as como você faria normalmente:

git diff

Guias mais antigos, incluindo o repositório de exemplo do quickstart do Docker, mostram uma flag --branch que colocava o agente em uma worktree no host, dentro de .sbx/. Essa flag foi removida no sbx v0.31.0 em favor do modo clone. Se você a usar agora, receberá um erro orientando a usar --clone.

O modo clone mantém o agente longe da sua working tree. Como explica a documentação de fluxo de trabalho com Git, o sbx cria um clone Git privado dentro do sandbox, e o agente trabalha nessa cópia. Nada muda no seu host até que você faça fetch da branch do agente ou que o agente faça push para um remote. Você só pode escolher o modo clone ao criar um sandbox, então passe --clone na primeira execução. Não é possível converter um sandbox existente depois.

Questões práticas

Qual política de rede devo escolher?

O Docker Sandboxes oferece três políticas de rede locais:

• Open permite todo o tráfego.
• Balanced bloqueia o tráfego por padrão, mas permite serviços de desenvolvimento comuns.
• Locked Down bloqueia tudo o que você não permitir explicitamente.

Escolha Balanced para a maior parte do trabalho de frontend. Ela abrange registros de pacotes, plataformas de hospedagem de código e APIs de provedores de IA. Se o seu agente precisar acessar um site que não está na lista, como um site de documentação, execute sbx policy check network <domain> para verificar se ele está bloqueado e, em seguida, libere-o com sbx policy allow network <domain>. Execute sbx policy ls para ver suas regras e remova uma delas com sbx policy rm. Os kits de agentes integrados também podem adicionar suas próprias regras de liberação para cada sandbox, mesmo no modo Locked Down.

O estado é mantido?

Sim. As ferramentas que o agente instala e quaisquer alterações que ele faça no sistema operacional permanecem no sandbox até que você o remova. Executar sbx rm my-project apaga o ambiente e todos os secrets restritos àquele sandbox. Seus secrets globais e a pasta do seu projeto não são afetados.

Como me reconecto?

Para se reconectar a um Docker Sandbox existente, execute sbx run --name my-project. Não é necessário repetir o nome do agente, pois ele é lido do sandbox existente. Executar sbx sem argumentos abre um painel interativo.

Docker Sandboxes vs. contêineres, devcontainers e VMs remotas

Todas as alternativas abrem mão de pelo menos uma de três coisas: isolamento de kernel, acesso seguro ao Docker ou uma política de saída (egress) integrada.

Se o que você realmente precisa é controlar quais ferramentas um agente pode chamar, em vez de isolar o ambiente dele, consulte Docker MCP for AI agents.

Limitações e custo do Docker Sandboxes

Executar sandboxes locais é gratuito. Segundo as notas de release da v0.45.0, os sandboxes na nuvem são experimentais e exigem uma assinatura ativa do Docker Agentic Platform. Você paga pela inferência do modelo com sua própria chave ou assinatura. É necessário ter uma conta Docker para executar sbx login. O produto é recente, então preços e flags podem mudar.

• O diretório do projeto tem permissão total de escrita, então trabalho não commitado não fica protegido.
• Tudo o que o agente envia via push, ou envia para um domínio permitido, sai do sandbox.
• Defina os recursos com --memory e --cpus. Localmente, a memória padrão é metade da RAM do host, até 32 GiB. O padrão documentado de 2 CPUs e 4 GiB se aplica aos sandboxes na nuvem.
• A assinatura de commits via SSH funciona por meio do encaminhamento do SSH agent, que vem ativado por padrão quando SSH_AUTH_SOCK está definido no seu host. Você ainda precisa configurar o Git dentro do sandbox para assinar com a chave encaminhada.
• Andrew Lock relatou em abril de 2026 que a execução em sandbox deixou até projetos simples muito mais lentos.

Conclusão

O Docker Sandboxes oferece a um agente de codificação seu próprio kernel, seu próprio Docker Engine e uma rede controlada por políticas, e a única parte da sua máquina que ele pode tocar é a pasta do seu projeto. Para começar, faça commit do seu trabalho, instale o sbx, escolha Balanced e execute sbx run --name my-project claude em um repositório que você pode se dar ao luxo de perder. Passe para o modo clone quando quiser manter as alterações do agente fora da sua working tree até revisá-las.

Perguntas frequentes

Como abro um servidor de desenvolvimento que o agente inicia dentro de um Docker Sandbox?

Publique a porta dele com sbx ports. Executar sbx ports my-project --publish 3000:8080 mapeia a porta 3000 do host para a porta 8080 do sandbox, e --publish 8080 sozinho escolhe uma porta efêmera no host. Seu navegador não consegue acessar serviços dentro do sandbox até que você faça isso. O servidor de desenvolvimento também precisa fazer bind em 0.0.0.0 em vez de 127.0.0.1, por isso muitos frameworks exigem a flag --host 0.0.0.0.

O agente pode ler outros diretórios sem poder modificá-los?

Sim. Adicione caminhos extras depois do workspace principal e coloque :ro no final de cada um para torná-lo somente leitura, por exemplo sbx run claude ~/project-a ~/shared-libs:ro ~/docs:ro. O agente começa no primeiro caminho. Cada workspace aparece dentro do sandbox no mesmo caminho absoluto que tem no seu host. Os workspaces extras são montados diretamente do host, mesmo quando o workspace principal usa o modo clone.

Como trago os commits de um sandbox em modo clone?

Faça fetch deles a partir do remote Git que o sbx adiciona ao repositório no seu host, chamado sandbox- seguido do nome do sandbox. Depois, faça diff ou merge como faria com qualquer remote. O servidor Git do clone fica dentro do sandbox, então o git fetch falha enquanto o sandbox estiver parado. O sbx rm também remove esse remote, então faça fetch ou push de tudo o que quiser manter antes de remover o sandbox.