El contenedor Docker de Hermes Agent se reinicia sin parar

Tu contenedor de Hermes Agent arranca, muere a los pocos segundos y Docker lo vuelve a levantar. docker ps muestra la línea Restarting (137) 3 seconds ago, el bot no responde en Telegram y hermes logs repite el mismo banner de arranque una y otra vez. Ese bucle casi siempre corresponde a uno de cinco problemas muy concretos, y el código de salida que imprime Docker te dice cuál. Este post los recorre en el orden que arregla más agentes.

Si nunca has ejecutado el contenedor, empieza primero por cómo correr Hermes Agent en Docker. Esta guía asume que la imagen se descarga bien, que el compose está en su sitio y que algo se rompe en cuanto arranca el proceso.

Paso 1 - Lee el código de salida real antes de tocar nada

Docker guarda el código de salida de la última ejecución dentro del estado del contenedor. Léelo directamente en lugar de adivinar por los logs:

docker inspect --format='{{.State.ExitCode}} OOM={{.State.OOMKilled}} err={{.State.Error}}' hermes-agent

Esa única línea te da tres cosas a la vez: el código de salida, si el OOM killer del kernel mató el proceso y cualquier error a nivel de daemon que Docker haya adjuntado. El código de salida acota muchísimo la búsqueda:

137 - al proceso se le envió SIGKILL. Casi siempre es un OOM kill por un límite de memoria del contenedor o porque el host se quedó sin RAM, y en ocasiones un docker stop que agotó su margen de 10 segundos.
139 - fallo de segmentación. En Hermes Agent aparece cuando la arquitectura de la imagen no coincide con el host (una imagen amd64 en un VPS ARM, o al revés).
125 / 126 / 127 - Docker en sí no pudo ejecutar el contenedor. 125 significa que el daemon rechazó la ejecución (opciones malas, imagen faltante). 126, que el entrypoint existe pero no es ejecutable. 127, que la ruta del entrypoint es incorrecta o falta el shell que necesita.
1 o 2 - el proceso de Hermes Agent llegó a arrancar, corrió su validación y salió con un error de aplicación. Ejecuta docker logs hermes-agent --tail 100 y busca la primera línea que no sea del banner de arranque.

Solo cuando sabes cuál de estos casos tienes tiene sentido tocar la configuración. Subir memoria a ciegas o reescribir el compose suele tapar la causa real y produce un contenedor que vuelve a caer una semana después por lo mismo.

Terminal mostrando la salida de docker inspect con el código de salida, el flag OOMKilled y el campo error resaltados

Paso 2 - Salida 137 con OOMKilled=true: la trampa del VPS de 1 GB

De largo, la causa más común en Hermes Agent, y contra la que avisa la guía de VPS baratos para IA. El agente en reposo no consume mucho, pero en cuanto le mandas una conversación larga, un mensaje de voz o una llamada a una herramienta MCP, la memoria sube rápido. En un VPS de 1 GB sin swap, el OOM killer del kernel elige el proceso más grande (el gateway) y lo termina. La política de reinicio de Docker lanza al instante un nuevo contenedor, que pide memoria de la misma forma y muere igual. Ese es tu bucle.

Confírmalo en el log del kernel:

sudo dmesg -T | grep -i -E 'oom-kill|killed process' | tail -5
# o en hosts con systemd:
sudo journalctl -k --since '30 minutes ago' | grep -i oom

Verás una línea con el proceso principal del contenedor (hermes o node) y su RSS en el momento del kill. Dos arreglos, por orden de preferencia:

Dale más RAM al host. Por debajo de 2 GB, Hermes Agent va a chocar contra este techo cada vez que una conversación se alargue o entre el modo voz. El mínimo realista para un agente de un solo usuario cómodo es 2 GB con swap activado, o 4 GB sin él.
Añade swap al host. En un VPS Linux: sudo fallocate -l 2G /swapfile && sudo chmod 600 /swapfile && sudo mkswap /swapfile && sudo swapon /swapfile, y persístelo en /etc/fstab. La swap es más lenta que la RAM, pero es la diferencia entre un contenedor muerto y una respuesta lenta.

Si has puesto un mem_limit explícito en tu compose, revísalo también. Un límite por debajo de 1 GB reproduce el mismo OOM incluso en un host grande. Quítalo o súbelo al menos a 1,5 GB antes de reiniciar.

Paso 3 - Salida 1 o 2 con un error de config en los logs

Si el código de salida es 1 o 2, Hermes Agent arrancó lo suficiente como para ejecutar su propia validación y rechazó la configuración. Los logs te dicen qué falló. Tres formas cubren casi todos los casos:

.env ausente o mal formado. El gateway no arranca sin una clave de proveedor válida. Busca Provider key not set o Missing TELEGRAM_BOT_TOKEN en los logs. Comprueba que el .env no tenga comillas sueltas alrededor de los valores (OPENROUTER_API_KEY="sk-..." está bien, OPENROUTER_API_KEY = "sk-..." con espacios no) ni finales de línea de Windows (file .env debería decir ASCII text, no CRLF).
Directorio de datos sin permisos de escritura. Si ves EACCES: permission denied, open '/data/config.json', el contenedor corre como usuario no-root y el directorio bind-montado del host pertenece a otra persona. En el host: sudo chown -R 1000:1000 ~/.hermes/data. UID 1000 es el que usa la imagen; no ejecutes el contenedor como root solo para saltarte esto.
Puerto ya en uso. bind: address already in use significa que otro proceso del host ya está en el puerto 8642. Localízalo con sudo lsof -i :8642 y para el otro proceso, o mapea Hermes Agent a otro puerto de host en el compose (ports: - "9642:8642").

Ninguno de estos se soluciona solo a base de reinicios. Arregla la config y vuelve a docker compose up -d.

Paso 4 - Salida 139 o "exec format error": la trampa de la imagen ARM

Si el contenedor sale en milisegundos con código 139, o Docker registra exec /usr/bin/node: exec format error, la imagen que descargaste no coincide con la CPU del host. Suele pasar en Oracle Cloud Ampere, AWS Graviton o una Raspberry Pi, todos ARM64. Si has descargado una imagen construida solo para linux/amd64, el kernel no puede ejecutar el binario y Docker sigue intentándolo.

Compara las arquitecturas del host y de la imagen:

uname -m                                   # aarch64 = ARM64, x86_64 = amd64
docker inspect hermes-agent-image \
  --format='{{.Architecture}}/{{.Os}}'     # debería coincidir con uname -m

Si no coinciden, descarga indicando la plataforma. La imagen oficial de Hermes Agent es multi-arch, así que basta con especificarla:

docker pull --platform linux/arm64 hermes/agent:latest

Si construyes una imagen propia, reconstrúyela con docker buildx build --platform linux/arm64,linux/amd64 y publica ambos tags. Correr una imagen ARM en un host amd64 es el mismo bug en espejo y produce el mismo 139.

Paso 5 - La política de reinicio está tapando el error real

restart: always es el valor por defecto correcto para un agente en producción, pero durante el debugging convierte cada arranque fallido en un bucle ocupado que llena los logs y esconde el primer error real. Cuando algo va mal, pasa a una política que exponga el fallo:

services:
  hermes-agent:
    image: hermes/agent:latest
    restart: "on-failure:3"

on-failure:3 reintenta hasta 3 veces en salidas no cero y luego se rinde. El contenedor queda parado con el fallo visible en docker ps -a, y los logs no se sobrescriben por arranques nuevos. En cuanto arregles la causa, vuelve a restart: always o unless-stopped. La guía de debugging y observabilidad de Hermes Agent cubre la rotación de logs que mantiene esto legible en producción.

Fragmento de docker-compose.yml con la política de reinicio resaltada, junto a una salida de docker ps mostrando el contenedor parado

Cuando el arreglo no compensa el fin de semana

Todos los fallos anteriores tienen solución, pero cada uno se lleva una tarde de domingo leyendo logs del kernel y reescribiendo composes. Si has llegado hasta aquí porque el bot lleva tres días caído y quieres volver a usar el agente, la versión gestionada existe exactamente para esto. Hermify ejecuta Hermes Agent por ti en Telegram, con el volumen de memoria, las claves de proveedor y la política de reinicio ya configurados, así que el contenedor cayendo deja de ser tu problema. Empieza con Hermify y vuelve a estar en línea en cerca de un minuto.

Para quienes prefieren seguir con self-hosting, el siguiente post es Hermes Agent memoria y skills - el segundo motivo más habitual de que un agente en Docker parezca roto.