Agente Hermes: Servidor sin cabeza + Configuración de escritorio remoto

Servidor Hermes headless con acceso a escritorio remoto

Índice

Ejecutar Hermes Agent en un servidor sin interfaz gráfica (headless) mientras se conecta desde un cliente de escritorio en otra máquina requiere dos procesos de servidor y una conexión de cliente.

La arquitectura separa el backend de Hermes en dos procesos del lado del servidor y una interfaz del lado del cliente. El backend hermes serve maneja las conexiones de la API y el panel de control, mientras que el proceso hermes gateway run gestiona los canales de mensajería de forma independiente. El cliente de escritorio se conecta al backend de serve, no al gateway.

flowchart LR subgraph Server["SERVIDOR HEADLESS"] serve["hermes serve
--host 0.0.0.0
:9119"] gateway["hermes gateway run
Telegram, Discord, Slack"] end subgraph Client["PC DE ESCRITORIO"] desktop["hermes desktop
(conexión WebSocket)"] end desktop <--->|WebSocket| serve gateway -.->|Comparte ~/.hermes/| serve

Dos procesos en el servidor, una aplicación en el cliente. Ambos procesos del servidor comparten la misma configuración ~/.hermes/, habilidades, memoria y sesiones. Las tareas programadas (Cron jobs) se ejecutan en el servidor donde se ejecuta el gateway.

Arquitectura de servidor headless de Hermes Agent

Para la instalación, configuración del proveedor y configuración inicial, comience con Hermes AI Assistant — Instalación, Configuración, Flujo de trabajo y Solución de problemas.

Configurar el servidor headless

1. Configurar la autenticación

La autenticación básica proporciona suficiente protección para una LAN de confianza. Agregue las credenciales al archivo de entorno:

cat >> ~/.hermes/.env << 'EOF'
HERMES_DASHBOARD_BASIC_AUTH_USERNAME=admin
HERMES_DASHBOARD_BASIC_AUTH_PASSWORD=choose-a-strong-password
HERMES_DASHBOARD_BASIC_AUTH_SECRET=$(openssl rand -base64 32)
EOF
chmod 600 ~/.hermes/.env

El archivo .env reside junto a config.yaml dentro de ~/.hermes/. Hermes resuelve la configuración con anulaciones de CLI primero, luego config.yaml, luego .env y finalmente los valores predeterminados integrados. Los secretos deben estar en .env.

2. Iniciar el backend

Ejecute el backend de serve en todas las interfaces:

hermes serve --host 0.0.0.0 --port 9119

El backend escucha en el puerto 9119 y acepta conexiones WebSocket desde el cliente de escritorio. Verifique que se esté ejecutando con una rápida comprobación de estado:

curl -s http://localhost:9119/api/status | jq '.auth_required, .auth_providers'
# Esperado: true "basic"

3. Ejecutar como un servicio systemd

Para un servidor persistente que sobreviva a los reinicios, instale un servicio systemd a nivel de usuario. Cree el archivo de unidad en /etc/systemd/user/hermes-serve.service:

[Unit]
Description=Hermes Agent Serve Backend

[Service]
EnvironmentFile=%h/.hermes/.env
ExecStart=/home/rg/.hermes/hermes-agent/venv/bin/python -m hermes_cli.main serve --host 0.0.0.0 --port 9119
Restart=on-failure

[Install]
WantedBy=default.target

Recargue el demonio, habilite el servicio e inícielo:

systemctl --user daemon-reload
systemctl --user enable hermes-serve
systemctl --user start hermes-serve

Verifique el estado del servicio:

systemctl --user status hermes-serve

4. Iniciar el gateway

El gateway es un proceso separado que maneja los canales de mensajería: Telegram, Discord, Slack y otros. Inícielo de forma independiente:

hermes gateway run

El gateway y el backend de serve son dos procesos separados. El gateway gestiona sesiones, ejecuta tareas programadas y enruta mensajes. El backend de serve proporciona la superficie de API para conexiones de escritorio y panel web. Comparten el mismo directorio principal pero se ejecutan de forma independiente.

Para la lista completa de comandos y subcomandos del gateway, consulte la Hoja de trucos de Hermes Agent CLI. Si su interfaz principal es la mensajería móvil, combine esta configuración con Control de voz de Hermes desde su teléfono para flujos de trabajo centrados en la voz sobre el mismo proceso de gateway.

5. Verificar el backend

Confirmar que el backend está respondiendo y que la autenticación está activa:

curl -s http://localhost:9119/api/status | jq '.auth_required, .auth_providers'

Salida esperada:

true
"basic"

Si la autenticación no está habilitada, la respuesta mostrará false para auth_required. Verifique que el archivo .env contenga las variables correctas y que el servicio se haya reiniciado después de los cambios de configuración.

Conectar desde el cliente de escritorio

Opción A: Aplicación de escritorio Hermes

Instale Hermes Desktop desde el sitio oficial. Inicie la aplicación, navegue a Configuración → Gateway → Gateway remoto e ingrese la dirección del servidor:

http://<ip-del-servidor>:9119

Inicie sesión con el nombre de usuario y la contraseña que configuró en el servidor.

Alternativamente, configure la URL remota mediante una variable de entorno:

HERMES_DESKTOP_REMOTE_URL=http://<ip-del-servidor>:9119 hermes desktop

Opción B: Panel web

Abra http://<ip-del-servidor>:9119 en un navegador e inicie sesión con las credenciales de autenticación básica. El panel web proporciona una interfaz basada en el navegador para el backend de Hermes sin requerir una instalación de escritorio.

Opción C: CLI

Desde la terminal de la PC de escritorio, configure la URL remota a través de la configuración de la aplicación de escritorio o la variable de entorno HERMES_DESKTOP_REMOTE_URL. La interfaz de CLI se conecta a través del mismo canal WebSocket que la aplicación de escritorio.

Consideraciones de red y seguridad

Escenario	Recomendación
LAN de confianza	`--host 0.0.0.0` + autenticación básica
Expuesto a internet	Usar Tailscale (`--host <ip-de-tailscale>`) o proveedor OAuth
Firewall	Abrir puerto 9119 TCP en el servidor

Para una red local de confianza, la autenticación básica en 0.0.0.0 es adecuada. Si el servidor está expuesto a internet, use Tailscale para vincularse a la IP de Tailscale en lugar de 0.0.0.0, o configure un proveedor OAuth para una autenticación más robusta. Siempre abra el puerto 9119 TCP en el firewall del servidor cuando el backend necesite aceptar conexiones externas.

Distinciones importantes de procesos

Comprender la separación entre los dos procesos del servidor evita errores de configuración comunes:

hermes serve — El backend al que se conectan la aplicación de escritorio y el panel web. Maneja la superficie de API y las conexiones WebSocket.
hermes gateway run — El proceso que maneja Telegram, Discord, Slack y otros canales de mensajería. Gestiona sesiones, ejecuta tareas programadas y enruta mensajes.
Estos son dos procesos separados en el servidor. Comparten la configuración ~/.hermes/, habilidades, memoria y sesiones, pero se ejecutan de forma independiente.
Las tareas programadas se ejecutan en el servidor donde se ejecuta el gateway.
Los perfiles, habilidades y memoria se configuran en el lado del servidor. El cliente se conecta al backend ya configurado.

Para una configuración centrada en perfiles y habilidades ajustadas para diferentes roles de producción, consulte Habilidades de Hermes AI Assistant para configuraciones de producción reales.

Solución de problemas

El escritorio no puede conectarse al servidor

Verifique que el backend se esté ejecutando: systemctl --user status hermes-serve
Compruebe que el puerto esté abierto: ss -tlnp | grep 9119
Pruebe desde el servidor: curl -s http://localhost:9119/api/status
Pruebe desde la máquina cliente: curl -s http://<ip-del-servidor>:9119/api/status
Si la prueba del cliente falla, verifique las reglas del firewall: sudo ufw status o sudo iptables -L

La autenticación falla

Confirme que el archivo .env tiene los permisos correctos: ls -la ~/.hermes/.env (debería ser 600)
Verifique que se generó el secreto: grep HERMES_DASHBOARD_BASIC_AUTH_SECRET ~/.hermes/.env
Reinicie el servicio después de los cambios de configuración: systemctl --user restart hermes-serve

El gateway no responde a los mensajes

El gateway es un proceso separado del backend. Si el escritorio se conecta pero las plataformas de mensajería no funcionan:

Verifique el estado del gateway: hermes gateway status
Inicie el gateway si está detenido: hermes gateway start
Revise los registros: hermes logs gateway -f

Referencias

Este artículo es parte del clúster de Sistemas de IA, que cubre asistentes autoalojados, arquitectura de recuperación, infraestructura local de LLM y observabilidad.