Root Cause fuers "geht trotzdem ans LLM": unser fast-paths-Plugin war auf
pre_gateway_dispatch registriert -- der Hook feuert laut Sourcecode nur fuer
die Gateway-Plattformen (Telegram/Discord/...), nicht fuer die TUI
(tui_gateway/server.py), die komplett am Gateway-Dispatcher vorbei direkt in
den Agent-Loop laeuft. Ein Patch an tui_gateway/server.py waere noetig
gewesen, aber Concurrency-kritischer Kern-Code -- zu riskant.
Hermes hat dafuer schon einen eigenen Mechanismus: quick_commands (type:
exec) bypassen den Agent-Loop nachweislich auf JEDER Plattform inkl. TUI,
kein LLM-Call, keine Tokens, offiziell dokumentiert. Trade-off: fester
Slash-Befehl statt Freitext (/next statt "naechstes Lied") -- gleiches
Prinzip wie Alexas Intent-Slots, ohne Slot-Fuellung.
scripts/spotify_quick.py buendelt next/previous/pause/play/volume_up/
volume_down/current in einem Skript (ein Argument pro Aktion), nutzt
denselben SpotifyClient wie der echte Tool-Dispatch. docker-compose.yml
mountet scripts/ jetzt read-only nach /opt/data/scripts statt fast-paths/
nach /opt/data/plugins/fast-paths.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Motivation: selbst mit allen bisherigen Proxy-Fixes braucht jede Nachricht
mindestens einen vollen LLM-Turn (mehrere Sekunden). Fuer "pause" oder
"naechstes Lied" unnoetig langsam -- Alexa & Co. loesen sowas ohne
generatives Modell per Intent-Klassifikation in Millisekunden.
Neues Hermes-Plugin fast-paths/, haengt am pre_gateway_dispatch-Hook
(feuert bei JEDER eingehenden Nachricht auf JEDER Plattform, noch VOR
Auth/Pairing und Agent-Dispatch -- gefunden im echten Hermes-Sourcecode,
hermes_cli/plugins.py + gateway/run.py). Matcht der normalisierte Text
gegen eine Regex, wird der Handler direkt ausgefuehrt und das LLM komplett
uebersprungen. Ein File pro Skill unter patterns/ (analog zu ARIAs eigenen
fast_patterns), erster Skill: patterns/spotify.py (pause/next/previous/
volume/current, plus "spiel Playlist X auf Geraet Y ab" per Fuzzy-Match
ohne LLM fuer den Freitext-Namen).
Sicherheit: pre_gateway_dispatch feuert VOR Hermes' eigener Autorisierung
-- der Loader prueft deshalb explizit gateway._is_user_authorized() vor
jedem Pattern-Treffer, sonst koennte ein nicht autorisierter Absender per
Fast-Path an Hermes vorbei Aktionen ausloesen. Handler koennen sich zudem
bewusst per Rueckgabe None zurueckziehen (z.B. mehrdeutiger Playlist-Name)
und faellen dann normal ans LLM zurueck statt zu raten.
Lokal verifiziert (Testharness auf aria-wohnung, Hermes' eigenen
_load_directory_module-Lademechanismus nachgebaut, gemockter SpotifyClient):
Matching, Sicherheits-Check bei nicht autorisiertem Sender, Fuzzy-Match
fuer Playlist+Geraet, und mehrere Regression-Faelle gegen False-Positives
bei laengeren/anderen Saetzen -- alle Faelle bestehen.
docker-compose.yml: neuer verschachtelter Read-Only-Mount
./fast-paths -> /opt/data/plugins/fast-paths (User-Plugin-Pfad unter
$HERMES_HOME). Muss zusaetzlich einmalig in config.yaml unter
plugins.enabled aktiviert werden (Hermes-Plugins sind Opt-in) -- siehe
README.md und fast-paths/README.md.
Prueft direkt in Hermes' eigenem Code (get_auth_status, _get_platform_tools,
SpotifyClient), ob Toolset aktiviert, Login vorhanden und ein echter
GET /me/player/devices erfolgreich ist -- ohne Umweg ueber Claude/Proxy,
da LLM-Textantworten wie 'nicht verbunden/aktiv' kein verlaesslicher
Diagnosewert sind.
hermes-proxy laeuft mit echter Claude-Code-CLI-Session auf ggf. demselben
Anthropic-Account wie ARIA -> account-weite Connectors (Gmail/Calendar/Drive)
und Claude Codes eigenes Skill-System wurden automatisch mitgeladen und
haben mit den per Prompt injizierten <tool_call>-Tools (Hermes-Plugins wie
Spotify) konkurriert. --safe-mode deaktiviert alle nativen Customizations
fuer diese Session, sodass nur noch die injizierten externen Tools sichtbar
sind.
Root Cause im echten Hermes-Sourcecode (hermes_cli/web_server.py,
_ws_host_origin_reason) verifiziert, nicht geraten: WebSocket-Upgrades
(/api/ws, /api/pub, /api/events) haben einen zweiten Guard neben dem
Host-Header, der zusaetzlich den Origin-Header gegen den Bind (127.0.0.1)
prueft. Browser schickt die echte Server-Adresse als Origin -> origin_mismatch
-> WS wird mit 4403 (Browser: 1006) geschlossen, komplett ohne Logging
(anders als /api/console + /api/pty). Fix: Origin-Header in Caddy entfernen,
dann ueberspringt Hermes den Check ganz.
hermes-agent-dashboard als separater Container ist raus. Stattdessen
supervised s6 Gateway und Dashboard jetzt als Geschwister-Prozesse im
selben hermes-agent-Container (HERMES_DASHBOARD=1 + HERMES_DASHBOARD_HOST=
127.0.0.1) -- laut Startup-Log selbst "the recommended setup for the s6
container image". Das ist der wahrscheinliche Fix fuer zwei offene Bugs:
Dashboard zeigte Gateway-Status immer als "Stopped" (lokale Prozess-
Inspektion sah den Gateway-Prozess im getrennten Container nie) und der
Restart-Button warf "no such gateway 'default'" (loeste s6-Services nur im
eigenen Container auf). README + Architektur-Diagramm entsprechend
aktualisiert.
Hermes' Dashboard-Backend prueft den eingehenden Host-Header gegen den
Host, an den es gebunden ist -- Caddy reichte bisher den originalen
Host-Header vom Browser (Server-IP/Domain) durch, was Hermes als
'Invalid Host header' ablehnte. header_up ueberschreibt den Host jetzt
explizit. Plus Troubleshooting-Eintrag in der README.
Hermes' eigenes Auth-Gate (dashboard.basic_auth/HERMES_DASHBOARD_PASSWORD_HASH)
engagiert sich laut eigener Fehlermeldung ohnehin nur bei einem 0.0.0.0-Bind,
der Dashboard-Container bindet aber fest auf 127.0.0.1 -- das Gate haette hier
nie gegriffen. Statt es als "Fallback falls Bind mal wieder wandert" zu
behalten, jetzt sauber raus: HERMES_DASHBOARD_PASSWORD_HASH aus .env.example
und docker-compose.yml, der auskommentierte dashboard:-Block aus
config.yaml.example, README-Setup auf 8 statt 9 Schritte umnummeriert.
Caddy (TLS + eigene Basic-Auth) ist damit die einzige noetige Auth-Schicht --
ein Layer statt zwei, weniger Setup, weniger Verwirrung. Stale Kommentare im
Caddy-Compose-Block (redeten noch von "zweiter Basic-Auth-Schicht noetig weil
unklar ob dashboard.basic_auth greift") ebenfalls korrigiert.
Dashboard bindet seit dem Caddy-Umbau nur noch auf 127.0.0.1 -- Hermes'
Auth-Gate engagiert sich laut eigener Fehlermeldung NUR bei einem
0.0.0.0-Bind, greift also gar nicht mehr. HERMES_DASHBOARD_PASSWORD_HASH
ist damit optional statt Pflicht (kein docker-compose-Abbruch mehr bei
leerem Wert), der dashboard: basic_auth-Block in config.yaml.example ist
standardmaessig auskommentiert. Caddy (TLS + eigene Basic-Auth) bleibt
die einzige im Normalbetrieb noetige Auth-Schicht. README/.env.example
entsprechend entschlackt -- Hash-Erzeugen + Dollarzeichen-Escaping nur
noch als Fallback dokumentiert, falls der Bind mal wieder auf 0.0.0.0
wandert.
Entrypoint im caddy-Service prueft beim Start ob /certs/dashboard.{crt,key}
schon existiert und erzeugt es sonst selbst (apk add openssl + req -x509,
100 Jahre). Persistent im Volume, kein manueller Schritt mehr noetig.
Manuelle Erzeugung bleibt als Fallback in der README dokumentiert (z.B.
fuer eigenes /CN).
Stefans Entscheidung: 0.0.0.0-Bind mit unverschluesseltem Basic-Auth war nur
Testzustand. Jetzt bindet hermes-agent-dashboard wieder auf 127.0.0.1, ein
neuer Caddy-Service (network_mode: host) terminiert TLS auf 443 mit einem
manuell erzeugten selbstsignierten Zertifikat (100 Jahre Laufzeit, kein
Let's-Encrypt-Domain-Zwang) und erzwingt eine zweite, eigene Basic-Auth-Schicht
(bcrypt-Hash in CADDY_BASIC_AUTH_HASH, getrennt von Hermes' pbkdf2-Hash) -
noetig weil Hermes' eigenes Auth-Gate laut Fehlermeldung nur bei 0.0.0.0-Binds
"engagiert". README + .env.example um die Setup-Schritte (Cert-Erzeugung,
Caddy-Hash, $-Escaping-Falle) ergaenzt.
docker-compose interpretiert rohe $-Zeichen im pbkdf2-Hash (.env) selbst
als Variablen-Referenzen und ersetzt sie stillschweigend durch Leerstring
(sichtbar als "WARN variable is not set"). Ergebnis: verstümmelter Hash,
Dashboard bleibt trotz "richtig" eingetragener Werte bei "no auth
providers are registered" haengen. Fix: jedes $ im Hash durch $$ ersetzen.
README dokumentierte den seit 19.07.2026 pflichtigen Dashboard-Auth-Block
(HERMES_DASHBOARD_USER/PASSWORD_HASH, dashboard.basic_auth in config.yaml)
noch gar nicht - neuer Setup-Schritt 4, Schritt 7/8 umnummeriert, Architektur-
Diagramm und Sicherheitshinweis auf den 0.0.0.0-Dashboard-Stand gebracht.
Nebenbei echten Bug gefunden: .env.example und config.yaml.example sagten,
den Passwort-Hash per 'docker exec hermes-agent-dashboard' zu erzeugen -
aber genau dieser Container startet ohne bereits gesetztes
HERMES_DASHBOARD_PASSWORD_HASH gar nicht (docker-compose :?-Pflichtvar).
Hash muss gegen 'hermes-agent' erzeugt werden, der teilt sich das Image
ohne die Pflicht-Var.
Stefan-Entscheidung: Hermes Agent (Nous Research) laeuft auf derselben
Maschine wie der Claude-Max-Proxy, nicht mehr remote. Ergaenzt:
- hermes-agent + hermes-agent-dashboard Services (offizielle Definition,
gebaut aus separat geklontem hermes-agent-src/), network_mode: host
- hermes-agent-config/config.yaml.example: seedet Hermes' model:-Block
automatisch auf provider: custom -> unser hermes-gateway, per ${VAR}-
Expansion aus .env (kein manuelles Config-Editieren mehr)
- hermes-gateway bindet jetzt nur noch auf 127.0.0.1 statt 0.0.0.0, da
Hermes lokal mitlaeuft und kein Remote-Zugriff mehr noetig ist
- .gitignore fuer hermes-agent-src/, hermes-data/, .env (Secrets/Sourcecode
gehoeren nicht ins Repo)
- README auf Single-Machine-Architektur aktualisiert, inkl. Setup-Schritten
und Einordnung des optionalen API_SERVER (fuer spaeteren mobilen Client,
andere Richtung als unser Proxy)
ARIAandClaude Sonnet 5