Agentbox - Sandbox para agentes de programación

No existe una forma perfecta de aislar agentes (todavía), pero los contenedores son un comienzo práctico.

Agentbox es un sandbox para agentes de programación basado en Docker, inspirado originalmente en Batrachian Toad, y ahora generalizado para más herramientas. Proporciona un entorno aislado que funciona bien con webterm para ejecutar múltiples sesiones de agentes.

Características

El contenedor predeterminado proporciona:

• Entorno de desarrollo: Debian Stable con herramientas de desarrollo comunes
• Agentes de programación preinstalados: Copilot CLI, Codex, Pi
• Herramientas CLI preinstaladas: gh, Nushell, lazygit, killall
• Gestores de paquetes: Homebrew y APT, además de uv y Bun; las compilaciones del contenedor instalan los paquetes más recientes disponibles sin fijar versiones exactas
• Herramientas opcionales para agentes: instala toad, opencode, gemini y vibe mediante make -C ~ ...
• Control de servicios: activa o desactiva Docker/SSH/RDP con ENABLE_DOCKER, ENABLE_SSH y ENABLE_RDP
• Docker-in-Docker: disponible cuando los contenedores se ejecutan en modo privilegiado
• Acceso remoto: soporte para SSH (ENABLE_SSH=true) y mosh
• Bootstrap del espacio de trabajo: esqueleto de espacio de trabajo integrado y habilidades de agentes en /home/agent/workspace-skel

Hoja de ruta

• Límites de CPU y memoria (restricciones básicas de recursos de Docker)
• Opciones de aislamiento de red
• Otras técnicas de sandboxing (gVisor, Kata Containers, etc.)

Configuración de servicios

Agentbox utiliza variables de entorno para controlar qué servicios se inician al lanzar el contenedor:

• ENABLE_DOCKER=true - Inicia el daemon de Docker (para soporte de Docker-in-Docker)
• ENABLE_SSH=true - Inicia el servidor SSH (puerto 22)
• ENABLE_RDP=true - Inicia el servidor RDP (puerto 3389)
• AGENTBOX_ENVIRONMENT=cli|gui - Marcador de entorno proporcionado por la imagen (cli para headless/CLI, gui para imágenes de escritorio)

Comportamiento predeterminado: Todos los servicios están deshabilitados a menos que se habiliten explícitamente.

Ejemplos:

# 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

Inicio rápido

Instalaciones opcionales de herramientas

Dentro del contenedor, el usuario agent incluye un ~/Makefile que puede instalar herramientas adicionales.

Agentes/CLIs de programación que puedes instalar mediante make -C ~ …:

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

Objetivos de conveniencia:

• tools — instala node, go, gemini, vibe
• node, go — instala cadenas de herramientas de lenguajes (requisitos previos para algunos agentes)

Esqueleto del espacio de trabajo

Agentbox incluye un esqueleto de proyecto integrado en /home/agent/workspace-skel.

Para copiarlo en tu /workspace actual sin sobrescribir archivos existentes:

make init-workspace

Consulta docs/workspace-skeleton.md para más detalles.

Imagen GUI

La compilación GUI se publica con la etiqueta :gui (también <release>-gui) e incluye XFCE, XRDP y VS Code.

Docker Compose

Flujo de trabajo recomendado:

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

Si necesitas sobrescribir servicios, crea docker-compose.override.yml:

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

Luego ejecuta:

docker compose up -d

Uso directo de Docker

# 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

Uso de Batrachian Toad

Una vez conectado al contenedor:

1. Instala Toad (si es necesario):

make -C ~ toad

2. Inicia Toad:

toad

3. O inicia con un directorio de proyecto específico:

toad /workspace

4. O lanza directamente con un agente:

toad -a open-hands

Notas de seguridad

• Control de servicios: De forma predeterminada, todos los servicios (Docker, SSH, RDP) están deshabilitados. Habilita explícitamente solo lo que necesites mediante variables de entorno.
• Las contraseñas predeterminadas son débiles: cámbialas para uso en producción
• El contenedor necesita ejecutarse en modo privilegiado para que Docker-in-Docker esté disponible para tus agentes (es mejor que nada)
• Considera usar claves SSH en lugar de autenticación por contraseña
• Para uso en producción, considera deshabilitar los servicios innecesarios y cambiar las credenciales predeterminadas

Créditos

Este proyecto está basado libremente en mi antiguo rcarmo/docker-templates/desktop-chrome con un userland actualizado.

Licencia

MIT