En la oficina tu homelab desaparece: la Webapp ahora toma prestadas las conexiones que guardó Desktop


Miércoles por la tarde, un portátil prestado, una sala de reuniones. Abres el navegador, escribes la dirección de la Webapp de la máquina que tienes en casa y quieres echar un vistazo rápido a los cron jobs que corren en tu homelab. Lo que aparece es un solo gateway: el local. En Desktop tienes tres o cuatro guardados y podrías recitar sus nombres de memoria: Homelab, el portátil del trabajo, ese VPS que pagas cada mes.

No es un problema de permisos y no es que se te haya cerrado la sesión. La Webapp solo conocía el gateway que sirve la página. Todo lo demás vivía en el directorio de datos de la app de escritorio, invisible para el lado del navegador.

El 7 de noviembre una tanda de commits cambió eso: las conexiones guardadas dejaron de ser datos privados de Desktop y pasaron a ser un único almacén que comparte toda la máquina. La Webapp lee la misma lista y puede marcar cualquier entrada igual que lo hace Desktop.

Un archivo, dos hosts

El cambio es sencillo: Desktop guardaba su registro de conexiones y los inicios de sesión nativos de OAuth en el directorio userData de Electron. Ahora viven en el home de Hermes, junto a ui-preferences.json:

  • gateway-connections.json — las conexiones en sí: etiquetas, URLs, hosts SSH y el token de sesión y las cabeceras extra propios de cada entrada
  • gateway-connection-tokens.json — los inicios de sesión OAuth, indexados por conexión

Ambos con permisos 0600, solo para el propietario. El proceso principal de Electron y el servidor de la Webapp escriben y leen el mismo archivo, así que añadir Homelab en Desktop aparece en el navegador tras un refresco, y al revés, sin reiniciar. El primer arranque de una build con la lista compartida copia una sola vez connections.json, connection.json y native-oauth-tokens.json desde el viejo directorio userData, manteniendo los mismos ids, de modo que no hay que configurar nada de nuevo ni aparecen duplicados. Los archivos antiguos se dejan intactos (las builds viejas siguen funcionando) y no se vuelven a leer.

El contrato de escritura importa, porque que dos hosts escriban un mismo archivo es justo el truco: quien escribe toma un lock de directorio <store>.lock, reemplaza el archivo entero mediante archivo temporal y rename, aparta un archivo ilegible como .corrupt-<ms> en lugar de sobrescribirlo, y solo trata un archivo ausente como «no hay almacén».

El navegador sigue hablando con un único gateway

Aquí es donde la gente se equivoca. La Webapp no hace que tu navegador marque el VPS directamente: no puede y no debería. Cada petición y cada socket del navegador siguen yendo al gateway que sirve la página, y ese gateway lo reenvía al destino guardado:

  • modo token: el X-Hermes-Session-Token guardado
  • modo OAuth: un bearer renovable, con un ticket de un solo uso para el handshake del WebSocket
  • más cualquier cabecera extra guardada en esa conexión

El remoto no necesita configuración propia: ve a un cliente corriente. Cada gateway guardado se suma al selector de gateways de la Webapp y a los grupos de gateway de la barra lateral, así que puedes cambiar entre ellos, agrupar por Gateway & profile y arrastrar secciones al orden que quieras (eso solo renombra y reordena etiquetas de la barra lateral, nunca el gateway).

OAuth también pasó al lado del servidor: la máquina que sirve la página ejecuta el flujo nativo de la RFC 8252, guarda el verificador PKCE, envía el navegador a /auth/native/authorize del remoto y recibe el callback en /webapp/gateway-connections/oauth/callback. Los tokens rotan contra /auth/native/refresh del remoto: uno en vuelo por conexión a la vez; un 401 tumba el inicio de sesión, una caída del servicio lo mantiene.

Si tu navegador no está en la máquina que sirve la página —lo normal, porque estás en la oficina y el gateway en casa— la redirección cae en tu propio loopback y el servidor no la ve nunca. El editor de conexiones te da entonces un campo para pegar esa dirección de vuelta, y con eso se completa el inicio de sesión.

Las conexiones SSH también funcionan en el navegador. El servidor lleva un port del camino SSH de Desktop: un ControlMaster al host de la entrada, el mismo spawn serve --isolated --host 127.0.0.1 --port 0 (con un archivo de token de sesión y un nonce de propietario) bajo el mutex del marcador de actualización remoto, y un forward solo en 127.0.0.1 al que apunta el relay. La propiedad está acotada al almacén de conexiones de esta máquina, así que Desktop y el gateway nunca se matan el serve del otro. Ambos extremos tienen que ser Linux o macOS; un remoto o un host local Windows se rechaza por plataforma no soportada.

El precio, dicho sin rodeos

Aquí quiero que pares y lo leas dos veces.

El límite de confianza de la Webapp es «cualquiera que pueda iniciar sesión en esta página». En cuanto alguien puede, puede usar todos los gateways guardados en esta máquina, como quien sea dueño de la credencial guardada. La documentación lo dice sin suavizar: guarda solo gateways a los que dejarías llegar a esa gente.

Lo que acota el radio de daño es lo que el navegador puede hacer con las respuestas: una respuesta retransmitida corre bajo una política de contenido con sandbox, el navegador nunca la cachea y no puede redirigir fuera de ese gateway; el relay no guarda tarro de cookies; quitar una conexión cierra sus sockets abiertos de inmediato.

Cinco motivos por los que una credencial puede acabar en la dirección equivocada

La mitad de esta tanda son correcciones de bugs, y todas son de la misma familia: la credencial y la dirección a la que se envió podían no coincidir. Esa parte enseña más que la funcionalidad.

Uno: dos lecturas por marcado. Marcar leía la URL de la entrada y luego, por id, volvía a leer su token, sus cabeceras y su inicio de sesión. Una edición que cayera entre ambas lecturas emparejaba la dirección vieja con la credencial nueva. Ahora el almacén entrega un único snapshot de marcado —entrada, URL, token, cabeceras y el inicio de sesión atado a la URL— de una sola lectura del registro. El modo token marca la URL del snapshot; ensure_access_token de OAuth devuelve el token junto con la dirección que lo emitió, y el ticket del socket solo lo acuña la dirección a la que el socket marca de verdad.

Dos: los inicios de sesión no estaban atados a la URL que los emitió. Los conjuntos de tokens se indexaban por id de conexión, y los ids son slugs de etiqueta que se reciclan. Cambia una URL, o borra y vuelve a añadir con la misma etiqueta, y el relay podía mandar el bearer del host A al host B y hacer POST del refresh token del host A a /auth/native/refresh del host B. Ahora cada conjunto guardado lleva su baseUrl emisora; un conjunto cuya baseUrl difiere de la URL actual de la entrada se lee como sesión cerrada en los dos gemelos, y el refresh solo hace POST a la URL del propio conjunto. Cualquier escritura del registro que elimine una entrada o cambie su url o su authMode tira el conjunto en ambos lados.

Tres: una página de otro sitio podía usar tu relay. La cookie de sesión de la Webapp es SameSite=Lax, así que una navegación de nivel superior desde otro sitio a /api/relay/<id>/<path> la llevaba consigo, y el relay hacía ese GET contra el gateway guardado con la credencial guardada. La respuesta iba con sandbox y era ilegible, pero un GET remoto con efectos secundarios se ejecutaba igual. Ahora una petición retransmitida cuyo Sec-Fetch-Site está presente y no es same-origin recibe 403 antes de enviar nada; los fetch de la propia página, y los clientes que no mandan Fetch Metadata, se retransmiten como antes.

Cuatro: un callback pegado podía canjearse contra la conexión equivocada. La finalización canjeaba el código y guardaba los tokens primero, y solo después comparaba la conexión del vuelo con el id de la ruta. Ahora el vuelo se empareja bajo el lock de vuelos antes del canje: una redirección pegada para otra conexión recibe 400 sin una sola petición de token, y el vuelo propio de esa conexión sigue siendo utilizable.

Cinco: clonar y exportar sacaban tokens en claro. hermes profile create --clone-all copiaba los dos almacenes de toda la máquina al clon, y hermes profile export enviaba después tokens de sesión en texto plano, porque el scrubber de la exportación no reconocía el sobre {"encoding":"plain","value":…}. Ambos almacenes entraron en PROFILE_CREDENTIAL_PATHS; clone-all los salta junto con su directorio .lock; el scrub de la exportación enmascara todos los sobres del JSON preparado.

Ya que estamos: ¿por qué estos secretos están en texto plano en disco y no en el llavero del sistema? Porque el servidor de la Webapp tiene que leerlos, y el llavero no existe para un proceso servidor. La protección son los permisos de archivo, más una frontera: el renderer y los plugins nunca ven bytes de token (el host.connections() del SDK de plugins devuelve solo etiquetas, tipos y el id primario). Un secreto que una build antigua cifró con safeStorage se descifra una vez durante la importación; el que no se descifra no se tira: se conserva tal cual y se anota en el importNotices del archivo hasta que el llavero de Desktop responda y lo convierta.

Cómo usarlo

Desktop y la Webapp comparten la ruta porque comparten la página: Settings → Gateways. Baja hasta Registered gateways y pulsa Add connection:

  • Local — el runtime que gestiona esta app (gestionado por la app, no se puede eliminar)
  • Remote gateway — un hermes serve en marcha; dale la URL y elige token de sesión u OAuth
  • SSH — un único campo compuesto user@host:22, más una ruta completa opcional al ejecutable hermes remoto
  • Hermes Cloud — viene del inicio de sesión en el Portal y del flujo de descubrimiento, sin URL escrita a mano

Luego pulsa Test. Sondea las dos patas de la conexión, HTTP y WebSocket, así que «Reachable» significa que el chat va a funcionar de verdad, no solo que el puerto responde. En la Webapp, Test sobre una fila SSH abre el mismo túnel gestionado que usa el gateway, arrancando (o reutilizando) hermes serve en el remoto; ese túnel no se te queda colgado para siempre: se cierra cuando quitas la conexión o paras el gateway, o por su cuenta tras el timeout de inactividad remoto dashboard.ssh_isolated_idle_grace_s (15 minutos por defecto) sin cliente y sin trabajo.

Los duplicados se rechazan al guardar: una sola entrada local, siempre; las entradas remotas y cloud se deduplican por URL normalizada (entre ambos tipos, así que una entrada cloud y una remota no pueden apuntar a la misma URL); las SSH se deduplican por user@host:port más el perfil remoto.

Cuándo podrás tenerlo de verdad

Con franqueza: todavía no, si usas releases oficiales. Estos commits entraron el 7 de noviembre y la v0.23.0 salió el 5 de noviembre, así que están en main y en ninguna etiqueta. hermes update te da releases, de modo que esperas a la siguiente o sigues main.

Actualización (10/11/2026): estos cambios ya salieron en la v0.23.1 (9 de noviembre): basta con hermes update. Lo de «no está en v0.23.0» sigue siendo cierto; la v0.23.1 cierra la brecha.

Hasta entonces, las conexiones guardadas de Desktop llevan tiempo funcionando (mira la guía de escritorio multi-gateway). Lo que cambia es que la mitad del navegador deja de ser ciudadano de segunda.

Y si tu inicio de sesión contra un gateway remoto lleva tiempo peleándose contigo por redirecciones de loopback y jump hosts, las tres rutas de completar OAuth en un servidor remoto siguen valiendo. Lo nuevo es que ahora el servidor ejecuta todo el flujo nativo por ti, y te deja pegar la dirección de vuelta cuando el callback cae en la máquina equivocada.

La versión corta

Las conexiones de gateway guardadas pasaron de ser asunto privado de una app de escritorio a infraestructura compartida de la máquina: un JSON 0600, dos hosts escribiéndolo, el navegador hablando solo con el gateway que le sirve la página y las credenciales atadas a una dirección antes de reenviarse. La capacidad en sí es simple. Las cinco correcciones son la parte valiosa: muestran que «¿de quién es esta credencial?» es una trampa en todas partes en cuanto se permiten ediciones y escrituras concurrentes desde varios hosts.

Para la superficie de comandos, mira la referencia de hermes gateway del sitio; para el lado de escritorio, la guía del modo interfaz explica cómo presenta la app los backends locales y remotos.