Agentbox - Sandbox per agenti di coding

Non esiste un modo perfetto per isolare gli agenti (per ora), ma i container sono un inizio pratico.

Agentbox è un sandbox per agenti di coding basato su Docker, originariamente ispirato a Batrachian Toad, e ora generalizzato ad altri strumenti. Fornisce un ambiente isolato che funziona bene con webterm per eseguire più sessioni di agenti.

Funzionalità

Il container predefinito fornisce:

• Ambiente di sviluppo: Debian Stable con strumenti di sviluppo comuni
• Agenti di coding preinstallati: Copilot CLI, Codex, Pi
• Strumenti CLI preinstallati: gh, Nushell, lazygit, killall
• Gestori di pacchetti: Homebrew e APT, più uv e Bun; le build del container installano i pacchetti più recenti disponibili senza pin esatti di versione
• Strumenti opzionali per agenti: installa toad, opencode, gemini e vibe tramite make -C ~ ...
• Controllo dei servizi: attiva/disattiva Docker/SSH/RDP con ENABLE_DOCKER, ENABLE_SSH e ENABLE_RDP
• Docker-in-Docker: disponibile quando i container vengono eseguiti in modalità privilegiata
• Accesso remoto: supporto SSH (ENABLE_SSH=true) e mosh
• Bootstrap del workspace: scheletro del workspace integrato e competenze degli agenti sotto /home/agent/workspace-skel

Roadmap

• Limiti di CPU e memoria (vincoli di risorse Docker di base)
• 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 daemon Docker (per il 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 dell'ambiente fornito dall'immagine (cli per headless/CLI, gui per immagini desktop)

Comportamento predefinito: Tutti i servizi sono disabilitati a meno che non vengano 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/CLI di coding 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 comodità:

• tools — installa node, go, gemini, vibe
• node, go — installa i toolchain dei linguaggi (prerequisiti per alcuni agenti)

Scheletro del workspace

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

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

make init-workspace

Vedi docs/workspace-skeleton.md per i 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 override dei servizi, crea docker-compose.override.yml:

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

Poi esegui:

docker compose up -d

Utilizzo diretto di 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

Utilizzo di 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 - cambiale per l'uso in produzione
• Il container deve essere eseguito in modalità privilegiata affinché Docker-in-Docker sia disponibile per i tuoi agenti (è meglio di niente)
• Considera l'uso di chiavi SSH invece dell'autenticazione con password
• Per l'uso in produzione, considera di disabilitare i servizi non necessari e cambiare le credenziali predefinite

Crediti

Questo progetto è vagamente basato sul mio vecchio rcarmo/docker-templates/desktop-chrome con uno userland aggiornato.

Licenza

MIT