Dirigir tu agente desde un tren: guía de campo del WebUI de la comunidad


Vas de vuelta a casa en el tren cuando te asalta la duda: ¿se ejecutó de verdad ese cron job esta mañana? Sacas el móvil. Nada en la bandeja de entrada. Tampoco tienes ningún bot de Telegram configurado. Así que esperas a llegar al escritorio, y para entonces la cena ya ha borrado la pregunta por completo.

El problema no es que Hermes no se pueda usar en remoto. Es que «remoto» suele significar montar un túnel y encima un frontend, y la mayoría de la gente nunca se molesta. Un proyecto de la comunidad lo comprime en tres comandos: Hermes WebUI, unas 18K estrellas, un backend en Python con JavaScript puro en el frontend, sin paso de build, sin bundler, funcionando sobre la config y los modelos de Hermes que ya tienes.

Qué es y por qué merece la instalación

Tienes el ya familiar diseño de tres paneles: sesiones y navegación a la izquierda, chat en el centro y un explorador de archivos del workspace a la derecha. Los controles de modelo, perfil y workspace están en el pie del compositor, así siguen visibles mientras escribes, y un anillo circular muestra el uso de contexto de un vistazo. Todo lo demás vive en el Hermes Control Center, que se abre desde un botón al final de la barra lateral.

La característica estrella es la paridad casi 1:1 con el CLI: lo que puedes hacer en una terminal, en su mayoría puedes hacerlo aquí. Fijar, archivar y agrupar sesiones en proyectos; buscar y previsualizar skills, editándolas in situ; editar MEMORY.md y USER.md; crear, pausar e inspeccionar cron jobs con historial de ejecuciones y alertas de finalización; cambiar y clonar perfiles; autocompletado para slash commands como /compress, /model, /new y /theme.

En el móvil es realmente responsive: la barra lateral se colapsa en un panel deslizante por debajo de 640px, los objetivos táctiles se mantienen en al menos 44px y el explorador de archivos se convierte en un panel que entra desde la derecha. Además se distribuye como PWA instalable, lo que hace que se sienta como una app y no como una página web una vez que está en tu pantalla de inicio.

Tres comandos para instalar — y probarlo primero en local

git clone https://github.com/nesquena/hermes-webui.git hermes-webui
cd hermes-webui
python3 bootstrap.py

bootstrap.py se encarga de las partes pesadas: detecta Hermes y ejecuta el instalador oficial si falta, encuentra o crea un entorno de Python con las dependencias del WebUI, arranca el servidor y espera a /health, y luego abre tu navegador en un asistente de primera ejecución. Pasa --no-browser si prefieres que no lo haga.

Si prefieres gestionar un daemon, el repo también incluye ctl.sh, que resulta más cómodo en una VM autoalojada porque no necesita fuser ni pkill:

./ctl.sh start              # daemon en segundo plano, PID en ~/.hermes/webui.pid
./ctl.sh status             # PID, uptime, host/puerto ligado, ruta del log, /health
./ctl.sh logs --lines 100   # sigue ~/.hermes/webui.log
./ctl.sh restart
./ctl.sh stop

El servidor se liga a 127.0.0.1:8787 por defecto; en otras palabras, consigue que una sesión funcione en local antes de pensar en el acceso remoto. El health check siempre está disponible para verificar a mano:

curl http://127.0.0.1:8787/health

Remoto y móvil: dos caminos, ninguno necesita un puerto abierto

La opción segura por defecto es un SSH tunnel. El servidor se queda en loopback y tú llegas a él desde fuera:

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

Luego abre http://127.0.0.1:8787 en tu navegador local. Ni siquiera necesitas un cliente SSH de escritorio en el móvil: bastantes apps de terminal móviles pueden mantener un túnel abierto.

La opción cómoda es Tailscale. Pon el servidor y el móvil en la misma tailnet y liga el servicio a todas las interfaces:

HERMES_WEBUI_HOST=0.0.0.0 HERMES_WEBUI_PASSWORD='pick-your-own' ./ctl.sh start

Luego navega a http://<server-tailscale-ip>:8787 desde el móvil. Fíjate en las dos condiciones de esa segunda mitad: la contraseña no es opcional, y el puerto 8787 solo debería existir dentro de la tailnet; resístete a la tentación de abrirlo en un security group de tu nube.

Seguridad: sin fricción en localhost, blindado cuando sales a remoto

El modelo de seguridad es honesto hasta refrescar en cuanto a intención: la autenticación por contraseña está desactivada por defecto, porque el acceso por localhost nunca la necesitó. Salir a remoto significa activar cosas tú mismo.

  • HERMES_WEBUI_PASSWORD como variable de entorno, o una contraseña definida en el panel de Settings;
  • passkeys / WebAuthn: inicia sesión con la contraseña, registra una passkey en Settings y, en cuanto exista al menos una, puedes descartar la contraseña y usar solo passkey (manteniendo la contraseña como vía de recuperación);
  • OIDC nativo, configurado con webui_oidc.issuer, client_id, allow_claim y allow_values: los cuatro son obligatorios antes de que OIDC se active, y el arranque te avisa si la config está incompleta;
  • tras el login obtienes una cookie HTTP-only firmada con HMAC y TTL de 24 horas, cabeceras de seguridad en las respuestas, un límite de 20MB en el cuerpo de los POST y assets de CDN fijados con hashes SRI.

Hay un aviso que destaca: si lo pones detrás de un reverse proxy, no uses el basic auth del proxy. Las actualizaciones de la PWA descargan el service worker, y el auth del proxy bloquea esas peticiones, dejando una app instalada en pantalla en blanco tras una actualización. La documentación incluye los pasos de recuperación, y es la razón por la que Tailscale o un túnel son el camino recomendado.

Si ya estás metido de lleno en la fontanería del acceso remoto, el artículo sobre OAuth sobre SSH puede ahorrarte unas cuantas horas.

Dónde están los límites

El bootstrap no soporta Windows nativo. Usa Linux, macOS o WSL2. Existe una guía para Windows nativo mantenida por la comunidad, pero ahí estás por tu cuenta.

El chat no pasa por un servidor de API externo por defecto. El WebUI ejecuta el agente Hermes en proceso, leyendo directamente tu config de HERMES_HOME. Si ya tienes un endpoint compatible con OpenAI, hay dos usos soportados: añadirlo en Settings como provider personalizado con su base URL y su bearer token, o enrutar el chat a través de un servidor de la Hermes Gateway API en ejecución con HERMES_WEBUI_CHAT_BACKEND=gateway. El segundo camino todavía no incluye la delegación completa del bucle del agente (hay un issue abierto al respecto), así que trátalo como un modo viable, pero no idéntico a ejecutar en local.

Las alternativas nativas para móvil siguen siendo muy recientes. El 19 de septiembre apareció un repositorio de app para móvil con un PRD y ninguna implementación, y hay experimentos previos en Android. Por ahora, el WebUI es la vía más madura y con mantenimiento más activo, y tiene entrada en nuestro directorio de ecosistema.

Noventa minutos después

Volvamos al tren: instala el WebUI, únete a Tailscale, añádelo a tu pantalla de inicio. La próxima vez que te preguntes si ese cron job se ejecutó, lo compruebas desde el bolsillo y, ya que estás, le pides que convierta los logs de build fallidos en tres conclusiones y te las envíe.

Si Hermes en sí aún no está configurado, empieza por la guía de instalación; si quieres apuntar tu escritorio y tus clientes remotos a un único backend, la referencia del comando gateway lo cubre. Ejecutar un agente en remoto debería ser la parte fácil.