Hermes Agent Web Dashboard: Lokaler Zugriff, Profile und Diagnose

Das grafische Hermes Agent Web Dashboard ermöglicht die browserbasierte Administration Ihrer Agenten-Installation, sodass Konfigurationsdateien nicht mehr direkt manuell bearbeitet werden müssen. Über das Dashboard können Sie API-Zugangsschlüssel verwalten, aktive Profile wechseln, vergangene Sitzungen einsehen und ein eingebettetes Terminal starten, ohne die Systemumgebung manuell anpassen zu müssen.

Grundlegender Start und Systemabhängigkeiten

Standardmäßig bindet sich das Dashboard an das Loopback-Interface:

hermes dashboard

Dieser Befehl startet einen lokalen HTTP-Server und öffnet http://127.0.0.1:9119 in Ihrem Standardbrowser. Falls dieser Port bereits durch einen anderen lokalen Dienst belegt ist, können Sie ihn mit dem Flag --port überschreiben:

hermes dashboard --port 9120 --no-open

Das Flag --no-open verhindert das automatische Öffnen eines neuen Browser-Tabs, was sich besonders für Hintergrundprozesse oder Automatisierungsskripte eignet.

Das Basispaket hermes-agent enthält den Web-Stack standardmäßig nicht. In Linux-, macOS- und WSL2-Umgebungen installieren Sie die erforderlichen optionalen Komponenten in die virtuelle Umgebung des Agenten:

cd ~/.hermes/hermes-agent && uv pip install -e ".[web,pty]"

Das Extra web installiert FastAPI sowie Uvicorn, während pty das Paket ptyprocess für POSIX-Systeme bereitstellt. Für das Erstellen des statischen Frontends des Dashboards ist eine aktive Node.js-Installation erforderlich (sofern npm vorhanden ist, wird das Frontend beim ersten Start automatisch kompiliert).

Plattformgrenzen: Natives Windows vs. WSL2

Gemäß dem Leitfaden für natives Windows unterstützt eine native Windows-Installation die Ansichten für Konfiguration, Metriken, Aufgaben und die Sitzungsdatenbank. Der eingebettete Terminal-Tab /chat setzt jedoch POSIX-PTY-Pseudoterminals voraus. Da natives Windows diese Schnittstelle nicht unterstützt, müssen Sie den Agenten innerhalb von WSL2 ausführen, um vollständige interaktive Terminal-Sitzungen im Browser nutzen zu können.

Ebenso wichtig ist die Trennung der Prozesse: Das Web-Dashboard und die Messaging-Gateways (etwa für Telegram, Discord oder andere Plattformen) laufen als unabhängige Daemons. Der Start der Weboberfläche startet oder aktiviert die Plattform-Gateways nicht automatisch.

Profilverwaltung und Modellkonfiguration

Das Dashboard arbeitet auf Systemebene und ermöglicht die zentrale Administration aller konfigurierten Profile. Ein Profilwechsel in der Seitenleiste aktualisiert den Arbeitskontext über den URL-Abfrageparameter ?profile=<name>.

1. Bereiche Config und API Keys: Die Seite Config bearbeitet Parameter in config.yaml, wobei Änderungen über die Schaltfläche „Save“ gespeichert werden. Die Seite API Keys verwaltet hingegen Umgebungsvariablen in ~/.hermes/.env: Schlüssel werden einzeln für jede Variable gesetzt oder entfernt, ohne eine globale Speichern-Schaltfläche oder eine gebündelte Validierung aller Felder.
2. Konsistenz von Provider und Modell: Das ausgewählte Modell und die Zugangsdaten müssen strikt demselben Anbieter entsprechen. Wenn Sie einen OpenAI-kompatiblen Drittanbieter-Dienst anbinden, prüfen Sie die Vorgaben des Anbieters: Relevante Felder, Modell-IDs und Verbindungseinstellungen sind beispielsweise im BetterToken-Leitfaden dokumentiert. Ein Drittanbieter stellt lediglich den unabhängigen API-Modellzugriff bereit und hostet weder das Hermes-Dashboard noch verwaltet er Netzwerktunnel.
3. Funktionsprüfung über Sessions: Senden Sie für eine manuelle Funktionsprüfung einen kurzen, reinen Lese-Prompt. Beachten Sie, dass Testanfragen vom Anbieter abgerechnet werden können. Eine erfolgreiche Inferenz wird bestätigt, sobald Sie eine inhaltliche Antwort in der Oberfläche erhalten und der Token-Verbrauch in den Sitzungsmetadaten oder beim Provider erfasst wird. Das bloße Erscheinen eines neuen Eintrags in der Liste des Tabs Sessions belegt lediglich die Erstellung eines Datensatzes und stellt keine Bestätigung für eine erfolgreiche Antwort des Modells dar.

Sicherer Fernzugriff

Standardmäßig lauscht der Webserver ausschließlich auf 127.0.0.1. Bei einer Bindung an externe Schnittstellen (--host 0.0.0.0) greift automatisch ein Authentifizierungs-Gate. Wenn kein Authentifizierungsanbieter konfiguriert ist, bricht der Agent die Ausführung mit einem Fehler ab (Fail-Closed). Das veraltete Flag --insecure umgeht die Authentifizierung nicht mehr. Öffentliche oder externe Netzwerkbindungen erfordern gemäß der Hermes-Agent-Dokumentation zwingend eine Authentifizierung.

Die empfohlene Methode, um sich ohne Freigabe externer Ports mit einem Remote-Server zu verbinden, ist die lokale Portweiterleitung über einen SSH-Tunnel (ersetzen Sie user@your-server durch die Adresse und den Benutzernamen Ihres Servers):

ssh -N -L 9119:127.0.0.1:9119 user@your-server

Falls der lokale Port 9119 auf Ihrer Arbeitsstation bereits durch einen anderen Prozess belegt ist, verwenden Sie die Variante mit einem alternativen lokalen Port:

ssh -N -L 9120:127.0.0.1:9119 user@your-server

Bei diesem Ansatz lauscht der Hermes-Server auf dem entfernten Rechner weiterhin ausschließlich auf dem lokalen Loopback-Interface 127.0.0.1, der Datenverkehr wird durch den Tunnel verschlüsselt und das Dashboard lässt sich auf Ihrer Arbeitsstation unter http://127.0.0.1:9119 (oder http://127.0.0.1:9120 bei Verwendung des alternativen lokalen Ports) aufrufen.

Schritt-für-Schritt-Fehlerdiagnose

Beim Auftreten von Fehlern ist es wichtig, die fehlerhafte Schicht gezielt zu isolieren, anstatt die gesamte Kette auf einmal zu prüfen.

+----------------------------------------------------------------+
| 1. HTTP-транспорт      | 127.0.0.1:9119 /api/status            |
+------------------------+---------------------------------------+
| 2. Окружение и PTY     | Node.js / POSIX ptyprocess (WSL2)     |
+------------------------+---------------------------------------+
| 3. Сокеты и каналы     | /api/pty (Chat) / /api/ws (Desktop)   |
+------------------------+---------------------------------------+
| 4. Провайдер инференса | Ключи API, лимиты и сетевой эндпоинт  |
+----------------------------------------------------------------+

Die im obigen Entscheidungsbaum dargestellten Diagnoseebenen umfassen:

• Ebene 1 (HTTP-Transport): 127.0.0.1:9119 /api/status
• Ebene 2 (Umgebung und PTY): Node.js / POSIX ptyprocess (WSL2)
• Ebene 3 (Sockets und Kanäle): /api/pty (Chat) / /api/ws (Desktop)
• Ebene 4 (Inferenzanbieter): API-Schlüssel, Limits und Netzwerk-Endpunkt

1. Netzwerkebene (HTTP): Die Erreichbarkeit von GET /api/status beweist lediglich, dass der Uvicorn-Prozess läuft und auf HTTP-Anfragen antwortet. Dieser offene Endpunkt garantiert weder eine erfolgreiche Authentifizierung noch die Einsatzbereitschaft des interaktiven Chats.
2. PTY- und Schnittstellenebene: Ein Connection closed-Fehler kann verschiedene Ursachen haben. Unter nativem Windows liegt eine typische Diagnoseursache im Fehlen von POSIX-PTY-Unterstützung (in diesem Fall sollte der Start in eine WSL2-Umgebung verlegt werden). In anderen Umgebungen ist dieses Symptom nicht allein auf PTY zurückzuführen und erfordert eine Prüfung der Systemprotokolle sowie der Socket-Verbindungen. Fehler beim Erstellen der Stile oder ein weißer Bildschirm erfordern die Überprüfung der Node.js-Version und einen erneuten Build der Abhängigkeiten.
3. Socket-Kanäle und Autorisierung: Das im Browser eingebettete Terminal nutzt die Route /api/pty, während sich der entfernte Desktop-Client über /api/ws verbindet. Meldet der Client die Erreichbarkeit des Backends, während die Sitzung nicht reagiert, überprüfen Sie die Verbindung des entsprechenden Kanals: Typische Fehlerquellen sind fehlende oder abgelaufene Sitzungstickets sowie der DNS-Rebinding-Schutz, wenn der Host-Header nicht mit der Bind-Adresse übereinstimmt.
4. Modell-Provider-Ebene: Antwortverzögerungen oder Fehlermeldungen nach dem Absenden einer Nachricht im aktiven Terminal sind zumeist auf API-Ebene angesiedelt (etwa ungültige Schlüssel in .env, Nichterreichbarkeit des Provider-Endpunkts, Limits oder Guthaben). Fehler des Anbieters bedeuten jedoch nicht automatisch, dass der Dashboard-Server selbst fehlerfrei arbeitet: Bei Störungen kann zusätzlich eine Überprüfung des Laufzeitstatus und des Sitzungszyklus erforderlich sein.