Hermes Agent Web Dashboard: acceso local, perfiles y diagnóstico

La interfaz gráfica Hermes Agent Web Dashboard permite administrar la instalación del agente desde el navegador, eliminando la necesidad de editar archivos de configuración directamente. El panel facilita la gestión de claves de API, el cambio de perfiles activos, la inspección de sesiones anteriores y el inicio de una terminal integrada sin tener que modificar manualmente el entorno del sistema.

Inicio básico y dependencias del sistema

Por defecto, el panel de control se vincula a la interfaz de bucle invertido (loopback):

hermes dashboard

Este comando inicia un servidor HTTP local y abre http://127.0.0.1:9119 en el navegador predeterminado. Si ese puerto ya está ocupado por otro servicio local, se puede anular mediante la opción --port:

hermes dashboard --port 9120 --no-open

La opción --no-open impide que se abra automáticamente una nueva pestaña en el navegador, lo cual resulta idóneo para procesos en segundo plano o scripts de automatización.

El paquete base hermes-agent no incluye la pila web de manera predeterminada. En entornos Linux, macOS y WSL2, los componentes opcionales necesarios se instalan dentro del entorno virtual del agente:

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

El extra web instala FastAPI y Uvicorn, mientras que pty añade ptyprocess para sistemas POSIX. La compilación de la interfaz estática del panel requiere una instalación activa de Node.js (si npm está disponible, la interfaz se compila automáticamente en el primer inicio).

Límites de plataforma: Windows nativo frente a WSL2

Según la guía de Windows (Native), una instalación nativa en Windows admite las vistas de configuración, métricas, tareas y la base de datos de sesiones. Sin embargo, la pestaña de la terminal integrada /chat depende de pseudoterminales POSIX PTY. Dado que el entorno nativo de Windows no admite esta interfaz, es necesario ejecutar el agente dentro de WSL2 para disponer de sesiones de terminal interactivas completas en el navegador.

Asimismo, es fundamental separar los procesos: el panel web y las pasarelas de mensajería (messaging gateways para Telegram, Discord u otras plataformas) funcionan como demonios independientes. Iniciar la interfaz web no activa automáticamente la pasarela de la plataforma.

Gestión de perfiles y configuración de modelos

El panel de control opera a nivel de toda la máquina y proporciona una administración centralizada para todos los perfiles configurados. El selector de perfiles en la barra lateral modifica el contexto de trabajo a través del parámetro de consulta URL ?profile=<nombre>.

1. Secciones Config y API Keys: La página Config edita los parámetros en config.yaml, donde las modificaciones se guardan haciendo clic en el botón Save. Por el contrario, la página API Keys gestiona las variables de entorno en ~/.hermes/.env: las claves se establecen y eliminan de forma individual para cada variable, sin un botón de guardado global ni validación por lotes de todos los campos.
2. Coherencia de proveedor y modelo: El modelo seleccionado y las credenciales deben corresponder estrictamente al mismo proveedor. Al integrar un servicio compatible con OpenAI de terceros, verifique los parámetros oficiales del proveedor: por ejemplo, los ajustes de conexión, los identificadores de modelos y los campos obligatorios se describen en la guía de BetterToken. Un proveedor externo únicamente suministra acceso independiente a la API de los modelos y no aloja el panel de Hermes ni gestiona túneles de red.
3. Comprobación de funcionamiento mediante Sessions: Para realizar una verificación manual, envíe una instrucción breve de solo lectura. Tenga en cuenta que las consultas de prueba pueden ser tarificadas por el proveedor. La inferencia se considera exitosa cuando se recibe una respuesta sustancial en la interfaz y el consumo de tokens queda registrado en los metadatos de la sesión o en los registros del proveedor. La mera aparición de una nueva entrada en la lista de la pestaña Sessions solo indica que se ha creado un registro de sesión, no que el modelo haya respondido correctamente.

Acceso remoto seguro

De forma predeterminada, el servidor web escucha exclusivamente en 127.0.0.1. Al vincularlo a interfaces externas (--host 0.0.0.0), se activa automáticamente una barrera de autenticación (auth gate). Si no se ha configurado ningún proveedor de autenticación, el agente finaliza con un error (fail-closed). La opción obsoleta --insecure ya no desactiva la comprobación de autenticación. Cualquier vinculación a redes públicas o externas exige autenticación obligatoria según la documentación de Hermes Agent.

El método recomendado para conectarse a un servidor remoto sin exponer puertos externos es el reenvío de puertos locales a través de un túnel SSH (sustituya user@your-server por la dirección y el usuario de su servidor remoto):

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

Si el puerto local 9119 ya está ocupado en su estación de trabajo, utilice un puerto local alternativo:

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

Con esta configuración, el servidor Hermes en la máquina remota continúa escuchando estrictamente en la interfaz de bucle invertido local 127.0.0.1, todo el tráfico viaja cifrado por el túnel SSH y se puede acceder al panel desde su estación de trabajo en http://127.0.0.1:9119 (o http://127.0.0.1:9120 si se utiliza el puerto local alternativo).

Diagnóstico de problemas paso a paso

Cuando se presenten errores, resulta fundamental aislar la capa del fallo en lugar de evaluar toda la pila a la vez.

+----------------------------------------------------------------+
| 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, лимиты и сетевой эндпоинт  |
+----------------------------------------------------------------+

Las capas de diagnóstico descritas en el árbol de decisión anterior representan:

• Capa 1 (Transporte HTTP): 127.0.0.1:9119 /api/status
• Capa 2 (Entorno y PTY): Node.js / POSIX ptyprocess (WSL2)
• Capa 3 (Sockets y canales): /api/pty (Chat) / /api/ws (Desktop)
• Capa 4 (Proveedor de inferencia): claves de API, cuotas y extremo de red

1. Capa de red (HTTP): Una respuesta satisfactoria de GET /api/status demuestra únicamente que el proceso de Uvicorn se está ejecutando y responde a solicitudes HTTP. Este extremo no requiere autenticación y no garantiza que se haya superado la autorización ni que la interfaz de chat interactivo esté lista.
2. Capa de PTY e interfaz: El error Connection closed puede obedecer a varias causas distintas. En Windows nativo, una causa diagnóstica principal es la falta de compatibilidad con POSIX PTY (en cuyo caso la ejecución debe trasladarse a WSL2). En otras plataformas, este síntoma no se limita a PTY y exige examinar los registros del sistema y la conexión del socket. Los problemas de pantalla en blanco o los errores de compilación de estilos requieren verificar la versión de Node.js y recompilar las dependencias del frontend.
3. Canales de sockets y autorización: La terminal integrada en el navegador se comunica a través de /api/pty, mientras que el cliente Desktop remoto se conecta mediante /api/ws. Si el cliente indica que el backend es accesible pero las sesiones no responden, compruebe la conexión del canal correspondiente: los fallos suelen deberse a la ausencia o caducidad de tickets de sesión, o a la protección contra DNS rebinding que bloquea las peticiones cuando el encabezado Host no coincide con la dirección de enlace.
4. Capa del proveedor del modelo: La latencia o los mensajes de error devueltos tras enviar un mensaje en una terminal activa suelen originarse en la capa de la API (como una clave no válida en .env, un extremo del proveedor inaccesible o cuotas y saldos agotados). Sin embargo, los errores del proveedor no prueban que el servidor del panel esté completamente sano: diagnosticar las incidencias también puede requerir inspeccionar el estado del entorno de ejecución y el ciclo de vida de la sesión.