DEV Community

Cover image for Eu parei de rodar agentes de IA direto no meu WSL: usando Dev Containers + gVisor com Claude Code e Codex
Marcos Filipe
Marcos Filipe

Posted on

Eu parei de rodar agentes de IA direto no meu WSL: usando Dev Containers + gVisor com Claude Code e Codex

#ai #claude #docker #security

Nos últimos tempos, comecei a usar cada vez mais agentes de IA no terminal para desenvolvimento de software: Claude Code, Codex, OpenCode e outras ferramentas parecidas.

O fluxo parece simples:

cd meu-projeto
code .
Enter fullscreen mode Exit fullscreen mode

Depois, dentro do terminal integrado do VS Code:

claude
Enter fullscreen mode Exit fullscreen mode

ou:

codex
Enter fullscreen mode Exit fullscreen mode

Só que aí veio uma dúvida importante:

Eu estou rodando esses agentes dentro de um ambiente seguro ou eles estão diretamente no meu sistema operacional?

A resposta, na maioria dos casos, é: se você só abriu o terminal do Ubuntu/WSL e digitou claude ou codex, provavelmente o agente está rodando direto no seu ambiente real.

E isso muda bastante o nível de risco.

Por que isso importa?

Agentes de IA para programação não são apenas chats que respondem perguntas.

Eles podem:

  • ler arquivos do projeto;
  • editar código;
  • criar arquivos;
  • apagar arquivos;
  • executar comandos de terminal;
  • instalar dependências;
  • rodar testes;
  • subir servidores locais;
  • acessar a internet, dependendo das permissões;
  • interagir com ferramentas do seu ambiente.

Isso é poderoso.

Mas também cria uma superfície de risco.

Imagine alguns cenários:

  • o agente entende errado uma instrução e executa um comando destrutivo;
  • você aprova um comando sem ler com atenção;
  • um arquivo do projeto contém uma instrução maliciosa para induzir o agente a agir fora do esperado;
  • o agente acessa arquivos que não deveria;
  • alguma dependência ou script executado pelo agente faz mais do que você imaginava.

Não é questão de demonizar as ferramentas. Pelo contrário: elas são extremamente úteis.

A questão é simples:

Se vamos dar autonomia para agentes executarem comandos, precisamos criar limites claros para onde eles podem atuar.

O problema do terminal “normal”

Meu fluxo antes era algo assim:

cd ~/projetos/meu-projeto
code .
Enter fullscreen mode Exit fullscreen mode

Depois, no terminal integrado do VS Code:

claude
Enter fullscreen mode Exit fullscreen mode

ou:

codex
Enter fullscreen mode Exit fullscreen mode

O problema é que esse terminal estava apontando para algo como:

/home/meu-usuario/projetos/meu-projeto
Enter fullscreen mode Exit fullscreen mode

Ou seja: eu estava no ambiente real do meu Ubuntu/WSL.

Nesse caso, o agente não está automaticamente dentro de um container só porque estou usando VS Code.

Ele está rodando no mesmo ambiente em que ficam minhas ferramentas, configurações, chaves, arquivos, histórico e dependências.

A ideia: colocar o ambiente de trabalho dentro de um Dev Container

O primeiro passo para melhorar isso é usar Dev Containers.

Com Dev Containers, o VS Code abre o projeto dentro de um container Docker. O editor continua confortável, mas o terminal, as extensões e as ferramentas de desenvolvimento passam a rodar dentro do container.

Na prática, o caminho muda de:

/home/meu-usuario/projetos/meu-projeto
Enter fullscreen mode Exit fullscreen mode

para algo como:

/workspaces/meu-projeto
Enter fullscreen mode Exit fullscreen mode

Esse detalhe é importante.

Quando o terminal mostra /workspaces/..., significa que você está dentro do Dev Container.

O fluxo passa a ser:

VS Code
→ Dev Container
→ ambiente isolado
→ agente de IA
→ projeto montado em /workspaces
Enter fullscreen mode Exit fullscreen mode

A documentação oficial do VS Code explica que Dev Containers permitem abrir uma pasta dentro de um container e usar esse container como ambiente completo de desenvolvimento.

Referência: https://code.visualstudio.com/docs/devcontainers/containers

Mas Docker puro é suficiente?

Docker já ajuda bastante, mas container tradicional não é uma barreira perfeita.

Containers compartilham o kernel do host. Isso significa que eles isolam processos, filesystem, rede e permissões, mas não são a mesma coisa que uma máquina virtual completa.

Por isso existem camadas extras de isolamento, como:

  • permissões do próprio agente;
  • sandbox nativo da ferramenta;
  • seccomp;
  • gVisor;
  • microVMs.

Aqui é onde a confusão começa.

Muita gente fala “use Docker com Claude Code” ou “use sandbox com agente de IA”, mas isso pode significar coisas diferentes.

Pode significar:

  1. rodar o agente dentro de um container;
  2. fazer o código gerado aparecer no host por volume montado;
  3. usar o sandbox nativo do agente;
  4. usar gVisor como runtime do Docker;
  5. usar microVMs.

No meu caso, eu queria um equilíbrio entre:

  • continuar usando VS Code normalmente;
  • manter o terminal integrado funcionando;
  • usar Claude Code e Codex dentro do projeto;
  • não rodar tudo direto no WSL;
  • adicionar uma camada extra além do Docker padrão.

A solução foi:

VS Code
→ Dev Container
→ Docker
→ gVisor / runsc-ptrace
→ Claude Code ou Codex
Enter fullscreen mode Exit fullscreen mode

O que é gVisor?

gVisor é uma camada de isolamento criada para rodar containers com uma barreira adicional entre o container e o kernel do host.

Em vez de deixar as chamadas de sistema do container irem diretamente para o kernel do sistema, o gVisor intercepta e implementa parte desse comportamento em um kernel de usuário.

Na prática, ele fica entre o container e o sistema operacional.

Referência oficial: https://gvisor.dev/

No Docker, usamos o runtime runsc para executar containers com gVisor.

Exemplo:

docker run --runtime=runsc --rm hello-world
Enter fullscreen mode Exit fullscreen mode

Referência: https://gvisor.dev/docs/user_guide/quick_start/docker/

O detalhe no WSL2: systrap falhou, ptrace funcionou

Durante a configuração, um detalhe importante apareceu.

O runtime padrão do gVisor usando runsc falhou no meu ambiente WSL2 com um erro parecido com este:

OCI runtime start failed: starting container: starting root container: urpc method "containerManager.StartRoot" failed: EOF
Enter fullscreen mode Exit fullscreen mode

Depois de investigar, o problema estava na plataforma padrão usada pelo gVisor, chamada systrap.

A solução foi registrar um runtime alternativo usando ptrace:

sudo runsc install --runtime runsc-ptrace -- --platform=ptrace
sudo systemctl restart docker || sudo service docker restart
Enter fullscreen mode Exit fullscreen mode

Depois testei:

docker run --runtime=runsc-ptrace --rm hello-world
Enter fullscreen mode Exit fullscreen mode

E funcionou.

Então, no meu ambiente, o caminho funcional ficou:

Docker + gVisor usando runsc-ptrace
Enter fullscreen mode Exit fullscreen mode

ptrace pode ser mais lento que systrap, mas tende a ser mais compatível em ambientes como WSL2.

Referência sobre plataformas do gVisor: https://gvisor.dev/docs/user_guide/platforms/

O template .devcontainer

Depois disso, criei um template simples para reaproveitar em qualquer projeto.

O arquivo principal é:

.devcontainer/devcontainer.json
Enter fullscreen mode Exit fullscreen mode

Com esta ideia central:

{
  "name": "Agent Dev Container - gVisor ptrace",
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",

  "runArgs": [
    "--runtime=runsc-ptrace"
  ],

  "features": {
    "ghcr.io/devcontainers/features/node:1": {
      "version": "22"
    },
    "ghcr.io/devcontainers/features/python:1": {
      "version": "3.12"
    }
  },

  "postCreateCommand": "corepack enable && corepack prepare pnpm@10.0.0 --activate",

  "customizations": {
    "vscode": {
      "extensions": [
        "ms-azuretools.vscode-docker",
        "ms-python.python",
        "bradlc.vscode-tailwindcss",
        "esbenp.prettier-vscode"
      ]
    }
  },

  "remoteUser": "vscode"
}
Enter fullscreen mode Exit fullscreen mode

A parte mais importante é esta:

"runArgs": [
  "--runtime=runsc-ptrace"
]
Enter fullscreen mode Exit fullscreen mode

Isso força o Dev Container a subir usando o runtime do gVisor que funcionou no WSL2.

Como usar em qualquer projeto

Depois de ter Docker, gVisor e runsc-ptrace configurados no sistema, não preciso repetir tudo em cada projeto.

Para um projeto novo, basta copiar a pasta .devcontainer para a raiz do projeto.

Exemplo:

cp -r caminho/para/agent-devcontainer-gvisor-template/.devcontainer meu-projeto/
Enter fullscreen mode Exit fullscreen mode

Depois:

cd meu-projeto
code .
Enter fullscreen mode Exit fullscreen mode

No VS Code:

Ctrl + Shift + P
Dev Containers: Reopen in Container
Enter fullscreen mode Exit fullscreen mode

Quando abrir o terminal integrado, verifico:

pwd
Enter fullscreen mode Exit fullscreen mode

Se aparecer:

/workspaces/meu-projeto
Enter fullscreen mode Exit fullscreen mode

então estou dentro do Dev Container.

Como confirmar se está usando gVisor

Em outro terminal, fora do Dev Container, posso rodar:

docker ps
Enter fullscreen mode Exit fullscreen mode

Depois:

docker inspect $(docker ps -q | head -n 1) --format '{{.HostConfig.Runtime}}'
Enter fullscreen mode Exit fullscreen mode

O esperado é:

runsc-ptrace
Enter fullscreen mode Exit fullscreen mode

Se aparecer isso, o Dev Container está rodando com o runtime configurado.

E o Claude Code?

O Claude Code possui sandbox nativo.

No Linux/WSL2, a documentação oficial fala sobre o uso de bubblewrap e socat para o sandbox.

Referência: https://code.claude.com/docs/en/sandboxing

Dentro do Claude Code, posso rodar:

/sandbox
Enter fullscreen mode Exit fullscreen mode

E escolher:

Sandbox BashTool, with regular permissions
Enter fullscreen mode Exit fullscreen mode

Esse modo mantém o BashTool sandboxado, mas ainda usa o fluxo normal de permissões.

Para mim, é um bom equilíbrio entre segurança e controle.

Com isso, o fluxo fica:

Dev Container
→ gVisor / runsc-ptrace
→ Claude Code
→ sandbox nativo do Claude
Enter fullscreen mode Exit fullscreen mode

E o Codex?

O Codex também trabalha com a ideia de permissões e sandbox.

No menu de permissões, o modo que escolhi foi:

Default
Enter fullscreen mode Exit fullscreen mode

Esse modo permite que o Codex leia, edite arquivos e execute comandos dentro do workspace, mas exige aprovação para acessar a internet ou editar arquivos fora do projeto.

Referência: https://developers.openai.com/codex/agent-approvals-security

Na prática, isso combina bem com o Dev Container:

Dev Container
→ gVisor / runsc-ptrace
→ Codex
→ permissões Default
Enter fullscreen mode Exit fullscreen mode

O que não fazer

Eu evitaria usar agentes direto em:

/home/meu-usuario/projetos/meu-projeto
Enter fullscreen mode Exit fullscreen mode

principalmente com permissões amplas.

Também evitaria começar usando modos como:

Full Access
danger-full-access
--dangerously-skip-permissions
Enter fullscreen mode Exit fullscreen mode

Esses modos podem fazer sentido em ambientes descartáveis e controlados, mas não são uma boa escolha inicial para o dia a dia.

Para uso normal, prefiro:

workspace limitado
aprovação manual
rede controlada
ambiente isolado
Enter fullscreen mode Exit fullscreen mode

Isso resolve 100% da segurança?

Não.

Esse setup não é uma promessa de segurança perfeita.

Ele é uma melhoria prática.

A ideia é reduzir o risco de rodar agentes de IA diretamente no sistema principal.

Ainda é importante:

  • revisar comandos antes de aprovar;
  • não expor credenciais desnecessárias;
  • não montar pastas sensíveis no container;
  • não usar Full Access sem necessidade;
  • revisar o diff antes de commitar;
  • manter dependências e imagens atualizadas;
  • tratar agentes como ferramentas poderosas, não como usuários totalmente confiáveis.

O template no GitHub

Para facilitar, deixei um template simples no GitHub:

https://github.com/mffdeo/agent-devcontainer-gvisor-template

A ideia é copiar a pasta .devcontainer para qualquer projeto e abrir com:

Dev Containers: Reopen in Container
Enter fullscreen mode Exit fullscreen mode

O template assume que você já configurou Docker, gVisor e runsc-ptrace no ambiente.

Conclusão

Usar agentes de IA no terminal está ficando cada vez mais comum.

Mas existe uma diferença enorme entre:

rodar um agente direto no seu sistema
Enter fullscreen mode Exit fullscreen mode

E:

rodar um agente dentro de um ambiente isolado, com permissões controladas
Enter fullscreen mode Exit fullscreen mode

Para mim, o caminho que fez sentido foi:

VS Code
→ Dev Container
→ Docker
→ gVisor / runsc-ptrace
→ Claude Code ou Codex
Enter fullscreen mode Exit fullscreen mode

Não é o único caminho possível.

Mas é um caminho prático, reproduzível e mais seguro para quem quer usar agentes de IA no desenvolvimento local sem entregar o sistema inteiro de bandeja.

Se você usa Claude Code, Codex ou outros agentes no terminal, vale a pena parar alguns minutos e perguntar:

Esse agente está rodando onde exatamente?

Essa pergunta muda tudo.

Top comments (0)