Agentbox - Coding-Agent-Sandbox

Es gibt (noch) keinen perfekten Weg, Agents zu sandboxen, aber Container sind ein praktischer Anfang.

Agentbox ist eine Docker-basierte Coding-Agent-Sandbox, ursprünglich inspiriert von Batrachian Toad und inzwischen für weitere Tools verallgemeinert. Sie bietet eine isolierte Umgebung, die gut mit webterm zusammenarbeitet, um mehrere Agent-Sitzungen auszuführen.

Funktionen

Der Standard-Container bietet:

• Entwicklungsumgebung: Debian Stable mit gängigen Entwicklungswerkzeugen
• Vorinstallierte Coding-Agents: Copilot CLI, Codex, Pi
• Vorinstallierte CLI-Tools: gh, Nushell, lazygit, killall
• Paketmanager: Homebrew und APT, plus uv und Bun; Container-Builds installieren die neuesten verfügbaren Pakete ohne exakte Versions-Pins
• Optionales Agent-Tooling: toad, opencode, gemini und vibe via make -C ~ ... installieren
• Dienststeuerung: Docker/SSH/RDP mit ENABLE_DOCKER, ENABLE_SSH und ENABLE_RDP umschalten
• Docker-in-Docker: verfügbar, wenn Container im privilegierten Modus laufen
• Fernzugriff: SSH (ENABLE_SSH=true) und mosh-Unterstützung
• Workspace-Bootstrap: integriertes Workspace-Skelett und Agent-Skills unter /home/agent/workspace-skel

Roadmap

• CPU- und Speicherlimits (grundlegende Docker-Ressourcenbeschränkungen)
• Netzwerkisolationsoptionen
• Weitere Sandboxing-Techniken (gVisor, Kata Containers usw.)

Dienstkonfiguration

Agentbox verwendet Umgebungsvariablen, um zu steuern, welche Dienste beim Start des Containers gestartet werden:

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

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

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 Tool-Installationen

Im Container verfügt der Benutzer agent über ein ~/Makefile, mit dem zusätzliches Tooling installiert werden kann.

Coding-Agents/CLIs, die du via make -C ~ … installieren kannst:

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

Praktische Targets:

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

Workspace-Skelett

Agentbox liefert ein integriertes Projekt-Skelett unter /home/agent/workspace-skel.

Um es in dein 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 Tag :gui veröffentlicht (auch <release>-gui) und enthält XFCE, XRDP und VS Code.

Docker Compose

Empfohlener Workflow:

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

Wenn du Dienst-Overrides benötigst, erstelle docker-compose.override.yml:

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

Führe dann aus:

docker compose up -d

Docker direkt verwenden

# 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

Batrachian Toad verwenden

Sobald du mit dem Container verbunden bist:

1. Toad installieren (falls nötig):

make -C ~ toad

2. Toad starten:

toad

3. Oder mit einem bestimmten Projektverzeichnis starten:

toad /workspace

4. Oder direkt mit einem Agent starten:

toad -a open-hands

Sicherheitshinweise

• Dienststeuerung: Standardmäßig sind alle Dienste (Docker, SSH, RDP) deaktiviert. Aktiviere explizit nur das, was du benötigst, über Umgebungsvariablen.
• Standardpasswörter sind schwach - ändere sie für den Produktiveinsatz
• Der Container muss im privilegierten Modus laufen, damit Docker-in-Docker für deine Agents verfügbar ist (es ist besser als nichts)
• Erwäge die Verwendung von SSH-Schlüsseln anstelle der Passwortauthentifizierung
• Für den Produktiveinsatz solltest du unnötige Dienste deaktivieren und Standardanmeldedaten ändern

Danksagungen

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

Lizenz

MIT