Docker no WSL 2 para Agentes de IA — Tutorial de Isolamento de Ambientes

Sumário

• Por que Docker + WSL 2 para agentes de IA
• Instalação do Docker no WSL 2
• Dockerfile para Claude Code
• Dockerfile para Codex
• Docker Compose multi-agente
• Dicas de performance para contêineres no WSL
• FAQ
• Próximos passos com contêineres e agentes

Por que Docker + WSL 2 para agentes de IA

Agentes de IA são exigentes com o ambiente de execução. Claude Code precisa de Node.js 18+, Git, acesso ao sistema de arquivos e permissões específicas. Codex exige Python 3.10+ com pacotes como openai e requests. Cada projeto pode demandar versões diferentes dessas ferramentas.

Sem isolamento, você enfrenta:

• Conflito de versões — Um projeto precisa de Node 18, outro de Node 22. Alternar entre elas exige nvm e reconfiguração constante.
• Poluição do sistema — Pip install global, npm install -g, apt packages. Com o tempo, sua máquina vira uma sopa de dependências.
• Reprodutibilidade — O setup que funciona na sua máquina quebra na do colega. "Mas na minha máquina roda" é um clássico.
• Segurança — Agentes de IA executam código gerado por terceiros. Um pip install malicioso em um ambiente não isolado pode comprometer todo o sistema.

Docker resolve todos esses problemas de uma vez. Cada agente roda em seu próprio contêiner Linux com as dependências exatas de que precisa. O Docker WSL 2 agentes IA é a combinação ideal porque o WSL 2 fornece o kernel Linux nativo que o Docker precisa — sem máquina virtual pesada, sem Hyper-V separado.

No Windows, você tem duas rotas: Docker Desktop (interface gráfica, pago para empresas) ou Docker Engine direto no WSL 2 (leve, open source, 100% funcional). Este tutorial cobre as duas, mas foca na instalação direta — mais rápida e sem as limitações de licenciamento do Docker Desktop.

Instalação do Docker no WSL 2

Antes de começar, você precisa do WSL 2 configurado com uma distribuição Linux. Se ainda não fez isso, veja o guia completo de WSL 2 para agentes de IA. Você vai precisar do Ubuntu 24.04 LTS rodando no WSL 2.

Método 1: Docker Engine direto no WSL (recomendado)

Este método instala o Docker Engine nativamente dentro do WSL 2, sem depender do Docker Desktop. É mais leve, não tem taxa de licenciamento e funciona perfeitamente para desenvolvimento local com agentes de IA.

Abra o terminal WSL e execute:

Depois de instalado, adicione seu usuário ao grupo docker para evitar usar sudo em todo comando:

Saia do terminal WSL (exit), abra novamente e inicie o serviço:

Para que o Docker inicie automaticamente junto com o WSL, adicione ao final do ~/.bashrc:

Método 2: Docker Desktop com backend WSL 2

Se você prefere interface gráfica ou já usa o Docker Desktop, a configuração é igualmente simples:

1. Baixe e instale o Docker Desktop para Windows
2. Vá em Settings > Resources > WSL Integration
3. Ative a integração com Ubuntu-24.04 (ou sua distribuição)
4. Aplique e reinicie

Agora o comando docker funciona direto do terminal WSL, e os contêineres rodam nativamente usando o kernel do WSL 2.

Verificando a instalação

Teste se tudo está funcionando:

A mensagem de confirmação do Docker indica que a instalação está correta. Agora você tem um ambiente Docker completo rodando dentro do WSL 2, pronto para isolar seus agentes de IA.

Dockerfile para Claude Code

Com o Docker instalado, vamos criar um contêiner dedicado para o Claude Code. O objetivo é ter um ambiente limpo com Node.js, Git e a CLI do Claude Code pré-instalados, sem poluir seu sistema host.

Crie um arquivo Dockerfile.claude no diretório do seu projeto:

Para construir e usar:

Vamos entender cada flag:

• -it — Modo interativo, essencial para o Claude Code que espera entrada do terminal
• --rm — Remove o contêiner após o uso, evitando acúmulo
• -v "$(pwd):/workspace" — Monta o diretório atual no contêiner
• -v "$HOME/.claude:/root/.claude" — Compartilha as configurações do Claude Code
• -e ANTHROPIC_API_KEY — Injeta a chave de API como variável de ambiente

Esse setup isola completamente o ambiente do Claude Code. Se algo der errado, basta destruir o contêiner e criar um novo — sem resquícios no sistema.

Dockerfile para Codex

O Codex exige Python 3.10+ e alguns pacotes específicos. O Dockerfile é igualmente simples:

Construa e execute:

Com Claude Code e Codex em contêineres separados, você pode rodar os dois simultaneamente sem qualquer conflito de dependências. Cada um vive em seu próprio ecossistema isolado.

Docker Compose multi-agente

O verdadeiro poder do Docker WSL agentes IA aparece quando você orquestra múltiplos agentes ao mesmo tempo. Com Docker Compose, você define toda a infraestrutura em um único arquivo YAML.

Crie um docker-compose.yml:

Crie um arquivo .env na raiz com suas chaves:

Para iniciar tudo de uma vez:

Para acessar um agente específico:

O serviço test-env funciona como um ambiente de testes isolado. Quando Claude Code ou Codex geram código, você pode testá-lo no test-env sem risco de contaminar o contêiner do agente. Se o código for malicioso ou bugado, o estrago máximo é um contêiner destruído — seu sistema principal fica intacto.

Script auxiliar para facilitar

Para não precisar digitar docker exec -it toda vez, crie um alias no ~/.bashrc:

Agora você chama claude-docker e codex-docker diretamente do terminal WSL.

Dicas de performance para contêineres no WSL

Rodar Docker dentro do WSL 2 tem suas particularidades. Aqui estão as otimizações que fazem diferença real.

Use bind mounts, não volumes nomeados

Para projetos de agentes de IA, bind mounts (-v "$(pwd):/workspace") são mais performáticos que volumes nomeados do Docker. O bind mount dá acesso direto ao sistema de arquivos do WSL, enquanto os volumes passam por uma camada extra de abstração.

Configure limites de recursos por contêiner

No Docker Compose acima, você viu mem_limit e cpus. Sempre defina esses limites. Um agente que consuma toda a RAM disponível pode derrubar o WSL 2 inteiro. Valores seguros para uma máquina de 16 GB:

Prefira imagens slim

Imagens -slim reduzem drasticamente o tamanho do contêiner. Uma imagem node:22 tem 1.1 GB; a versão node:22-bookworm-slim tem 250 MB. Em um cenário com 3-4 contêineres, a economia ultrapassa 3 GB de disco.

Habilite o BuildKit

O BuildKit acelera a construção das imagens com cache inteligente e construção paralela:

Atenção ao arquivo .dockerignore

Evite que arquivos desnecessários sejam enviados para o daemon do Docker:

Isso acelera o build e reduz o tráfego entre o cliente Docker e o daemon — que no WSL 2 acontece via rede interna.

FAQ

Preciso do Docker Desktop ou o Docker Engine no WSL 2 é suficiente?

O Docker Engine instalado diretamente no WSL 2 é suficiente para uso com agentes de IA. Você perde a interface gráfica, mas ganha em leveza e evita as limitações de licenciamento do Docker Desktop para uso comercial. Para desenvolvimento local com Claude Code e Codex, o Engine puro atende perfeitamente.

Dá para rodar Claude Code e Codex em contêineres ao mesmo tempo?

Sim. Com Docker Compose, você define ambos os serviços no mesmo arquivo YAML e inicia tudo com docker compose up. Cada agente roda em isolamento total, com suas próprias dependências, volumes e variáveis de ambiente. Não há conflito entre eles.

Como faço para acessar os arquivos gerados pelos agentes dentro dos contêineres?

Use bind mounts. Quando você monta $(pwd):/workspace, tudo que o agente cria dentro de /workspace aparece no seu sistema de arquivos do WSL imediatamente. Para acessar do Windows, navegue até \\wsl.localhost\Ubuntu-24.04\caminho\do\projeto.

Qual a diferença de performance entre rodar o agente direto no WSL vs em contêiner?

A diferença é pequena para a maioria dos casos — cerca de 5-10% de overhead em operações de E/S devido ao sistema de arquivos em camadas do Docker. O ganho em isolamento e reprodutibilidade compensa amplamente essa perda. Para tarefas computacionais intensivas (builds, testes), o overhead é insignificante.

Como garantir que as chaves de API dos agentes estejam seguras nos contêineres?

Nunca hardcode chaves no Dockerfile. Use o arquivo .env (que está no .gitignore) e referencie com ${ANTHROPIC_API_KEY} no docker-compose.yml. Para segurança adicional, configure secrets do Docker Swarm ou use ferramentas como o Bitwarden Secrets Manager.

O Docker no WSL 2 funciona com GPUs para inferência local?

Sim, com algumas ressalvas. O WSL 2 suporta aceleração de GPU via CUDA (NVIDIA) e DirectML (AMD). Para usar GPUs em contêineres, instale o CUDA Toolkit no WSL e use a flag --gpus all no docker run. Isso é útil se você roda modelos locais com Claude Code ou ferramentas de inferência.

Com que frequência devo reconstruir as imagens dos agentes?

Reconstrua sempre que houver atualizações nas ferramentas (Claude Code, Codex) ou nas dependências do sistema. Use docker compose build para reconstruir tudo ou docker compose build claude para um agente específico. Para manter as imagens atualizadas automaticamente, configure uma tarefa semanal no cron do WSL.

Próximos passos com contêineres e agentes

Configurar o Docker no WSL 2 para agentes de IA transforma a forma como você gerencia ambientes de desenvolvimento. Cada agente roda isolado, com suas dependências exatas, sem conflitos e sem poluir seu sistema. Você ganha reprodutibilidade, segurança e sanidade mental.

O fluxo ideal é simples: Dockerfile para cada agente, Docker Compose para orquestrar tudo, e bind mounts para acessar os arquivos gerados. Com os limites de recursos bem configurados, você roda Claude Code, Codex e ambientes de teste simultaneamente sem sufocar o sistema.

Se você quer levar a orquestração multi-agente a outro nível, o Orquestra oferece um canvas infinito nativo para Windows com suporte total a Docker e WSL 2. Baixe o Orquestra e gerencie seus contêineres de agentes de IA em um ambiente visual integrado — sem abrir mão do isolamento que você aprendeu aqui.

Para se aprofundar na configuração do WSL 2, veja o guia completo de WSL 2 para agentes de IA. E para entender como orquestrar múltiplos agentes em paralelo, confira o guia de orquestração de agentes de IA.