Hermes Agent in Docker betreiben (selbst gehostet)

Warum Docker die Standardmethode ist, um Hermes Agent zu betreiben

Hermes Agent wird als Docker-Container als erstklassiges Bereitstellungsziel ausgeliefert. Das Image bündelt das Gateway, das Dashboard, die Laufzeitabhängigkeiten und eine vernünftige Standardkonfiguration, sodass Sie sich nicht mit Python-Versionen, Systembibliotheken oder PATH-Problemen auf dem Host herumschlagen müssen. Sie bringen einen Host mit installiertem Docker mit, ein kleines persistentes Volume für den Zustand und Ihren Anbieter-API-Schlüssel. Den Rest erledigt der Container.

Ein typisches selbst gehostetes Setup sieht so aus:

Ein Gateway-Container, der Port 8642 für die OpenAI-kompatible API und den Health-Endpunkt bereitstellt.
Ein persistentes benanntes Volume für Sessions, Speicher, gelernte Skills und Konfiguration.
Eine .env-Datei mit Anbieter-Schlüsseln und Telegram-Anmeldedaten.
Optional ein Sidecar-Dashboard-Container, der dasselbe Datenverzeichnis im schreibgeschützten Modus liest.

Alles andere – Upgrades, Neustarts, Log-Rotation – wird von Docker selbst erledigt. Dieser Beitrag führt Sie durch dieses Setup von Anfang bis Ende, zeigt dann das produktionsreife Docker-Compose-Layout und die Fallstricke, die Sie kennen sollten, bevor Sie den Agenten auf einen öffentlichen Host stellen.

Falls Sie sich noch nicht zwischen Selbsthosting und einem verwalteten Setup entschieden haben, lesen Sie zuerst Selbsthosting vs. verwalteter Hermes Agent. Der Rest dieses Leitfadens setzt voraus, dass Sie sich dafür entschieden haben, den Container selbst zu betreiben.

Voraussetzungen

Sie benötigen:

Einen Host mit installiertem Docker 24+ (Linux-VPS, macOS über Docker Desktop oder Windows über WSL2).
Mindestens 1 vCPU und 2 GB RAM. Die offizielle Empfehlung lautet 2 vCPU und 8 GB für eine komfortable gleichzeitige Nutzung.
Einen Anbieter-API-Schlüssel (OpenAI, Anthropic, OpenRouter oder einen beliebigen OpenAI-kompatiblen Endpunkt).
Etwa 2 GB freien Festplattenspeicher für das Image, zuzüglich Wachstumsspielraum für das Daten-Volume.

Ein VPS für $5 von einem beliebigen vernünftigen Anbieter erfüllt das Minimum. Der Agent ist I/O- und CPU-arm, wenn er nicht aktiv denkt – den größten Teil seines Tages verbringt er im Leerlauf und wartet auf Telegram-Nachrichten oder geplante Aufgaben.

Schritt 1 – Das Datenverzeichnis erstellen

Der Container persistiert alles nach /data innerhalb des Images. Entscheiden Sie auf dem Host, wo dieses Verzeichnis liegt. Die Konvention ist ~/.hermes/data:

mkdir -p ~/.hermes/data

Dieses einzelne Verzeichnis enthält den Session-Verlauf, den Vektorspeicher, gelernte Skills, verschlüsselte Secrets und die Benutzerkonfiguration. Sichern Sie es, und Sie haben den gesamten Agenten gesichert. Verlieren Sie es, und Sie fangen bei null an – der Container selbst ist flüchtig.

Schritt 2 – Einrichtungsassistent beim ersten Start

Führen Sie den Container beim ersten Mal interaktiv aus, damit er Sie nach Schlüsseln fragen und sie in ~/.hermes/.env schreiben kann:

docker run -it --rm \
  -v ~/.hermes:/root/.hermes \
  -v ~/.hermes/data:/data \
  ghcr.io/nousresearch/hermes-agent:latest setup

Der Assistent fragt nach:

Dem Standard-LLM-Anbieter (OpenAI, Anthropic, OpenRouter, benutzerdefiniert).
Dem Anbieter-API-Schlüssel.
Optionalem Telegram-Bot-Token und einer Liste erlaubter Benutzer.
Optionalen Schlüsseln für Sprach-Anbieter (nur falls Sie den Sprachmodus aktivieren möchten).

Die Werte werden auf dem Host in ~/.hermes/.env geschrieben. Behandeln Sie diese Datei als Secret – chmod 600 ~/.hermes/.env und committen Sie sie niemals.

Ein Terminal, das den Einrichtungsassistenten von Hermes Agent für Docker zeigt, der nach einem OpenAI-API-Schlüssel fragt, mit dem Pfad der neuen .env-Datei oben sichtbar

Schritt 3 – Das persistente Gateway betreiben

Sobald der Assistent fertig ist, startet die langlaufende Form desselben Containers das Gateway:

docker run -d \
  --name hermes \
  --restart unless-stopped \
  -p 8642:8642 \
  --env-file ~/.hermes/.env \
  -v ~/.hermes/data:/data \
  ghcr.io/nousresearch/hermes-agent:latest gateway

Aufschlüsselung jeder Option:

-d führt den Container im Hintergrund (detached) aus.
--restart unless-stopped bringt ihn nach Host-Neustarts und Abstürzen automatisch zurück.
-p 8642:8642 stellt die OpenAI-kompatible API und den /health-Endpunkt bereit.
--env-file ~/.hermes/.env injiziert die Anbieter-Schlüssel, ohne sie in das Image einzubacken.
-v ~/.hermes/data:/data ist die Persistenz-Zeile – löschen Sie diese Zeile, und der Agent vergisst bei jedem Neustart alles.

Überprüfen Sie, dass er gesund ist:

curl http://localhost:8642/health
# {"status":"ok","gateway":"running"}

Falls Sie auf einem VPS arbeiten, den Sie von Ihrem Laptop aus erreichen möchten, binden Sie den Port nicht direkt an 0.0.0.0. Setzen Sie einen Reverse-Proxy (Caddy, Nginx, Traefik) mit HTTPS davor, oder stellen Sie den Port nur über Tailscale oder WireGuard bereit. Die OpenAI-kompatible API hat standardmäßig keine Authentifizierung – sie vertraut dem Netzwerk, in dem sie sich befindet.

Schritt 4 – Docker Compose für die Produktion verwenden

Für alles, was über einen schnellen Test hinausgeht, wechseln Sie zu docker-compose.yaml. Das macht die Konfiguration überprüfbar, als Einheit neustartbar und leicht um das optionale Dashboard-Sidecar erweiterbar:

services:
  gateway:
    image: ghcr.io/nousresearch/hermes-agent:latest
    container_name: hermes-gateway
    restart: unless-stopped
    command: gateway
    ports:
      - "127.0.0.1:8642:8642"
    env_file:
      - ./.env
    volumes:
      - hermes_data:/data
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8642/health"]
      interval: 30s
      timeout: 5s
      retries: 3
    deploy:
      resources:
        limits:
          memory: 1G

  dashboard:
    image: ghcr.io/nousresearch/hermes-agent:latest
    container_name: hermes-dashboard
    restart: unless-stopped
    command: dashboard
    ports:
      - "127.0.0.1:8643:8643"
    volumes:
      - hermes_data:/data:ro
    depends_on:
      gateway:
        condition: service_healthy

volumes:
  hermes_data:

Ein paar Details, die erwähnenswert sind:

Der Dashboard-Container bindet das Daten-Volume schreibgeschützt (:ro) ein. Es liest Sessions und Speicher nur, um die Benutzeroberfläche darzustellen, schreibt sie aber nie. Genau das macht es möglich, beide sicher zu betreiben.
Der Gateway-Port ist auf dem Host an 127.0.0.1 gebunden. Die öffentliche Bereitstellung ist Aufgabe des Reverse-Proxys, nicht von Docker.
healthcheck lässt depends_on auf das Gateway warten, bevor das Dashboard gestartet wird.
Ein Speicherlimit von 1 GB ist für die meisten persönlichen Workloads komfortabel. Erhöhen Sie es bei hohem Traffic.

Starten Sie den Stack mit docker compose up -d und verfolgen Sie die Logs mit docker compose logs -f.

Ein vereinfachtes Architekturdiagramm, das den Docker-Host mit zwei Containern zeigt, Gateway und Dashboard, die sich ein einziges benanntes Volume teilen, das auf der Dashboard-Seite schreibgeschützt eingebunden ist

Schritt 5 – Upgrades

Der Container ist die Einheit des Upgrades. Um zu einer neuen Version zu wechseln:

docker compose pull
docker compose up -d

Compose erstellt das Gateway mit dem neuen Image neu und behält dabei das benannte Volume unversehrt. Speicher, Skills und Telegram-Verbindungen kommen genau so zurück, wie sie waren. Pinnen Sie für die Produktion auf einen bestimmten Tag statt auf latest – ghcr.io/nousresearch/hermes-agent:0.42 statt :latest –, damit Upgrades explizit sind.

Erstellen Sie vor jedem Upgrade einen Snapshot des Volumes:

docker run --rm \
  -v hermes_data:/data \
  -v $(pwd):/backup \
  alpine tar czf /backup/hermes-$(date +%F).tar.gz -C /data .

Die Wiederherstellung ist derselbe Befehl in umgekehrter Reihenfolge. Das ist schneller und sicherer, als das Image allein zurückzurollen.

Häufige Fallstricke

Zwei Gateway-Container auf demselben Volume. Die Session- und Speicher-Stores von Hermes gehen von einem einzigen Schreiber aus. Wenn Sie zwei Gateway-Container gegen dasselbe /data laufen lassen, werden die Dateien innerhalb von Minuten beschädigt. Das Dashboard-Sidecar ist in Ordnung, weil es schreibgeschützt ist.

Fehlendes --env-file. Ohne es startet der Container, scheitert aber beim ersten LLM-Aufruf mit einem 401. Prüfen Sie docker logs hermes, falls niemals Antworten eintreffen.

Bindung an 0.0.0.0:8642 auf einem öffentlichen VPS. Die API hat keine eingebaute Authentifizierung. Stellen Sie ihr immer einen Reverse-Proxy voran, der HTTPS sowie entweder Basic Auth oder eine Beschränkung auf Netzwerkebene (Tailscale, Firewall-Regeln) verlangt.

Anonyme Volumes. Wenn Sie die Zeile -v ~/.hermes/data:/data vergessen, erstellt Docker ein anonymes Volume. Es überlebt Neustarts, ist aber schwer zu finden und leicht versehentlich zu entfernen (prune). Verwenden Sie immer ein benanntes Volume oder ein Host-Bind.

Wiederverbindung des Telegram-Bots. Wenn Sie ein Upgrade durchführen, verbindet sich der Bot automatisch wieder. Falls nicht, prüfen Sie, ob TELEGRAM_BOT_TOKEN noch in .env steht und ob der Container ausgehenden Internetzugang hat.

Für Telegram-spezifische Probleme behandelt Hermes Agent Telegram-Fehlerbehebung die Messaging-Seite ausführlicher.

Sich die Container-Klempnerei sparen

Hermes in Docker zu betreiben ist unkompliziert, aber der Host gehört weiterhin Ihnen: Backups, TLS-Zertifikate, Log-Rotation, Betriebssystem-Patches und der Upgrade-Rhythmus. Für einen persönlichen Agenten ist das in Ordnung – ein Sonntagnachmittag zum Einrichten und danach vielleicht zehn Minuten im Monat.

Falls Sie sich all das lieber sparen möchten: Hermify betreibt Ihren Hermes-Agenten in einem isolierten, verwalteten Container, mit ruhend verschlüsselten Secrets, automatischen Upgrades, täglichen Volume-Snapshots und Telegram, das über das Dashboard mit zwei Tipps verbunden wird. Sie bringen einen Anbieter-Schlüssel mit; die Plattform kümmert sich um alles darunter.