Agentbox - Sandbox para Agentes de Codificação

Não existe uma maneira perfeita de isolar agentes (ainda), mas contêineres são um começo prático.

Agentbox é um sandbox para agentes de codificação baseado em Docker, originalmente inspirado por Batrachian Toad, e agora generalizado para mais ferramentas. Ele fornece um ambiente isolado que funciona bem com webterm para executar múltiplas sessões de agentes.

Recursos

O contêiner padrão fornece:

• Ambiente de desenvolvimento: Debian Trixie com ferramentas de desenvolvimento comuns
• Agentes de codificação pré-instalados: Copilot CLI, Codex, Pi
• Ferramentas CLI pré-instaladas: gh, Nushell, lazygit, killall
• Gerenciadores de pacotes: Homebrew e APT, além de uv e Bun
• Ferramentas opcionais para agentes: instale toad, opencode, gemini e vibe via make -C ~ ...
• Controle de serviços: ative/desative Docker/SSH/RDP com ENABLE_DOCKER, ENABLE_SSH e ENABLE_RDP
• Docker dentro de Docker: disponível quando os contêineres são executados em modo privilegiado
• Acesso remoto: SSH (ENABLE_SSH=true) e suporte a mosh
• Inicialização do workspace: esqueleto de workspace integrado e habilidades do agente em /home/agent/workspace-skel

Roteiro

• Limites de CPU e memória (restrições básicas de recursos do Docker)
• Opções de isolamento de rede
• Outras técnicas de isolamento (gVisor, Kata Containers, etc.)

Configuração de Serviços

O Agentbox usa variáveis de ambiente para controlar quais serviços iniciam na inicialização do contêiner:

• ENABLE_DOCKER=true - Inicia o daemon do Docker (para suporte a Docker dentro de Docker)
• ENABLE_SSH=true - Inicia o servidor SSH (porta 22)
• ENABLE_RDP=true - Inicia o servidor RDP (porta 3389)
• AGENTBOX_ENVIRONMENT=cli|gui - Marcador de ambiente fornecido pela imagem (cli para headless/CLI, gui para imagens de desktop)

Comportamento padrão: Todos os serviços estão desabilitados a menos que explicitamente ativados.

Exemplos:

# Default - all services disabled
docker run -d agentbox

# Enable only Docker daemon
docker run -d -e ENABLE_DOCKER=true agentbox

# Enable Docker and SSH for development
docker run -d -e ENABLE_DOCKER=true -e ENABLE_SSH=true -p 22:22 agentbox

# Full desktop experience with all services (GUI image)
docker run -d -e ENABLE_DOCKER=true -e ENABLE_SSH=true -e ENABLE_RDP=true -p 22:22 -p 3389:3389 agentbox:gui

Início Rápido

Instalações Opcionais de Ferramentas

Dentro do contêiner, o usuário agent vem com um ~/Makefile que pode instalar ferramentas adicionais.

Agentes de codificação/CLIs que você pode instalar via make -C ~ …:

• toad — instala Batrachian Toad (via uv tool)
• opencode — instala OpenCode (via Bun)
• gemini — instala Gemini CLI (via Homebrew)
• vibe — instala mistral-vibe (via uv tool)

Alvos de conveniência:

• tools — instala node, go, gemini, vibe
• node, go — instala toolchains de linguagem (pré-requisitos para alguns agentes)

Esqueleto de workspace

O Agentbox inclui um esqueleto de projeto integrado em /home/agent/workspace-skel.

Para copiá-lo para seu /workspace atual sem sobrescrever arquivos existentes:

make init-workspace

Consulte docs/workspace-skeleton.md para detalhes.

Imagem GUI

A compilação GUI é publicada como a tag :gui (também <release>-gui) e inclui XFCE, XRDP e VS Code.

Docker Compose

Fluxo de trabalho recomendado:

make up
make enter-toad   # or: make enter-copilot
make down

Se você precisar de substituições de serviço, crie docker-compose.override.yml:

services:
  toad:
    environment:
      ENABLE_DOCKER: "true"
      ENABLE_SSH: "true"
  copilot:
    environment:
      ENABLE_DOCKER: "true"
      ENABLE_SSH: "true"

Então execute:

docker compose up -d

Usando Docker Diretamente

# Build the headless image
docker build -t agentbox .

# Build the GUI image
docker build -t agentbox:gui --target gui .

# Run the container with selected services (GUI image)
docker run -d \
  --name agentbox \
  --privileged \
  -e ENABLE_DOCKER=true \
  -e ENABLE_SSH=true \
  -e ENABLE_RDP=true \
  -p 22:22 \
  -p 3389:3389 \
  -v $(pwd):/workspace \
  agentbox:gui

Usando Batrachian Toad

Uma vez conectado ao contêiner:

1. Instale o Toad (se necessário):

make -C ~ toad

2. Inicie o Toad:

toad

3. Ou inicie com um diretório de projeto específico:

toad /workspace

4. Ou lance diretamente com um agente:

toad -a open-hands

Notas de Segurança

• Controle de Serviços: Por padrão, todos os serviços (Docker, SSH, RDP) estão desabilitados. Ative explicitamente apenas o que você precisa usando variáveis de ambiente.
• As senhas padrão são fracas - altere-as para uso em produção
• O contêiner precisa ser executado em modo privilegiado para que o Docker dentro de Docker esteja disponível para seus agentes (é melhor que nada)
• Considere usar chaves SSH em vez de autenticação por senha
• Para uso em produção, considere desabilitar serviços desnecessários e alterar as credenciais padrão

Créditos

Este projeto é vagamente baseado no meu antigo rcarmo/docker-templates/desktop-chrome com um espaço de usuário atualizado.

Licença

MIT