Docker + Hermes Agent: Dos Formas de Usarlo

Si alguna vez te has preguntado cómo encaja Docker en el ecosistema de Hermes Agent, estás en el lugar correcto. En realidad, hay dos formas distintas en las que ambos pueden trabajar juntos, y vale la pena conocer la diferencia antes de empezar a teclear docker run.

Los Dos Modos de Docker

Ejecutar Hermes DENTRO de Docker — el propio agente vive dentro de un contenedor. Este es el enfoque principal de esta guía.
Docker como backend de terminal — Hermes se ejecuta en tu máquina host, pero cada comando que ejecuta ocurre dentro de un único sandbox persistente de Docker. Ese sandbox sobrevive a las llamadas de herramientas, a /new, e incluso a los subagentes mientras el proceso de Hermes esté vivo.

Este artículo cubre la opción 1. Lo clave que debes saber: todos tus datos (configuración, claves API, sesiones, habilidades, memorias) viven en un único directorio en tu host, montado en /opt/data dentro del contenedor. La imagen en sí es sin estado, así que puedes descargar una nueva versión en cualquier momento sin perder tu configuración.

Inicio Rápido: Primera Configuración

Si es tu primera vez, crea un directorio de datos y arranca el contenedor de forma interactiva para ejecutar el asistente de configuración:

mkdir -p ~/.hermes
docker run -it --rm \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent setup

Esto te lleva al asistente, que te pide tus claves API y las escribe en ~/.hermes/.env. Solo necesitas hacer esto una vez. Ya que estás en ello, es un buen momento para configurar un sistema de chat (Telegram, Discord, etc.) para que tu gateway tenga dónde conversar.

⚠️ Una advertencia: Evita las consolas VPS basadas en navegador para estos comandos de instalación. Algunos proveedores (como Hetzner) alteran los caracteres especiales — : puede llegar como ;, @ se renderiza mal, y las claves API pegadas pueden corromperse silenciosamente. Conéctate siempre por SSH para una entrada de comandos segura con copiar y pegar. Si debes usar la consola del navegador, escribe los comandos manualmente y verifica cada :, @, = y /.

Consejo profesional: Dentro del contenedor, ejecuta hermes setup --portal una vez — el token de refresco persiste en tu volumen montado ~/.hermes.

Ejecución en Modo Gateway

Una vez configurado, ejecuta el contenedor en segundo plano como un gateway persistente:

docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  -p 8642:8642 \
  nousresearch/hermes-agent gateway run

El puerto 8642 expone el servidor API compatible con OpenAI del gateway y su endpoint de salud. Es opcional si solo usas plataformas de chat, pero es necesario si quieres que el dashboard o herramientas externas accedan al gateway.

Qué Hay de Nuevo: Gateway Supervisado

Aquí hay un gran cambio: dentro de la imagen oficial de Docker, gateway run ahora está supervisado automáticamente por s6-overlay. Si el gateway se bloquea, se reinicia en segundos sin perder el contenedor. El dashboard (cuando está habilitado) se supervisa junto con él.

Verás una línea de rastro en docker logs que confirma la actualización. Para optar por no participar y obtener el comportamiento anterior (salida del contenedor = salida del gateway), pasa --no-supervise o establece HERMES_GATEWAY_NO_SUPERVISE=1. Esto es útil para pruebas de humo en CI; para producción, el valor predeterminado supervisado es estrictamente mejor.

Paradas Forzadas del Bucle de Herramientas

Una configuración importante para gateways desatendidos: tool_loop_guardrails.hard_stop_enabled tiene como valor predeterminado false. Eso está bien para sesiones interactivas donde un humano puede ver las advertencias. Pero en despliegues desatendidos, las advertencias por sí solas podrían no detener a un agente atascado en un bucle. Si quieres el comportamiento de cortacircuitos, actívalo en el config.yaml de tu perfil:

tool_loop_guardrails:
  hard_stop_enabled: true
  hard_stop_after:
    exact_failure: 5
    idempotent_no_progress: 5

Exponiendo el Servidor API

El servidor API está condicionado a API_SERVER_ENABLED=true. Para exponerlo más allá de 127.0.0.1 dentro del contenedor, también establece API_SERVER_HOST=0.0.0.0 y una API_SERVER_KEY (mínimo 8 caracteres — genera una con openssl rand -hex 32):

docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  -p 8642:8642 \
  -e API_SERVER_ENABLED=true \
  -e API_SERVER_HOST=0.0.0.0 \
  -e API_SERVER_KEY="$(openssl rand -hex 32)" \
  -e API_SERVER_CORS_ORIGINS='*' \
  nousresearch/hermes-agent gateway run

Nota de seguridad: Abrir cualquier puerto en una máquina expuesta a internet es un riesgo. No lo hagas a menos que entiendas completamente las consecuencias.

Ejecutando el Dashboard

El dashboard web integrado se ejecuta como un servicio supervisado por s6-rc junto al gateway en el mismo contenedor. Solo establece HERMES_DASHBOARD=1:

docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  -p 8642:8642 \
  -p 9119:9119 \
  -e HERMES_DASHBOARD=1 \
  nousresearch/hermes-agent gateway run

Si el dashboard se bloquea, s6-supervise lo reinicia automáticamente tras un breve período de espera. Su salida va a docker logs <contenedor>.

Dónde Van los Registros

Para el mapa de enrutamiento completo (gateways por perfil, dashboard, reconciliador de arranque y docker logs a nivel de contenedor), consulta la sección dedicada en la documentación. La versión corta: todo termina eventualmente en docker logs, pero con prefijos claros para que puedas distinguir qué es qué.

Conclusión

Docker te ofrece una forma limpia y actualizable de ejecutar Hermes Agent. El contenedor es sin estado, tus datos viven de forma segura en el host, y la nueva supervisión de s6 significa que tu gateway se mantiene activo incluso si se bloquea. Ya sea que estés ejecutando una configuración simple o una combinación completa de dashboard + servidor API, los comandos anteriores te llevan allí en minutos.