Hermify
Volver al Blog
HermesDockerSelf-HostingTutorial

Cómo ejecutar Hermes Agent en Docker (autoalojado)

Despliega Hermes Agent en Docker con volúmenes persistentes, docker-compose y configuración de producción. Datos, secretos, puertos y actualizaciones.

Por Hermify Team||7 min de lectura
Una sala de servidores oscura con un único rack iluminado en verde, evocando un agente de IA autoalojado funcionando 24/7

Por qué Docker es la forma por defecto de ejecutar Hermes Agent

Hermes Agent se distribuye como contenedor Docker como objetivo de despliegue principal. La imagen incluye el gateway, el dashboard, las dependencias de tiempo de ejecución y una configuración por defecto razonable, así no tienes que pelearte con versiones de Python, librerías del sistema o problemas con el PATH en el host. Tú aportas un host con Docker instalado, un volumen persistente pequeño para el estado y tu API key del proveedor. El contenedor hace el resto.

Una instalación autoalojada típica se ve así:

  • Un contenedor gateway exponiendo el puerto 8642 para la API compatible con OpenAI y el endpoint de salud.
  • Un volumen persistente con nombre para sesiones, memoria, skills aprendidas y configuración.
  • Un archivo .env con las claves del proveedor y las credenciales de Telegram.
  • Opcionalmente, un contenedor dashboard sidecar que lee el mismo directorio de datos en modo solo lectura.

Todo lo demás - actualizaciones, reinicios, rotación de logs - lo gestiona el propio Docker. Este post recorre esa configuración de principio a fin, luego muestra el layout de docker-compose listo para producción y los detalles que conviene conocer antes de poner el agente en un host público.

Si todavía no has decidido entre autoalojar o usar una versión gestionada, lee primero autoalojado vs gestionado de Hermes Agent. El resto de esta guía asume que has decidido ejecutar el contenedor tú mismo.

Requisitos previos

Necesitas:

  • Un host con Docker 24+ instalado (VPS Linux, macOS con Docker Desktop, o Windows con WSL2).
  • Al menos 1 vCPU y 2 GB de RAM. La recomendación oficial es 2 vCPU y 8 GB para un uso concurrente cómodo.
  • Una API key de proveedor (OpenAI, Anthropic, OpenRouter o cualquier endpoint compatible con OpenAI).
  • Unos 2 GB de espacio libre en disco para la imagen, más margen para el crecimiento del volumen de datos.

Un VPS de 5 dólares de cualquier proveedor decente cumple el mínimo. El agente consume poca CPU y poca E/S cuando no está razonando activamente - la mayor parte del día está inactivo esperando mensajes de Telegram o tareas programadas.

Paso 1 - Crear el directorio de datos

El contenedor persiste todo en /data dentro de la imagen. En el host, decide dónde vive ese directorio. La convención es ~/.hermes/data:

mkdir -p ~/.hermes/data

Este único directorio guarda el historial de sesiones, la memoria vectorial, las skills aprendidas, los secretos cifrados y la configuración del usuario. Haz copia de él y habrás respaldado el agente entero. Piérdelo y empiezas de cero - el contenedor en sí es efímero.

Paso 2 - Asistente de configuración inicial

Ejecuta el contenedor de forma interactiva la primera vez para que pueda pedirte las claves y escribirlas en ~/.hermes/.env:

docker run -it --rm \
  -v ~/.hermes:/root/.hermes \
  -v ~/.hermes/data:/data \
  ghcr.io/nousresearch/hermes-agent:latest setup

El asistente pregunta por:

  • El proveedor LLM por defecto (OpenAI, Anthropic, OpenRouter, personalizado).
  • La API key del proveedor.
  • Token opcional del bot de Telegram y lista de usuarios permitidos.
  • Claves opcionales del proveedor de voz (solo si vas a habilitar el modo voz).

Los valores se escriben en ~/.hermes/.env en el host. Trata ese archivo como un secreto - chmod 600 ~/.hermes/.env y nunca lo subas a git.

Una terminal mostrando el asistente de configuración Docker de Hermes Agent pidiendo una API key de OpenAI, con la ruta del nuevo archivo .env visible en la parte superior

Paso 3 - Ejecutar el gateway persistente

Una vez terminado el asistente, la forma de larga duración del mismo contenedor arranca el gateway:

docker run -d \
  --name hermes \
  --restart unless-stopped \
  -p 8642:8642 \
  --env-file ~/.hermes/.env \
  -v ~/.hermes/data:/data \
  ghcr.io/nousresearch/hermes-agent:latest gateway

Desglose de cada flag:

  • -d ejecuta el contenedor en segundo plano, en modo detached.
  • --restart unless-stopped lo vuelve a levantar automáticamente tras reinicios y caídas del host.
  • -p 8642:8642 expone la API compatible con OpenAI y el endpoint /health.
  • --env-file ~/.hermes/.env inyecta las claves del proveedor sin meterlas dentro de la imagen.
  • -v ~/.hermes/data:/data es la línea de persistencia - borra esta línea y el agente olvida todo en cada reinicio.

Verifica que está sano:

curl http://localhost:8642/health
# {"status":"ok","gateway":"running"}

Si lo ejecutas en un VPS al que quieres acceder desde tu portátil, no expongas el puerto directamente en 0.0.0.0. Pon un proxy inverso (Caddy, Nginx, Traefik) delante con HTTPS, o expón el puerto solo a través de Tailscale o WireGuard. La API compatible con OpenAI no tiene autenticación por defecto - confía en la red en la que está.

Paso 4 - Usar docker-compose en producción

Para cualquier cosa más allá de una prueba rápida, pasa a docker-compose.yaml. Hace que la configuración sea revisable, reiniciable como una unidad y fácil de extender con el sidecar opcional del dashboard:

services:
  gateway:
    image: ghcr.io/nousresearch/hermes-agent:latest
    container_name: hermes-gateway
    restart: unless-stopped
    command: gateway
    ports:
      - "127.0.0.1:8642:8642"
    env_file:
      - ./.env
    volumes:
      - hermes_data:/data
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8642/health"]
      interval: 30s
      timeout: 5s
      retries: 3
    deploy:
      resources:
        limits:
          memory: 1G

  dashboard:
    image: ghcr.io/nousresearch/hermes-agent:latest
    container_name: hermes-dashboard
    restart: unless-stopped
    command: dashboard
    ports:
      - "127.0.0.1:8643:8643"
    volumes:
      - hermes_data:/data:ro
    depends_on:
      gateway:
        condition: service_healthy

volumes:
  hermes_data:

Algunos detalles que conviene mencionar:

  • El contenedor del dashboard monta el volumen de datos en solo lectura (:ro). Solo lee sesiones y memoria para renderizar la UI, nunca escribe. Eso es lo que permite ejecutar ambos sin riesgo.
  • El puerto del gateway está atado a 127.0.0.1 en el host. La exposición pública es trabajo del proxy inverso, no de Docker.
  • healthcheck permite que depends_on espere al gateway antes de arrancar el dashboard.
  • Un límite de memoria de 1 GB es cómodo para cargas a escala personal. Súbelo si tienes mucho tráfico.

Levanta el stack con docker compose up -d y sigue los logs con docker compose logs -f.

Un diagrama de arquitectura simplificado mostrando el host Docker con dos contenedores, gateway y dashboard, compartiendo un único volumen con nombre montado en solo lectura en el lado del dashboard

Paso 5 - Actualizaciones

El contenedor es la unidad de actualización. Para pasar a una nueva release:

docker compose pull
docker compose up -d

Compose recrea el gateway con la nueva imagen mientras mantiene intacto el volumen con nombre. Memoria, skills y conexiones de Telegram vuelven exactamente como estaban. Fija un tag específico en lugar de latest para producción - ghcr.io/nousresearch/hermes-agent:0.42 en vez de :latest - para que las actualizaciones sean explícitas.

Antes de cualquier actualización, haz un snapshot del volumen:

docker run --rm \
  -v hermes_data:/data \
  -v $(pwd):/backup \
  alpine tar czf /backup/hermes-$(date +%F).tar.gz -C /data .

Restaurar es el mismo comando al revés. Es más rápido y seguro que hacer rollback solo de la imagen.

Errores comunes

Dos contenedores gateway sobre el mismo volumen. Los almacenes de sesión y memoria de Hermes asumen un único escritor. Ejecutar dos contenedores gateway contra el mismo /data corromperá los archivos en minutos. El sidecar del dashboard está bien porque es solo lectura.

Falta --env-file. Sin él, el contenedor arranca pero falla la primera llamada al LLM con un 401. Comprueba docker logs hermes si las respuestas nunca llegan.

Bindear a 0.0.0.0:8642 en un VPS público. La API no tiene autenticación incorporada. Pon siempre un proxy inverso delante que exija HTTPS más auth básica o una restricción a nivel de red (Tailscale, reglas de firewall).

Volúmenes anónimos. Si olvidas la línea -v ~/.hermes/data:/data, Docker crea un volumen anónimo. Sobrevive a reinicios pero es difícil de localizar y fácil de borrar por accidente. Usa siempre un volumen con nombre o un bind al host.

Reconexión del bot de Telegram. Cuando actualizas, el bot se reconecta automáticamente. Si no lo hace, comprueba que TELEGRAM_BOT_TOKEN sigue en .env y que el contenedor tiene salida a internet.

Para incidencias específicas de Telegram, Solución de problemas de Hermes Agent en Telegram cubre la parte de mensajería con más detalle.

Sáltate todo el cableado del contenedor

Ejecutar Hermes en Docker es directo, pero el host sigue siendo tu responsabilidad: backups, certificados TLS, rotación de logs, parches del SO y la cadencia de actualizaciones. Para un agente personal eso está bien - una tarde de domingo de setup y quizás diez minutos al mes después.

Si prefieres saltarte todo eso, Hermify ejecuta tu agente Hermes en un contenedor gestionado y aislado, con secretos cifrados en reposo, actualizaciones automáticas, snapshots diarios del volumen y Telegram conectado desde el dashboard en dos toques. Tú aportas la clave del proveedor; la plataforma se encarga de todo lo de debajo.

Fuentes

Lanza tu propio agente Hermes

Trae tu clave de API, conecta Telegram y ten un agente de IA que evoluciona solo activo en 60 segundos.

Empezar