Tutorial 16: Docker-Bereitstellung

Tutorial 16: Docker-Bereitstellung

Willkommen zurück, Hermes-Entdecker! Im letzten Tutorial haben wir uns damit vertraut gemacht, Hermes Agent direkt auf unseren Maschinen auszuführen. Heute bringen wir die Sache auf die nächste Stufe: Wir setzen Hermes in einen Docker-Container. Das ist ein echter Game-Changer, um dein Setup sauber, portabel und einfach aktualisierbar zu halten.

Zwei Wege, wie Docker und Hermes zusammenkommen

Bevor wir loslegen, ist es wichtig zu verstehen, dass Docker und Hermes Agent auf zwei verschiedene Arten zusammenarbeiten können:

1. Hermes in Docker ausführen – Der Agent selbst lebt in einem Container. Darauf konzentrieren wir uns heute.
2. Docker als Terminal-Backend – Hermes läuft auf deinem Host, aber jeder Befehl, den er ausführt, passiert in einer persistenten Docker-Sandbox. Das ist großartig für Sicherheit und Isolation, aber ein Thema für einen anderen Tag.

Heute dreht sich alles um Option 1. Das Schöne an diesem Ansatz: Alle deine Daten – Konfiguration, API-Schlüssel, Sitzungen, Fähigkeiten und Erinnerungen – leben in einem einzigen Verzeichnis auf deinem Host, das in den Container unter /opt/data eingebunden wird. Der Container selbst ist zustandslos, sodass du eine neue Version ziehen und aktualisieren kannst, ohne etwas zu verlieren.

Schnellstart: Dein erster Container

Wenn du völlig neu bei Hermes bist, ist der einfachste Weg, ein Datenverzeichnis anzulegen und den Setup-Assistenten interaktiv auszuführen. Dieser führt dich durch die Eingabe deiner API-Schlüssel und speichert sie in ~/.hermes/.env.

mkdir -p ~/.hermes
docker run -it --rm \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent setup

Ein Wort der Vorsicht: Vermeide browserbasierte VPS-Konsolen (wie die von Hetzner Cloud) für diese Befehle. Sie verstümmeln oft Sonderzeichen wie :, @ und =, was deine docker run-Argumente stillschweigend beschädigen kann. Verbinde dich immer über SSH (ssh root@<host>), um sicher per Copy-Paste einzufügen. Wenn du die Browser-Konsole unbedingt nutzen musst, tippe die Befehle manuell ein und überprüfe jedes Zeichen.

Sobald du im Assistenten bist, wird dringend empfohlen, ein Chat-System (Telegram, Discord usw.) einzurichten, damit dein Gateway einen Ort hat, an den es Nachrichten senden kann.

Ausführung im Gateway-Modus

Nach der Konfiguration möchtest du Hermes als persistentes Hintergrund-Gateway ausführen. So verbindet es sich mit deinen Chat-Plattformen und bleibt rund um die Uhr aktiv.

docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  -p 8642:8642 \
  nousresearch/hermes-agent gateway run

Das Flag -p 8642:8642 macht den OpenAI-kompatiblen API-Server und den Health-Endpoint des Gateways verfügbar. Es ist optional, wenn du nur Chat-Plattformen nutzt, aber erforderlich, wenn das Dashboard oder externe Tools auf dein Gateway zugreifen sollen.

Hier ist ein cooles neues Feature: Im offiziellen Docker-Image wird gateway run jetzt automatisch von s6-overlay überwacht. Das bedeutet: Wenn der Gateway-Prozess abstürzt, wird er innerhalb von Sekunden neu gestartet, ohne den Container zu verlieren. In docker logs siehst du einen Hinweis, der das Upgrade bestätigt. Wenn du das alte Verhalten möchtest (bei dem der Container beendet wird, wenn das Gateway beendet wird), übergib --no-supervise oder setze HERMES_GATEWAY_NO_SUPERVISE=1. Für den Produktionsbetrieb ist die überwachte Standardeinstellung eindeutig besser.

Den API-Server freigeben

Standardmäßig ist der API-Server durch API_SERVER_ENABLED=true geschützt. Um ihn über 127.0.0.1 im Container hinaus verfügbar zu machen, musst du ein paar Umgebungsvariablen setzen:

docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  -p 8642:8642 \
  -e API_SERVER_ENABLED=true \
  -e API_SERVER_HOST=0.0.0.0 \
  -e API_SERVER_KEY="$(openssl rand -hex 32)" \
  -e API_SERVER_CORS_ORIGINS='*' \
  nousresearch/hermes-agent gateway run

Der API_SERVER_KEY muss mindestens 8 Zeichen lang sein – generiere einen mit openssl rand -hex 32. Wichtig: Das Öffnen eines Ports auf einer internetzugänglichen Maschine ist ein Sicherheitsrisiko. Tu es nicht, es sei denn, du verstehst die Auswirkungen vollständig.

Das Dashboard ausführen

Du möchtest ein Web-Dashboard zur Überwachung deines Gateways? Setze HERMES_DASHBOARD=1 und gib Port 9119 frei:

docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  -p 8642:8642 \
  -p 9119:9119 \
  -e HERMES_DASHBOARD=1 \
  nousresearch/hermes-agent gateway run

Das Dashboard wird ebenfalls von s6 überwacht, sodass es bei einem Absturz automatisch neu startet. Seine Ausgabe geht an docker logs <container>.

Ein Hinweis zu Tool-Loop-Schutzmechanismen

Für unbeaufsichtigte Gateways solltest du in Betracht ziehen, harte Stopps für Tool-Loop-Schutzmechanismen zu aktivieren. Der Standardwert ist false, was für interaktive Sitzungen in Ordnung ist, in denen ein Mensch Warnungen sehen kann. Aber in einem unbeaufsichtigten Gateway könnte ein Agent, der in einer Schleife festhängt, nie aufhören. Füge dies zur config.yaml deines Profils hinzu:

tool_loop_guardrails:
  hard_stop_enabled: true
  hard_stop_after:
    exact_failure: 5
    idempotent_no_progress: 5

Zusammenfassung

Das war die Docker-Bereitstellungsgeschichte! Du hast jetzt einen zustandslosen, aktualisierbaren Container, bei dem alle deine Daten sicher auf dem Host eingebunden sind. Im nächsten Tutorial werden wir das Dashboard genauer erkunden. Bis dahin: Viel Spaß beim Containerisieren!