Agentbox - Sandbox para Agentes de Programação

Não existe uma forma perfeita de isolar agentes (ainda), mas contentores são um começo prático.

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

Funcionalidades

O contentor predefinido fornece:

• Ambiente de desenvolvimento: Debian Stable com ferramentas de desenvolvimento comuns
• Agentes de programação pré-instalados: Copilot CLI, Codex, Pi
• Ferramentas CLI pré-instaladas: gh, Nushell, lazygit, killall
• Gestores de pacotes: Homebrew e APT, além de uv e Bun; as compilações do contentor instalam os pacotes mais recentes disponíveis sem fixar versões exatas
• Ferramentas opcionais para agentes: instale toad, opencode, gemini e vibe via make -C ~ ...
• Controlo de serviços: ative/desative Docker/SSH/RDP com ENABLE_DOCKER, ENABLE_SSH e ENABLE_RDP
• Docker-in-Docker: disponível quando os contentores são executados em modo privilegiado
• Acesso remoto: suporte a SSH (ENABLE_SSH=true) e mosh
• Bootstrap do workspace: esqueleto de workspace integrado e competências de agentes em /home/agent/workspace-skel

Roadmap

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

Configuração de Serviços

O Agentbox usa variáveis de ambiente para controlar quais serviços são iniciados no arranque do contentor:

• ENABLE_DOCKER=true - Inicia o daemon do Docker (para suporte a Docker-in-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 ambiente de trabalho)

Comportamento predefinido: Todos os serviços estão desativados a menos que sejam 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 contentor, o utilizador agent inclui um ~/Makefile que pode instalar ferramentas adicionais.

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

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

Alvos de conveniência:

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

Esqueleto do workspace

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

Para o copiar para o seu /workspace atual sem sobrescrever ficheiros existentes:

make init-workspace

Consulte docs/workspace-skeleton.md para mais detalhes.

Imagem GUI

A compilação GUI é publicada com 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 precisar de substituições de serviços, crie docker-compose.override.yml:

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

Depois execute:

docker compose up -d

Utilizar 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

Utilizar o Batrachian Toad

Depois de se ligar ao contentor:

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

• Controlo de Serviços: Por predefinição, todos os serviços (Docker, SSH, RDP) estão desativados. Ative explicitamente apenas o que necessita usando variáveis de ambiente.
• As palavras-passe predefinidas são fracas - altere-as para uso em produção
• O contentor precisa de ser executado em modo privilegiado para que o Docker-in-Docker esteja disponível para os seus agentes (é melhor que nada)
• Considere usar chaves SSH em vez de autenticação por palavra-passe
• Para uso em produção, considere desativar serviços desnecessários e alterar as credenciais predefinidas

Créditos

Este projeto é vagamente baseado no meu antigo rcarmo/docker-templates/desktop-chrome com um userland atualizado.

Licença

MIT