Conteneur Docker Hermes Agent qui redémarre en boucle

Votre conteneur Hermes Agent démarre, meurt en quelques secondes et Docker le relance. docker ps affiche Restarting (137) 3 seconds ago, le bot ne répond pas sur Telegram et hermes logs fait défiler la même bannière de démarrage en boucle. Cette boucle correspond presque toujours à l'un de cinq problèmes bien précis, et le code de sortie affiché par Docker vous dit lequel. Ce post les parcourt dans l'ordre qui répare le plus d'agents.

Si vous n'avez jamais fait tourner le conteneur, commencez d'abord par faire tourner Hermes Agent dans Docker. Ce guide part du principe que l'image se télécharge correctement, que le compose est en place et que quelque chose casse dès le démarrage du processus.

Étape 1 - Lisez le vrai code de sortie avant de toucher à quoi que ce soit

Docker garde le code de sortie de la dernière exécution dans l'état du conteneur. Lisez-le directement au lieu de deviner d'après les logs :

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

Cette seule ligne vous donne trois choses à la fois : le code de sortie, si le OOM killer du noyau a tué le processus, et toute erreur au niveau du daemon que Docker a attachée au run. Le code de sortie réduit drastiquement la recherche :

137 - le processus a reçu SIGKILL. Presque toujours un OOM kill dû à une limite mémoire du conteneur ou à l'hôte à court de RAM, parfois un docker stop qui a dépassé sa marge de 10 secondes.
139 - erreur de segmentation. Sur Hermes Agent, cela apparaît quand l'architecture de l'image ne correspond pas à l'hôte (image amd64 sur un VPS ARM, ou l'inverse).
125 / 126 / 127 - Docker lui-même n'a pas pu exécuter le conteneur. 125 signifie que le daemon a refusé le run (mauvaises options, image manquante). 126, que l'entrypoint existe mais n'est pas exécutable. 127, que le chemin de l'entrypoint est faux ou que le shell requis manque.
1 ou 2 - le processus Hermes Agent a démarré, passé sa validation et est sorti sur une erreur applicative. Lancez docker logs hermes-agent --tail 100 et cherchez la première ligne qui n'est pas la bannière de démarrage.

Ce n'est qu'après avoir identifié le cas qu'il vaut la peine de toucher à la configuration. Augmenter la mémoire au hasard ou réécrire le compose masque en général la cause réelle et produit un conteneur qui tombe une semaine plus tard pour la même raison.

Terminal montrant la sortie de docker inspect avec le code de sortie, le drapeau OOMKilled et le champ error surlignés

Étape 2 - Sortie 137 avec OOMKilled=true : le piège du VPS 1 Go

De loin la cause la plus courante sur Hermes Agent, et celle contre laquelle le guide VPS pas cher pour agent IA met en garde. L'agent au repos n'est pas lourd, mais dès que vous envoyez une longue conversation, un message vocal ou un appel d'outil MCP, la mémoire monte vite. Sur un VPS 1 Go sans swap, le OOM killer du noyau choisit le plus gros processus (la gateway) et le termine. La politique de redémarrage de Docker relance immédiatement un nouveau conteneur qui alloue la mémoire de la même façon et meurt pareil. C'est votre boucle.

Confirmez dans le journal du noyau :

sudo dmesg -T | grep -i -E 'oom-kill|killed process' | tail -5
# ou sur des hôtes systemd :
sudo journalctl -k --since '30 minutes ago' | grep -i oom

Vous verrez une ligne nommant le processus principal du conteneur (hermes ou node) et son RSS au moment du kill. Deux correctifs, par ordre de préférence :

Donnez plus de RAM à l'hôte. En dessous de 2 Go, Hermes Agent butera sur ce plafond à chaque conversation longue ou passage en mode voix. Le plancher réaliste pour un agent mono-utilisateur confortable est 2 Go avec swap activé, ou 4 Go sans.
Ajoutez du swap sur l'hôte. Sur un VPS Linux : sudo fallocate -l 2G /swapfile && sudo chmod 600 /swapfile && sudo mkswap /swapfile && sudo swapon /swapfile, puis persistez-le dans /etc/fstab. Le swap est plus lent que la RAM, mais c'est la différence entre un conteneur tué et une réponse lente.

Si vous avez fixé un mem_limit explicite dans votre compose, vérifiez-le aussi. Une limite sous 1 Go reproduit le même comportement OOM même sur un gros hôte. Retirez la limite ou passez-la à au moins 1,5 Go avant de redémarrer.

Étape 3 - Sortie 1 ou 2 avec une erreur de config dans les logs

Si le code de sortie est 1 ou 2, Hermes Agent a démarré assez loin pour exécuter sa propre validation et a rejeté la config. Les logs disent ce qui a échoué. Trois formes couvrent l'essentiel :

.env absent ou mal formé. La gateway ne démarre pas sans clé de provider valide. Cherchez Provider key not set ou Missing TELEGRAM_BOT_TOKEN dans les logs. Vérifiez que le .env n'a pas de guillemets en trop autour des valeurs (OPENROUTER_API_KEY="sk-..." est ok, OPENROUTER_API_KEY = "sk-..." avec espaces non) ni de fins de ligne Windows (file .env devrait dire ASCII text, pas CRLF).
Répertoire de données non accessible en écriture. Si vous voyez EACCES: permission denied, open '/data/config.json', le conteneur tourne en utilisateur non-root et le répertoire bind-mount de l'hôte appartient à quelqu'un d'autre. Sur l'hôte : sudo chown -R 1000:1000 ~/.hermes/data. UID 1000 est celui que l'image utilise ; ne lancez pas le conteneur en root juste pour contourner ça.
Port déjà lié. bind: address already in use signifie qu'un autre processus de l'hôte occupe déjà le port 8642. Trouvez-le avec sudo lsof -i :8642 et arrêtez-le, ou mappez Hermes Agent sur un autre port hôte dans le compose (ports: - "9642:8642").

Aucun de ces cas ne se résout tout seul avec des redémarrages. Corrigez la config puis relancez docker compose up -d.

Étape 4 - Sortie 139 ou "exec format error" : le piège de l'image ARM

Si le conteneur meurt en quelques millisecondes avec le code 139, ou que Docker journalise exec /usr/bin/node: exec format error, l'image téléchargée ne correspond pas au CPU de l'hôte. Ça arrive typiquement sur Oracle Cloud Ampere, AWS Graviton ou Raspberry Pi, tous ARM64. Si vous avez pris une image construite uniquement pour linux/amd64, le noyau ne peut pas exécuter le binaire et Docker continue d'essayer.

Comparez les architectures de l'hôte et de l'image :

uname -m                                   # aarch64 = ARM64, x86_64 = amd64
docker inspect hermes-agent-image \
  --format='{{.Architecture}}/{{.Os}}'     # doit correspondre à uname -m

Si ça ne correspond pas, téléchargez en spécifiant la plateforme. L'image officielle Hermes Agent est multi-arch, il suffit donc de préciser :

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

Si vous construisez votre propre image, reconstruisez-la avec docker buildx build --platform linux/arm64,linux/amd64 et poussez les deux tags. Faire tourner une image ARM sur un hôte amd64 est le même bug en miroir et produit le même 139.

Étape 5 - La politique de redémarrage masque l'erreur réelle

restart: always est le bon défaut pour un agent en production, mais pendant le debug il transforme chaque échec au démarrage en boucle serrée qui remplit les logs et cache la première erreur réelle. Quand quelque chose cloche, passez à une politique qui expose l'échec :

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

on-failure:3 redémarre jusqu'à 3 fois sur des sorties non nulles, puis renonce. Le conteneur s'arrête avec l'échec visible dans docker ps -a, et les logs ne sont pas écrasés par de nouveaux démarrages. Une fois la cause corrigée, repassez à restart: always ou unless-stopped. Le guide debug et observabilité de Hermes Agent couvre la rotation des logs qui garde tout ça lisible en production.

Extrait de docker-compose.yml avec la politique de redémarrage surlignée, à côté d'une sortie docker ps montrant le conteneur arrêté

Quand la réparation ne vaut pas le week-end

Chaque panne ci-dessus est réparable, mais chacune coûte un dimanche après-midi à lire des logs noyau et à réécrire des composes. Si vous arrivez ici parce que le bot est HS depuis trois jours et que vous voulez juste revenir à l'usage de l'agent, la version managée existe précisément pour ça. Hermify fait tourner Hermes Agent pour vous sur Telegram, avec le volume mémoire, les clés de provider et la politique de redémarrage déjà câblés, donc un conteneur qui tombe n'est plus votre problème à diagnostiquer. Démarrez avec Hermify et retrouvez l'antenne en une minute environ.

Pour les lecteurs qui préfèrent continuer en self-hosting, la suite à lire est Hermes Agent mémoire et skills - la deuxième raison la plus courante qu'un agent dockerisé ait l'air cassé.