Hermes-Agent: Headless-Server + Remote-Desktop-Einrichtung

Headless Hermes-Server mit Remote-Desktop-Zugriff

Inhaltsverzeichnis

Das Ausführen des Hermes-Agenten auf einem headless-Server bei gleichzeitiger Verbindung von einem Desktop-Client auf einer anderen Maschine erfordert zwei Serverprozesse und eine einzelne Client-Verbindung.

Die Architektur trennt das Hermes-Backend in zwei serverseitige Prozesse und eine clientseitige Oberfläche. Der Prozess hermes serve handhabt die API- und Dashboard-Verbindungen, während der Prozess hermes gateway run die Messaging-Kanäle unabhängig verwaltet. Der Desktop-Client verbindet sich mit dem Serve-Backend, nicht mit dem Gateway.

flowchart LR subgraph Server["HEADLESS SERVER"] serve["hermes serve
--host 0.0.0.0
:9119"] gateway["hermes gateway run
Telegram, Discord, Slack"] end subgraph Client["DESKTOP PC"] desktop["hermes desktop
(WebSocket connection)"] end desktop <--->|WebSocket| serve gateway -.->|Shares ~/.hermes/| serve

Zwei Prozesse auf dem Server, eine Anwendung auf dem Client. Beide Serverprozesse verwenden denselben ~/.hermes/-Konfigurationsordner, Fähigkeiten (Skills), Speicher (Memory) und Sitzungen. Cron-Jobs werden auf dem Server ausgeführt, auf dem das Gateway läuft.

Hermes Agent headless server architecture

Für Installation, Provider-Einrichtung und die initiale Konfiguration beginnen Sie mit dem Leitfaden Hermes AI Assistant — Installation, Einrichtung, Workflow und Fehlerbehebung.

Den headless Server einrichten

1. Authentifizierung konfigurieren

Basic Auth bietet ausreichenden Schutz für ein vertrauenswürdiges LAN. Fügen Sie die Anmeldeinformationen zur Umgebungsdatei hinzu:

cat >> ~/.hermes/.env << 'EOF'
HERMES_DASHBOARD_BASIC_AUTH_USERNAME=admin
HERMES_DASHBOARD_BASIC_AUTH_PASSWORD=choose-a-strong-password
HERMES_DASHBOARD_BASIC_AUTH_SECRET=$(openssl rand -base64 32)
EOF
chmod 600 ~/.hermes/.env

Die .env-Datei befindet sich neben config.yaml unter ~/.hermes/. Hermes löst die Konfiguration in folgender Reihenfolge auf: CLI-Überschreibungen zuerst, dann config.yaml, dann .env und schließlich die eingebauten Standardwerte. Geheimnisse (Secrets) gehören in die .env-Datei.

2. Das Backend starten

Starten Sie das Serve-Backend auf allen Schnittstellen:

hermes serve --host 0.0.0.0 --port 9119

Das Backend hört auf Port 9119 und akzeptiert WebSocket-Verbindungen vom Desktop-Client. Überprüfen Sie, ob es läuft, mit einer schnellen Statusabfrage:

curl -s http://localhost:9119/api/status | jq '.auth_required, .auth_providers'
# Erwartet: true  "basic"

3. Als systemd-Dienst ausführen

Für einen persistenten Server, der Neustarts überlebt, installieren Sie einen systemd-Dienst auf Benutzerebene. Erstellen Sie die Einheitsdatei (Unit-File) unter /etc/systemd/user/hermes-serve.service:

[Unit]
Description=Hermes Agent Serve Backend

[Service]
EnvironmentFile=%h/.hermes/.env
ExecStart=/home/rg/.hermes/hermes-agent/venv/bin/python -m hermes_cli.main serve --host 0.0.0.0 --port 9119
Restart=on-failure

[Install]
WantedBy=default.target

Laden Sie den Daemon neu, aktivieren Sie den Dienst und starten Sie ihn:

systemctl --user daemon-reload
systemctl --user enable hermes-serve
systemctl --user start hermes-serve

Überprüfen Sie den Dienststatus:

systemctl --user status hermes-serve

4. Das Gateway starten

Das Gateway ist ein separater Prozess, der Messaging-Kanäle wie Telegram, Discord, Slack und andere handhabt. Starten Sie es unabhängig:

hermes gateway run

Das Gateway und das Serve-Backend sind zwei separate Prozesse. Das Gateway verwaltet Sitzungen, führt Cron-Jobs aus und leitet Nachrichten weiter. Das Serve-Backend bietet die API-Oberfläche für Desktop- und Web-Dashboard-Verbindungen. Sie teilen sich dasselbe Home-Verzeichnis, laufen jedoch unabhängig voneinander.

Für die vollständige Liste der Gateway-Befehle und Unterbefehle siehe die Hermes Agent CLI-Referenz. Wenn Ihre primäre Schnittstelle mobile Messaging-Dienste sind, kombinieren Sie diese Einrichtung mit Hermes Sprachsteuerung vom Handy für sprachbasierte Workflows auf Basis desselben Gateway-Prozesses.

5. Das Backend überprüfen

Bestätigen Sie, dass das Backend antwortet und die Authentifizierung aktiv ist:

curl -s http://localhost:9119/api/status | jq '.auth_required, .auth_providers'

Erwartete Ausgabe:

true
"basic"

Wenn die Authentifizierung nicht aktiviert ist, zeigt die Antwort false für auth_required an. Überprüfen Sie, ob die .env-Datei die korrekten Variablen enthält und dass der Dienst nach Konfigurationsänderungen neu gestartet wurde.

Verbindung vom Desktop-Client herstellen

Option A: Hermes Desktop-App

Installieren Sie Hermes Desktop von der offiziellen Website. Starten Sie die App, navigieren Sie zu Einstellungen → Gateway → Remotes Gateway und geben Sie die Serveradresse ein:

http://<server-ip>:9119

Melden Sie sich mit dem Benutzernamen und Passwort an, die Sie auf dem Server konfiguriert haben.

Alternativ setzen Sie die Remote-URL über eine Umgebungsvariable:

HERMES_DESKTOP_REMOTE_URL=http://<server-ip>:9119 hermes desktop

Option B: Web-Dashboard

Öffnen Sie http://<server-ip>:9119 in einem Browser und melden Sie sich mit den Basic-Auth-Credentials an. Das Web-Dashboard bietet eine browserbasierte Schnittstelle zum Hermes-Backend, ohne dass eine Desktop-Installation erforderlich ist.

Option C: CLI

Konfigurieren Sie im Terminal des Desktop-PCs die Remote-URL über die Einstellungen der Desktop-App oder die Umgebungsvariable HERMES_DESKTOP_REMOTE_URL. Die CLI-Oberfläche verbindet sich über denselben WebSocket-Kanal wie die Desktop-App.

Netzwerk- und Sicherheitsüberlegungen

Szenario Empfehlung
Vertrauenswürdiges LAN --host 0.0.0.0 + Basic Auth
Im Internet exponiert Tailscale verwenden (--host <tailscale-ip>) oder OAuth-Provider
Firewall Port 9119 TCP auf dem Server öffnen

Für ein vertrauenswürdiges lokales Netzwerk ist Basic Auth auf 0.0.0.0 ausreichend. Wenn der Server im Internet exponiert ist, verwenden Sie Tailscale, um an die Tailscale-IP statt an 0.0.0.0 zu binden, oder konfigurieren Sie einen OAuth-Provider für eine stärkere Authentifizierung. Öffnen Sie immer den Port 9119 TCP in der Firewall des Servers, wenn das Backend externe Verbindungen akzeptieren muss.

Wichtige Unterscheidungen zwischen Prozessen

Das Verständnis der Trennung zwischen den beiden Serverprozessen verhindert häufige Konfigurationsfehler:

  • hermes serve — Das Backend, mit dem sich die Desktop-App und das Web-Dashboard verbinden. Handhabt die API-Oberfläche und WebSocket-Verbindungen.
  • hermes gateway run — Der Prozess, der Telegram, Discord, Slack und andere Messaging-Kanäle handhabt. Verwaltet Sitzungen, führt Cron-Jobs aus und leitet Nachrichten weiter.
  • Dies sind zwei separate Prozesse auf dem Server. Sie teilen sich die ~/.hermes/-Konfiguration, Skills, Memory und Sitzungen, laufen aber unabhängig voneinander.
  • Cron-Jobs werden auf dem Server ausgeführt, auf dem das Gateway läuft.
  • Profile, Skills und Memory werden serverseitig konfiguriert. Der Client verbindet sich mit dem bereits konfigurierten Backend.

Für eine profilbasierte Konfiguration und Skills, die auf verschiedene Produktionsrollen abgestimmt sind, siehe Hermes AI Assistant Skills für echte Produktionsumgebungen.

Fehlerbehebung

Desktop kann keine Verbindung zum Server herstellen

  1. Überprüfen Sie, ob das Backend läuft: systemctl --user status hermes-serve
  2. Prüfen Sie, ob der Port offen ist: ss -tlnp | grep 9119
  3. Testen Sie vom Server aus: curl -s http://localhost:9119/api/status
  4. Testen Sie vom Client-Rechner aus: curl -s http://<server-ip>:9119/api/status
  5. Wenn der Client-Test fehlschlägt, überprüfen Sie die Firewall-Regeln: sudo ufw status oder sudo iptables -L

Authentifizierung schlägt fehl

  1. Bestätigen Sie, dass die .env-Datei die richtigen Berechtigungen hat: ls -la ~/.hermes/.env (sollte 600 sein)
  2. Überprüfen Sie, ob das Secret generiert wurde: grep HERMES_DASHBOARD_BASIC_AUTH_SECRET ~/.hermes/.env
  3. Starten Sie den Dienst nach Konfigurationsänderungen neu: systemctl --user restart hermes-serve

Gateway reagiert nicht auf Nachrichten

Das Gateway ist ein separater Prozess vom Backend. Wenn der Desktop verbunden ist, Messaging-Plattformen jedoch nicht funktionieren:

  1. Überprüfen Sie den Gateway-Status: hermes gateway status
  2. Starten Sie das Gateway, falls gestoppt: hermes gateway start
  3. Überprüfen Sie die Logs: hermes logs gateway -f

Referenzen

Dieser Artikel ist Teil des Clusters AI Systems, der sich mit selbst gehosteten Assistenten, Retrieval-Architektur, lokaler LLM-Infrastruktur und Observability befasst.

Abonnieren

Neue Beiträge zu Systemen, Infrastruktur und KI-Engineering.