Agentbox - Sandbox per Agent di Codice

Non esiste ancora un modo perfetto per isolare gli agent, ma i container sono un inizio pratico.

Agentbox è una sandbox per agent di codifica basata su Docker, originariamente ispirata da Batrachian Toad, e ora generalizzata per più strumenti. Fornisce un ambiente isolato che funziona bene con webterm per eseguire più sessioni di agent.

Funzionalità

Il container predefinito fornisce:

• Ambiente di sviluppo: Debian Trixie con strumenti di sviluppo comuni
• Agenti di codifica preinstallati: Copilot CLI, Codex, Pi
• Strumenti CLI preinstallati: gh, Nushell, lazygit, killall
• Gestori pacchetti: Homebrew e APT, più uv e Bun
• Strumenti agent opzionali: installa toad, opencode, gemini e vibe tramite make -C ~ ...
• Controllo servizi: attiva/disattiva Docker/SSH/RDP con ENABLE_DOCKER, ENABLE_SSH e ENABLE_RDP
• Docker-in-Docker: disponibile quando i container sono eseguiti in modalità privilegiata
• Accesso remoto: supporto SSH (ENABLE_SSH=true) e mosh
• Avvio workspace: scheletro workspace integrato e competenze agent in /home/agent/workspace-skel

Roadmap

• Limiti CPU e memoria (vincoli base risorse Docker)
• Opzioni di isolamento di rete
• Altre tecniche di sandboxing (gVisor, Kata Containers, ecc.)

Configurazione dei Servizi

Agentbox utilizza variabili d'ambiente per controllare quali servizi avviare all'avvio del container:

• ENABLE_DOCKER=true - Avvia il demone Docker (per supporto Docker-in-Docker)
• ENABLE_SSH=true - Avvia il server SSH (porta 22)
• ENABLE_RDP=true - Avvia il server RDP (porta 3389)
• AGENTBOX_ENVIRONMENT=cli|gui - Indicatore ambiente fornito dall'immagine (cli per headless/CLI, gui per immagini desktop)

Comportamento predefinito: Tutti i servizi sono disabilitati a meno che non siano esplicitamente abilitati.

Esempi:

# 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

Avvio Rapido

Installazioni Opzionali di Strumenti

All'interno del container, l'utente agent include un ~/Makefile che può installare strumenti aggiuntivi.

Agenti di codifica/CLI che puoi installare tramite make -C ~ …:

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

Target di convenienza:

• tools — installa node, go, gemini, vibe
• node, go — installa le toolchain linguistiche (prerequisiti per alcuni agent)

Scheletro del Workspace

Agentbox include uno scheletro di progetto integrato in /home/agent/workspace-skel.

Per copiarlo nella tua directory corrente /workspace senza sovrascrivere file esistenti:

make init-workspace

Vedi docs/workspace-skeleton.md per dettagli.

Immagine GUI

La build GUI è pubblicata con il tag :gui (anche <release>-gui) e include XFCE, XRDP e VS Code.

Docker Compose

Flusso di lavoro consigliato:

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

Se hai bisogno di sovrascritture dei servizi, crea docker-compose.override.yml:

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

Quindi esegui:

docker compose up -d

Usare Docker Direttamente

# 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

Usare Batrachian Toad

Una volta connesso al container:

1. Installa Toad (se necessario):

make -C ~ toad

2. Avvia Toad:

toad

3. Oppure avvia con una directory di progetto specifica:

toad /workspace

4. Oppure avvia direttamente con un agente:

toad -a open-hands

Note sulla Sicurezza

• Controllo dei Servizi: Per impostazione predefinita, tutti i servizi (Docker, SSH, RDP) sono disabilitati. Abilita esplicitamente solo ciò di cui hai bisogno utilizzando le variabili d'ambiente.
• Le password predefinite sono deboli - cambiarle per uso in produzione
• Il container deve essere eseguito in modalità privilegiata per Docker-in-Docker sia disponibile per i tuoi agent (è meglio che niente)
• Considera l'uso di chiavi SSH invece dell'autenticazione con password
• Per uso in produzione, considera di disabilitare i servizi non necessari e cambiare le credenziali predefinite

Crediti

Questo progetto è liberamente basato sul mio antico rcarmo/docker-templates/desktop-chrome con un userland aggiornato.

Licenza

MIT