Agentbox - Coding-Agent-Sandbox

Es gibt (noch) keine perfekte Möglichkeit, Agenten zu sandboxen, aber Container sind ein praktischer Anfang.

Agentbox ist eine Docker-basierte Sandbox für Coding-Agenten, ursprünglich inspiriert von Batrachian Toad, und jetzt für weitere Tools verallgemeinert. Es bietet eine isolierte Umgebung, die gut mit webterm für die Ausführung mehrerer Agentensitzungen funktioniert.

Funktionen

Der Standardcontainer bietet:

• Entwicklungsumgebung: Debian Trixie mit gängigen Entwicklungswerkzeugen
• Vorinstallierte Coding-Agenten: Copilot CLI, Codex, Pi
• Vorinstallierte CLI-Tools: gh, Nushell, lazygit, killall
• Paketmanager: Homebrew und APT, plus uv und Bun
• Optionale Agent-Werkzeuge: installieren Sie toad, opencode, gemini und vibe über make -C ~ ...
• Dienststeuerung: Docker/SSH/RDP umschalten mit ENABLE_DOCKER, ENABLE_SSH und ENABLE_RDP
• Docker-in-Docker: verfügbar, wenn Container im privilegierten Modus ausgeführt werden
• Fernzugriff: SSH (ENABLE_SSH=true) und mosh-Unterstützung
• Workspace-Bootstrap: eingebautes Workspace-Gerüst und Agenten-Fähigkeiten unter /home/agent/workspace-skel

Roadmap

• CPU- und Speicherlimits (grundlegende Docker-Ressourcenbeschränkungen)
• Optionen zur Netzwerkisolation
• Andere Sandboxing-Techniken (gVisor, Kata-Container, usw.)

Dienstkonfiguration

Agentbox verwendet Umgebungsvariablen, um zu steuern, welche Dienste beim Containerstart gestartet werden:

• ENABLE_DOCKER=true - Startet Docker-Daemon (für Docker-in-Docker-Unterstützung)
• ENABLE_SSH=true - Startet SSH-Server (Port 22)
• ENABLE_RDP=true - Startet RDP-Server (Port 3389)
• AGENTBOX_ENVIRONMENT=cli|gui - Vom Image bereitgestellte Umgebungsmarkierung (cli für headless/CLI, gui für Desktop-Images)

Standardverhalten: Alle Dienste sind deaktiviert, sofern nicht explizit aktiviert.

Beispiele:

# 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

Schnellstart

Optionale Werkzeuginstallationen

Im Container verfügt der Benutzer agent über ein ~/Makefile, das zusätzliche Werkzeuge installieren kann.

Coding-Agenten/CLIs, die Sie über make -C ~ … installieren können:

• toad — installiert Batrachian Toad (über uv tool)
• opencode — installiert OpenCode (über Bun)
• gemini — installiert Gemini CLI (über Homebrew)
• vibe — installiert mistral-vibe (über uv tool)

Praktische Ziele:

• tools — installiert node, go, gemini, vibe
• node, go — installiert Sprach-Toolchains (Voraussetzungen für einige Agenten)

Workspace-Gerüst

Agentbox enthält ein eingebautes Projektgerüst unter /home/agent/workspace-skel.

Um es in Ihr aktuelles /workspace zu kopieren, ohne vorhandene Dateien zu überschreiben:

make init-workspace

Siehe docs/workspace-skeleton.md für Details.

GUI-Image

Der GUI-Build wird als :gui-Tag veröffentlicht (auch <release>-gui) und enthält XFCE, XRDP und VS Code.

Docker Compose

Empfohlener Arbeitsablauf:

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

Wenn Sie Dienstüberschreibungen benötigen, erstellen Sie docker-compose.override.yml:

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

Dann führen Sie aus:

docker compose up -d

Direkte Verwendung von 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

Verwendung von Batrachian Toad

Sobald Sie mit dem Container verbunden sind:

1. Toad installieren (falls erforderlich):

make -C ~ toad

2. Toad starten:

toad

3. Oder mit einem bestimmten Projektverzeichnis starten:

toad /workspace

4. Oder direkt mit einem Agenten starten:

toad -a open-hands

Sicherheitshinweise

• Dienststeuerung: Standardmäßig sind alle Dienste (Docker, SSH, RDP) deaktiviert. Aktivieren Sie nur das, was Sie benötigen, explizit über Umgebungsvariablen.
• Standardpasswörter sind schwach - ändern Sie sie für den Produktionseinsatz
• Der Container muss im privilegierten Modus ausgeführt werden, damit Docker-in-Docker für Ihre Agenten verfügbar ist (es ist besser als nichts)
• Erwägen Sie die Verwendung von SSH-Schlüsseln anstelle der Passwortauthentifizierung
• Für den Produktionseinsatz sollten Sie unnötige Dienste deaktivieren und die Standardanmeldeinformationen ändern

Danksagungen

Dieses Projekt basiert lose auf meinem alten rcarmo/docker-templates/desktop-chrome mit einer aktualisierten Benutzerumgebung.

Lizenz

MIT