Tutorial 16: Despliegue con Docker

Tutorial 16: Despliegue con Docker

¡Bienvenidos de nuevo, exploradores de Hermes! En nuestro último tutorial, nos sentimos cómodos ejecutando Hermes Agent directamente en nuestras máquinas. Hoy, llevamos las cosas al siguiente nivel: vamos a poner a Hermes dentro de un contenedor Docker. Esto cambia las reglas del juego para mantener tu configuración limpia, portátil y fácil de actualizar.

Dos formas en que Docker se encuentra con Hermes

Antes de sumergirnos, es importante entender que Docker y Hermes Agent pueden trabajar juntos de dos maneras distintas:

1. Ejecutar Hermes en Docker – El propio agente vive dentro de un contenedor. Esto es en lo que nos centraremos hoy.
2. Docker como backend de terminal – Hermes se ejecuta en tu host, pero cada comando que ejecuta ocurre dentro de un sandbox Docker persistente. Esto es genial para la seguridad y el aislamiento, pero es un tema para otro día.

Hoy, nos centramos en la opción 1. La belleza de este enfoque es que todos tus datos (configuración, claves API, sesiones, habilidades y memorias) viven en un único directorio en tu host, montado en el contenedor en /opt/data. El contenedor en sí no tiene estado, por lo que puedes descargar una nueva versión y actualizar sin perder nada.

Inicio rápido: Tu primer contenedor

Si eres completamente nuevo en Hermes, el camino más fácil es crear un directorio de datos y ejecutar el asistente de configuración de forma interactiva. Esto te guiará para ingresar tus claves API y guardarlas en ~/.hermes/.env.

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

Una palabra de precaución: evita las consolas VPS basadas en navegador (como las de Hetzner Cloud) para estos comandos. A menudo alteran caracteres especiales como :, @ y =, lo que puede corromper silenciosamente tus argumentos de docker run. Conéctate siempre por SSH (ssh root@<host>) para una entrada segura con copiar y pegar. Si debes usar la consola del navegador, escribe los comandos manualmente y verifica cada carácter.

Una vez que estés en el asistente, es muy recomendable configurar un sistema de chat (Telegram, Discord, etc.) para que tu gateway tenga un lugar donde enviar mensajes.

Ejecución en modo Gateway

Una vez configurado, querrás ejecutar Hermes como un gateway de fondo persistente. Así es como se conecta a tus plataformas de chat y permanece activo 24/7.

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

El flag -p 8642: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 lleguen a tu gateway.

Aquí hay una nueva característica interesante: dentro de la imagen oficial de Docker, gateway run ahora está supervisado automáticamente por s6-overlay. Esto significa que si el proceso del gateway falla, se reinicia en segundos sin perder el contenedor. Verás una miga de pan en docker logs confirmando la actualización. Si quieres el comportamiento anterior (donde el contenedor se detiene cuando el gateway se detiene), pasa --no-supervise o establece HERMES_GATEWAY_NO_SUPERVISE=1. Para producción, el valor predeterminado supervisado es estrictamente mejor.

Exponiendo el servidor API

Por defecto, el servidor API está restringido por API_SERVER_ENABLED=true. Para exponerlo más allá de 127.0.0.1 dentro del contenedor, necesitarás establecer algunas variables de entorno:

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

La API_SERVER_KEY debe tener al menos 8 caracteres; genera una con openssl rand -hex 32. Importante: abrir cualquier puerto en una máquina expuesta a internet es un riesgo de seguridad. No lo hagas a menos que entiendas completamente las implicaciones.

Ejecutando el Dashboard

¿Quieres un dashboard web para monitorear tu gateway? Establece HERMES_DASHBOARD=1 y expón el puerto 9119:

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

El dashboard también está supervisado por s6, por lo que se reinicia automáticamente si falla. Su salida va a docker logs <contenedor>.

Una nota sobre las salvaguardas del bucle de herramientas

Para gateways desatendidos, considera habilitar detenciones forzadas para las salvaguardas del bucle de herramientas. El valor predeterminado es false, lo cual está bien para sesiones interactivas donde un humano puede ver las advertencias. Pero en un gateway desatendido, un agente atrapado en un bucle podría nunca detenerse. Añade esto a config.yaml de tu perfil:

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

Conclusión

¡Esa es la historia del despliegue con Docker! Ahora tienes un contenedor sin estado y actualizable con todos tus datos montados de forma segura en el host. En el próximo tutorial, exploraremos el dashboard con más detalle. Hasta entonces, ¡feliz contenerización!