Hermes Agent Docker-Container startet dauernd neu

Ihr Hermes Agent Container startet, stirbt nach wenigen Sekunden, und Docker fährt ihn immer wieder hoch. docker ps zeigt eine Zeile Restarting (137) 3 seconds ago, der Bot antwortet nie auf Telegram, und hermes logs scrollt dasselbe Startbanner immer wieder durch. Diese Schleife lässt sich fast immer auf eines von fünf sehr konkreten Problemen zurückführen, und der von Docker ausgegebene Exit-Code sagt Ihnen, welches. Dieser Beitrag geht sie in der Reihenfolge durch, die die meisten Agenten repariert.

Falls Sie den Container noch nie ausgeführt haben, starten Sie zuerst mit Hermes Agent in Docker betreiben. Diese Anleitung geht davon aus, dass das Image sauber geladen wird, die Compose-Datei liegt und der Fehler in dem Moment auftritt, in dem der Prozess startet.

Schritt 1 - Lesen Sie den tatsächlichen Exit-Code, bevor Sie etwas ändern

Docker legt den Exit-Code des letzten Laufs im Container-State ab. Lesen Sie ihn direkt aus, statt aus den Logs zu raten:

docker inspect --format='{{.State.ExitCode}} OOM={{.State.OOMKilled}} err={{.State.Error}}' hermes-agent

Diese eine Zeile liefert drei Dinge auf einmal: den Exit-Code, ob der OOM-Killer des Kernels den Prozess beendet hat, und einen etwaigen Daemon-Fehler, den Docker dem Lauf angehängt hat. Der Exit-Code grenzt die Suche massiv ein:

137 - der Prozess hat SIGKILL bekommen. Fast immer ein OOM-Kill durch ein Container-Speicherlimit oder einen RAM-armen Host, gelegentlich ein docker stop, der die 10-Sekunden-Frist überschritten hat.
139 - Segmentation Fault. Bei Hermes Agent taucht das auf, wenn die Image-Architektur nicht zum Host passt (amd64-Image auf ARM-VPS, oder umgekehrt).
125 / 126 / 127 - Docker selbst konnte den Container nicht ausführen. 125 heißt, der Daemon hat den Run abgelehnt (falsche Optionen, fehlendes Image). 126, dass der Entrypoint existiert, aber nicht ausführbar ist. 127, dass der Pfad falsch ist oder die benötigte Shell fehlt.
1 oder 2 - der Hermes-Agent-Prozess ist so weit gekommen, seine eigene Validierung auszuführen, und mit einem Anwendungsfehler beendet. Führen Sie docker logs hermes-agent --tail 100 aus und suchen Sie die erste Zeile, die nicht Teil des Startbanners ist.

Erst wenn Sie wissen, welchen dieser Fälle Sie vor sich haben, ergibt es Sinn, die Konfiguration anzufassen. Blind Speicher hochzudrehen oder die Compose-Datei umzuschreiben verdeckt meistens die eigentliche Ursache und produziert einen Container, der eine Woche später aus demselben Grund wieder umkippt.

Terminal mit der Ausgabe von docker inspect, in der Exit-Code, OOMKilled-Flag und error-Feld hervorgehoben sind

Schritt 2 - Exit 137 mit OOMKilled=true: die Falle des 1-GB-VPS

Mit Abstand die häufigste Ursache bei Hermes Agent, und die, vor der der Leitfaden günstiger VPS für KI-Agenten warnt. Der Agent im Leerlauf ist nicht schwer, aber sobald Sie eine lange Konversation, eine Sprachnachricht oder einen MCP-Toolaufruf senden, schnellt der Speicher hoch. Auf einem 1-GB-VPS ohne Swap greift der OOM-Killer des Kernels zum größten Prozess (der Gateway) und beendet ihn. Die Restart-Policy von Docker startet sofort einen neuen Container, der Speicher genauso anfordert und genauso getötet wird. Das ist Ihre Schleife.

Bestätigen Sie es im Kernel-Log:

sudo dmesg -T | grep -i -E 'oom-kill|killed process' | tail -5
# oder auf systemd-Hosts:
sudo journalctl -k --since '30 minutes ago' | grep -i oom

Sie sehen eine Zeile mit dem Hauptprozess des Containers (hermes oder node) und dessen RSS zum Zeitpunkt des Kills. Zwei Fixes, in absteigender Präferenz:

Geben Sie dem Host mehr RAM. Unter 2 GB wird Hermes Agent immer wieder gegen diese Decke laufen, sobald eine Konversation länger wird oder der Sprachmodus einspringt. Realistische Untergrenze für einen komfortablen Ein-Personen-Agenten sind 2 GB mit aktivem Swap oder 4 GB ohne.
Legen Sie Swap auf dem Host an. Auf einem Linux-VPS: sudo fallocate -l 2G /swapfile && sudo chmod 600 /swapfile && sudo mkswap /swapfile && sudo swapon /swapfile, dann in /etc/fstab persistieren. Swap ist langsamer als RAM, aber es ist der Unterschied zwischen einem gekillten Container und einer langsamen Antwort.

Falls Sie in Ihrer Compose-Datei ein explizites mem_limit gesetzt haben, prüfen Sie es ebenfalls. Ein Limit unter 1 GB reproduziert dasselbe OOM-Verhalten selbst auf einem großen Host. Entfernen Sie das Limit oder heben Sie es vor dem Neustart auf mindestens 1,5 GB an.

Schritt 3 - Exit 1 oder 2 mit Config-Fehler in den Logs

Beim Exit-Code 1 oder 2 ist Hermes Agent weit genug gebootet, um seine eigene Validierung auszuführen, und hat die Konfiguration abgelehnt. Die Logs zeigen, was gescheitert ist. Drei Formen decken den Großteil ab:

Fehlende oder fehlerhafte .env. Die Gateway startet nicht ohne gültigen Provider-Schlüssel. Achten Sie in den Logs auf Provider key not set oder Missing TELEGRAM_BOT_TOKEN. Prüfen Sie, dass die .env keine überflüssigen Anführungszeichen um Werte hat (OPENROUTER_API_KEY="sk-..." ist ok, OPENROUTER_API_KEY = "sk-..." mit Leerzeichen nicht) und keine Windows-Zeilenenden (file .env sollte ASCII text sagen, nicht CRLF).
Datenverzeichnis nicht beschreibbar. Sehen Sie EACCES: permission denied, open '/data/config.json', läuft der Container als Nicht-Root-Benutzer, und das bind-gemountete Host-Verzeichnis gehört jemand anderem. Auf dem Host: sudo chown -R 1000:1000 ~/.hermes/data. UID 1000 nutzt das Image; führen Sie den Container nicht als Root aus, nur um das zu umgehen.
Port bereits belegt. bind: address already in use heißt, ein anderer Prozess auf dem Host hält bereits Port 8642. Finden Sie ihn mit sudo lsof -i :8642 und stoppen Sie ihn, oder mappen Sie Hermes Agent in der Compose-Datei auf einen anderen Host-Port (ports: - "9642:8642").

Keines dieser Probleme löst sich durch Neustarts. Reparieren Sie die Konfiguration und dann docker compose up -d erneut.

Schritt 4 - Exit 139 oder „exec format error": die ARM-Image-Falle

Beendet sich der Container in Millisekunden mit Code 139, oder loggt Docker exec /usr/bin/node: exec format error, passt das geladene Image nicht zur CPU-Architektur des Hosts. Das passiert typischerweise auf Oracle Cloud Ampere, AWS Graviton oder einem Raspberry Pi, allesamt ARM64. Haben Sie ein rein für linux/amd64 gebautes Image geladen, kann der Kernel das Binary nicht ausführen, und Docker versucht es immer weiter.

Prüfen Sie die Architekturen von Host und Image:

uname -m                                   # aarch64 = ARM64, x86_64 = amd64
docker inspect hermes-agent-image \
  --format='{{.Architecture}}/{{.Os}}'     # sollte zu uname -m passen

Passen sie nicht, holen Sie das Image mit expliziter Plattform. Das offizielle Hermes Agent Image ist multi-arch veröffentlicht, es reicht also, die Plattform anzugeben:

docker pull --platform linux/arm64 hermes/agent:latest

Bauen Sie ein eigenes Image, rebuilden Sie es mit docker buildx build --platform linux/arm64,linux/amd64 und pushen beide Tags. Ein ARM-Image auf einem amd64-Host zu starten ist derselbe Fehler gespiegelt und liefert denselben 139.

Schritt 5 - Die Restart-Policy verdeckt den echten Fehler

restart: always ist der richtige Default für einen Produktions-Agenten, aber während der Fehlersuche macht es aus jedem Startfehler eine dichte Schleife, die die Logs flutet und den ersten, eigentlichen Fehler kaschiert. Wenn etwas nicht stimmt, wechseln Sie zu einer Policy, die den Fehler sichtbar macht:

services:
  hermes-agent:
    image: hermes/agent:latest
    restart: "on-failure:3"

on-failure:3 startet bis zu dreimal bei Nicht-Null-Exit und gibt dann auf. Der Container bleibt stehen, der Fehler ist in docker ps -a sichtbar, und die Logs werden nicht durch frische Boots überschrieben. Sobald die Ursache behoben ist, schalten Sie zurück auf restart: always oder unless-stopped. Der Hermes Agent Debugging- und Observability-Leitfaden beschreibt die Log-Rotation, die das im Produktivbetrieb lesbar hält.

Auszug aus einer docker-compose.yml mit hervorgehobener Restart-Policy, daneben eine docker ps-Ausgabe, die den Container gestoppt zeigt

Wenn sich der Fix das Wochenende nicht mehr lohnt

Jeder der oben genannten Fehler ist behebbar, aber jeder kostet einen Sonntagnachmittag mit Kernel-Logs und Compose-Umbauten. Wenn Sie hier landen, weil der Bot seit drei Tagen offline ist und Sie einfach wieder mit dem Agenten arbeiten wollen, existiert die verwaltete Variante genau dafür. Hermify betreibt Hermes Agent für Sie auf Telegram, mit vorverdrahtetem Speicher-Volume, Provider-Schlüsseln und Restart-Policy, sodass ein kippender Container nicht mehr Ihr Diagnoseproblem ist. Starten Sie mit Hermify und sind Sie in etwa einer Minute wieder online.

Für Leser, die weiter selbst hosten möchten, ist der nächste Beitrag Hermes Agent Memory und Skills - der zweithäufigste Grund, warum ein dockerisierter Agent kaputt aussieht.