Im Büro ist das Homelab plötzlich weg: Die Webapp borgt sich jetzt die Verbindungen, die Desktop gespeichert hat


Mittwochnachmittag, ein geliehener Laptop, ein Besprechungsraum. Du öffnest einen Browser, tippst die Webapp-Adresse der Maschine zu Hause ein und willst einen Blick auf die Cron-Jobs werfen, die auf deinem Homelab laufen. Was du bekommst, ist ein einziges Gateway: das lokale. Auf Desktop sind drei oder vier gespeichert, und du könntest ihre Namen aus dem Kopf hersagen – Homelab, Arbeitslaptop, die VPS, die du monatlich bezahlst.

Das ist kein Rechteproblem, und du bist auch nicht ausgeloggt. Die Webapp kannte von Anfang an nur das Gateway, das die Seite ausliefert. Alles andere lag im eigenen Datenverzeichnis der Desktop-App, für die Browser-Seite unsichtbar.

Am 7. November hat ein Batch von Commits das geändert: Gespeicherte Verbindungen sind keine privaten Desktop-Daten mehr, sondern ein Store, den die ganze Maschine teilt. Die Webapp liest dieselbe Liste und kann jeden Eintrag genauso anwählen wie Desktop.

Eine Datei, zwei Hosts

Die Änderung ist unspektakulär: Desktop hielt seine Verbindungs-Registry und die nativen OAuth-Logins im userData-Verzeichnis von Electron. Jetzt liegen sie im Hermes-Home, neben ui-preferences.json:

  • gateway-connections.json — die Verbindungen selbst: Labels, URLs, SSH-Hosts sowie Session-Token und Extra-Header des jeweiligen Eintrags
  • gateway-connection-tokens.json — die OAuth-Logins, pro Verbindung abgelegt

Beide Dateien haben Modus 0600, also nur für den Eigentümer lesbar. Der Main-Prozess von Electron und der Server der Webapp schreiben sie beide und lesen dieselbe Datei – ein in Desktop hinzugefügtes Homelab taucht nach einem Refresh im Browser auf, und umgekehrt, ohne Neustart. Beim ersten Start eines Builds mit der geteilten Liste werden connections.json, connection.json und native-oauth-tokens.json einmalig aus dem alten userData-Verzeichnis kopiert, mit denselben IDs, sodass nichts neu eingerichtet werden muss und keine Duplikate entstehen. Die alten Dateien bleiben unangetastet (ältere Builds laufen weiter) und werden nie wieder gelesen.

Der Schreibvertrag ist der eigentliche Trick, denn hier schreiben zwei Hosts in eine Datei: Schreiber nehmen ein Verzeichnis-Lock <store>.lock, ersetzen die Datei vollständig über Temp-Datei plus Rename, legen eine nicht parsbare Datei als .corrupt-<ms> beiseite statt sie zu überschreiben, und behandeln nur eine fehlende Datei als „kein Store“.

Der Browser spricht weiterhin nur mit einem Gateway

Das ist der Punkt, an dem es viele falsch verstehen. Die Webapp lässt deinen Browser nicht die VPS direkt anwählen – das kann er nicht, und er sollte es auch nicht. Jede Anfrage und jeder Socket aus dem Browser geht weiter an das Gateway, das die Seite ausliefert, und dieses Gateway leitet sie an das gespeicherte Ziel weiter:

  • Token-Modus: das gespeicherte X-Hermes-Session-Token
  • OAuth-Modus: ein refreshbarer Bearer, plus ein Einmal-Ticket für den WebSocket-Handshake
  • dazu alle Extra-Header, die an dieser Verbindung gespeichert sind

Das Remote braucht keine eigene Konfiguration – es sieht einen gewöhnlichen Client. Jedes gespeicherte Gateway erscheint im Gateway-Switcher der Webapp und in den Gateway-Gruppen der Sidebar, du kannst also zwischen ihnen wechseln, nach Gateway & profile gruppieren und Abschnitte per Drag in die gewünschte Reihenfolge bringen (das benennt und sortiert nur Sidebar-Labels um, nie das Gateway).

OAuth wandert ebenfalls auf die Serverseite: Die Maschine, die die Seite ausliefert, fährt den nativen Flow nach RFC 8252 selbst, hält den PKCE-Verifier, schickt den Browser auf /auth/native/authorize des Remotes und empfängt den Callback unter /webapp/gateway-connections/oauth/callback. Tokens rotieren über /auth/native/refresh des Remotes – pro Verbindung ist immer nur einer unterwegs; ein 401 verwirft den Login, ein Ausfall behält ihn.

Wenn dein Browser nicht auf der Maschine läuft, die die Seite ausliefert – der Normalfall, du bist im Büro und das Gateway steht zu Hause –, landet der Redirect auf deinem eigenen Loopback, und der Server sieht ihn nie. Der Verbindungs-Editor bietet dir dann ein Feld, in das du diese Adresse einfügst, womit der Login abgeschlossen ist.

SSH-Verbindungen funktionieren im Browser ebenfalls. Der Server führt eine Portierung von Desktops SSH-Pfad mit: ein ControlMaster zum Host des Eintrags, derselbe serve --isolated --host 127.0.0.1 --port 0-Spawn (mit Session-Token-Datei und Owner-Nonce) unter dem Mutex des Remote-Update-Markers, und ein Forward nur auf 127.0.0.1, auf den das Relay zielt. Die Ownership ist auf den Verbindungs-Store dieser Maschine begrenzt, Desktop und Gateway räumen also nie gegenseitig ihr serve ab. Beide Enden müssen Linux oder macOS sein; ein Windows-Remote oder ein lokaler Windows-Host wird als nicht unterstützte Plattform abgelehnt.

Der Preis, offen gesagt

Hier möchte ich, dass du innehältst und zweimal liest.

Die Vertrauensgrenze der Webapp lautet „wer sich auf dieser Seite anmelden kann“. Sobald jemand das kann, kann er jedes auf dieser Maschine gespeicherte Gateway nutzen – als derjenige, dem die gespeicherte Credential gehört. Die Doku sagt es ohne Beschönigung: Speichere nur Gateways, zu denen diese Leute Zugang haben sollen.

Was den Schaden begrenzt, ist das, was der Browser mit den Antworten tun kann: Eine weitergeleitete Antwort läuft unter einer sandboxenden Content-Policy, wird vom Browser nie gecacht und kann nicht außerhalb dieses Gateways umleiten; das Relay führt keinen Cookie-Jar; das Entfernen einer Verbindung schließt ihre offenen Sockets sofort.

Fünf Gründe, warum eine Credential an der falschen Adresse landen konnte

Die Hälfte dieses Batches sind Bugfixes, und sie gehören alle zu einer Familie: Credential und Zieladresse konnten auseinanderlaufen. Dieser Teil ist lehrreicher als das Feature.

Erstens: zwei Reads pro Dial. Beim Dialing wurde früher die URL des Eintrags gelesen und danach Token, Header und Login noch einmal per ID. Ein Edit zwischen diesen Reads kombinierte die alte Adresse mit der Credential des neuen Eintrags. Der Store liefert jetzt einen einzigen Dial-Snapshot – Eintrag, URL, Token, Header und der URL-gebundene Login aus einem Registry-Read. Der Token-Modus wählt die URL des Snapshots; ensure_access_token von OAuth gibt das Token zusammen mit der Adresse zurück, die es ausgestellt hat, und das Socket-Ticket wird nur von der Adresse geprägt, die der Socket tatsächlich anwählt.

Zweitens: Logins waren nicht an die URL gebunden, die sie ausgestellt hat. Token-Sets wurden per Connection-ID abgelegt, und IDs sind wiederverwendete Label-Slugs. Ändere eine URL oder entferne den Eintrag und füge ihn unter demselben Label neu hinzu, und das Relay konnte den Bearer von Host A an Host B schicken und das Refresh-Token von Host A per POST an /auth/native/refresh von Host B. Jedes gespeicherte Set trägt jetzt seine ausstellende baseUrl; ein Set, dessen baseUrl von der aktuellen URL des Eintrags abweicht, gilt in beiden Twins als ausgeloggt, und Refresh-Posts gehen nur an die eigene URL des Sets. Jeder Registry-Write, der einen Eintrag entfernt oder seine url oder authMode ändert, verwirft das Set auf beiden Seiten.

Drittens: eine Cross-Site-Seite konnte dein Relay ausleihen. Das Session-Cookie der Webapp ist SameSite=Lax, eine Cross-Site-Top-Level-Navigation zu /api/relay/<id>/<path> trug es also mit, und das Relay führte dieses GET mit der gespeicherten Credential auf dem gespeicherten Gateway aus. Die Antwort war gesandboxt und unlesbar, aber ein Remote-GET mit Nebenwirkungen lief trotzdem. Jetzt bekommt eine weitergeleitete Anfrage, deren Sec-Fetch-Site vorhanden und nicht same-origin ist, ein 403, bevor irgendetwas gesendet wird; die Fetches der Seite selbst und Clients, die keine Fetch-Metadata senden, werden wie bisher weitergeleitet.

Viertens: ein eingefügter Callback konnte gegen die falsche Verbindung eingelöst werden. Die Fertigstellung löste früher den Code ein und speicherte die Tokens, und verglich erst danach die Verbindung des Flights mit der ID im Pfad. Der Flight wird jetzt unter dem Flights-Lock geprüft, bevor eingelöst wird: Ein für eine andere Verbindung eingefügter Redirect bekommt ein 400, ohne einen einzigen Token-Request, und der eigene Flight dieser Verbindung bleibt nutzbar.

Fünftens: Klonen und Exportieren trugen Klartext-Tokens nach draußen. hermes profile create --clone-all kopierte beide maschinenweiten Stores ins Klon, und hermes profile export verschickte danach Klartext-Session-Tokens, weil der Scrubber des Exports den Envelope {"encoding":"plain","value":…} nicht erkannte. Beide Stores kamen in PROFILE_CREDENTIAL_PATHS; clone-all überspringt sie und ihr .lock-Verzeichnis; der Export-Scrub maskiert jeden Envelope im gestagten JSON.

Wo wir gerade dabei sind: Warum liegen diese Secrets im Klartext auf der Platte statt im Keychain des Betriebssystems? Weil der Server der Webapp sie lesen muss und es für einen Serverprozess kein Keychain gibt. Der Schutz sind die Dateirechte, plus eine Grenze – Renderer und Plugins sehen nie Token-Bytes (das host.connections() des Plugin-SDKs gibt nur Labels, Arten und die primäre ID zurück). Ein Secret, das ein älterer Build mit safeStorage verschlüsselt hat, wird beim Import einmal entschlüsselt; eines, das sich nicht entschlüsseln lässt, wird nicht verworfen, sondern bleibt, wie es war, und steht in importNotices der Datei, bis das Keychain von Desktop antwortet und es konvertiert.

So benutzt du es

Desktop und die Webapp teilen den Pfad, weil sie die Seite teilen: Settings → Gateways. Scrolle zu Registered gateways und klicke auf Add connection:

  • Local — die Runtime, die diese App verwaltet (app-managed, nicht entfernbar)
  • Remote gateway — ein laufendes hermes serve; URL angeben und Session-Token oder OAuth wählen
  • SSH — ein kombiniertes Feld user@host:22, plus optional der vollständige Pfad zur remote hermes-Binary
  • Hermes Cloud — kommt aus dem Portal-Login und dem Discovery-Flow, keine handgetippte URL

Dann klicke auf Test. Der Test prüft beide Beine der Verbindung, HTTP und WebSocket, sodass „Reachable“ heißt, dass der Chat wirklich funktioniert und nicht nur der Port antwortet. In der Webapp öffnet Test bei einer SSH-Zeile denselben verwalteten Tunnel, den das Gateway benutzt, und startet (oder verwendet) hermes serve auf dem Remote; dieser Tunnel wird dir nicht weggeräumt – er endet, wenn du die Verbindung entfernst oder das Gateway stoppst, oder von selbst nach dem Remote-Idle-Timeout dashboard.ssh_isolated_idle_grace_s (standardmäßig 15 Minuten) ohne Client und ohne Arbeit.

Duplikate werden beim Speichern abgelehnt: genau ein lokaler Eintrag; Remote- und Cloud-Einträge deduplizieren über die normalisierte URL (über beide Arten hinweg, ein Cloud-Eintrag und ein Remote-Eintrag können also nicht auf dieselbe URL zeigen); SSH-Einträge deduplizieren über user@host:port plus Remote-Profil.

Wann du es wirklich bekommst

Ehrlich: noch nicht, wenn du offizielle Releases fährst. Diese Commits landeten am 7. November, und v0.23.0 erschien am 5. November – sie sind auf main und in keinem Tag. hermes update liefert Releases, du wartest also auf das nächste, oder du folgst main.

Update (10.11.2026): Diese Änderungen sind mit v0.23.1 (9. November) erschienen – ein hermes update genügt. Die Aussage „nicht in v0.23.0“ oben stimmt weiterhin; v0.23.1 schließt die Lücke.

Bis dahin funktionieren die gespeicherten Verbindungen von Desktop schon eine Weile (siehe Multi-Gateway-Leitfaden für die Desktop-App). Geändert hat sich, dass die Browser-Hälfte aufhört, ein Bürger zweiter Klasse zu sein.

Und wenn dein Login am Remote-Gateway dich mit Loopback-Redirects und Jump-Hosts geärgert hat: Die drei Wege in OAuth auf einem Remote-Server abschließen gelten weiter. Neu ist, dass der Server den kompletten nativen Flow für dich fährt und dir erlaubt, die Adresse einzufügen, wenn der Callback auf der falschen Maschine landet.

Die Kurzfassung

Gespeicherte Gateway-Verbindungen sind von der Privatsache einer Desktop-App zu geteilter Maschinen-Infrastruktur geworden: eine 0600-JSON-Datei, zwei Hosts, die sie schreiben, ein Browser, der nur mit seinem ausliefernden Gateway spricht, Credentials, die an eine Adresse gebunden sind, bevor sie weitergeleitet werden. Die Fähigkeit selbst ist simpel. Die fünf Fixes sind der wertvolle Teil – sie zeigen, dass „zu wem gehört diese Credential“ überall zur Falle wird, sobald Edits und gleichzeitige Writes von mehreren Hosts erlaubt sind.

Zur Kommando-Oberfläche siehe die hermes gateway-Referenz der Seite; für die Desktop-Seite beschreibt der Leitfaden zum Interface-Modus, wie die App lokale und entfernte Backends darstellt.