Docker + Hermes Agent: Two Ways to Play | Easy Understand Hermes Agent

Docker + Hermes Agent : Deux Façons de Jouer

Si vous vous êtes déjà demandé comment Docker s’intègre dans l’écosystème Hermes Agent, vous êtes au bon endroit. Il existe en réalité deux manières distinctes de les faire fonctionner ensemble, et il vaut mieux connaître la différence avant de commencer à taper docker run.

Les Deux Modes Docker

Exécuter Hermes DANS Docker — l’agent lui-même vit à l’intérieur d’un conteneur. C’est l’objectif principal de ce guide.
Docker comme backend de terminal — Hermes s’exécute sur votre machine hôte, mais chaque commande qu’il exécute se déroule dans un sandbox Docker unique et persistant. Ce sandbox survit aux appels d’outils, aux /new, et même aux sous-agents tant que le processus Hermes est vivant.

Cet article couvre l’option 1. Le point clé à retenir : toutes vos données (configuration, clés API, sessions, compétences, mémoires) vivent dans un répertoire unique sur votre hôte, monté sur /opt/data dans le conteneur. L’image elle-même est sans état, vous pouvez donc tirer une nouvelle version à tout moment sans perdre votre configuration.

Démarrage Rapide : Première Configuration

Si c’est votre première fois, créez un répertoire de données et démarrez le conteneur en mode interactif pour lancer l’assistant de configuration :

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

Cela vous amène dans l’assistant, qui demande vos clés API et les écrit dans ~/.hermes/.env. Vous n’avez à faire cela qu’une seule fois. Pendant que vous y êtes, c’est le moment idéal pour configurer un système de chat (Telegram, Discord, etc.) afin que votre passerelle ait un endroit où discuter.

⚠️ Un mot de prudence : Évitez les consoles VPS basées sur navigateur pour ces commandes d’installation. Certains fournisseurs (comme Hetzner) déforment les caractères spéciaux — : peut arriver comme ;, @ est mal rendu, et les clés API collées peuvent être corrompues silencieusement. Connectez-vous toujours via SSH pour une saisie de commandes sûre pour le copier-coller. Si vous devez utiliser la console navigateur, tapez les commandes manuellement et vérifiez chaque :, @, =, et /.

Astuce de pro : À l’intérieur du conteneur, exécutez hermes setup --portal une fois — le jeton d’actualisation persiste dans votre volume ~/.hermes monté.

Exécution en Mode Passerelle

Une fois configuré, exécutez le conteneur en arrière-plan comme passerelle persistante :

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

Le port 8642 expose le serveur API compatible OpenAI de la passerelle et son point de terminaison de santé. C’est optionnel si vous n’utilisez que des plateformes de chat, mais requis si vous voulez que le tableau de bord ou des outils externes atteignent la passerelle.

Quoi de Neuf : Passerelle Supervisée

Voici un grand changement : à l’intérieur de l’image Docker officielle, gateway run est maintenant automatiquement supervisé par s6-overlay. Si la passerelle plante, elle redémarre en quelques secondes sans perdre le conteneur. Le tableau de bord (lorsqu’il est activé) est supervisé à ses côtés.

Vous verrez un fil d’Ariane d’une ligne dans docker logs confirmant la mise à niveau. Pour vous désinscrire et retrouver l’ancien comportement (sortie du conteneur = sortie de la passerelle), passez --no-supervise ou définissez HERMES_GATEWAY_NO_SUPERVISE=1. C’est utile pour les tests de fumée CI ; en production, la valeur par défaut supervisée est strictement meilleure.

Arrêts Forcés de la Boucle d’Outils

Un paramètre important pour les passerelles sans surveillance : tool_loop_guardrails.hard_stop_enabled est par défaut false. C’est acceptable pour les sessions interactives où un humain peut voir les avertissements. Mais dans les déploiements sans surveillance, les avertissements seuls pourraient ne pas arrêter un agent coincé dans une boucle. Si vous voulez un comportement de disjoncteur, activez-le dans le config.yaml de votre profil :

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

Exposition du Serveur API

Le serveur API est conditionné par API_SERVER_ENABLED=true. Pour l’exposer au-delà de 127.0.0.1 dans le conteneur, définissez également API_SERVER_HOST=0.0.0.0 et une API_SERVER_KEY (minimum 8 caractères — générez-en une avec 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

Note de sécurité : Ouvrir un port sur une machine exposée à Internet est un risque. Ne le faites pas à moins de comprendre pleinement les conséquences.

Exécution du Tableau de Bord

Le tableau de bord web intégré s’exécute comme un service supervisé s6-rc aux côtés de la passerelle dans le même conteneur. Définissez simplement 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 le tableau de bord plante, s6-supervise le redémarre automatiquement après un court délai. Sa sortie va dans docker logs <container>.

Où Vont les Journaux

Pour la carte complète du routage (passerelles par profil, tableau de bord, réconciliateur de démarrage, et docker logs à l’échelle du conteneur), consultez la section dédiée dans la documentation. La version courte : tout finit par arriver dans docker logs, mais avec des préfixes clairs pour que vous puissiez distinguer ce qui est quoi.

Pour Conclure

Docker vous offre une manière propre et mise à niveau d’exécuter Hermes Agent. Le conteneur est sans état, vos données vivent en sécurité sur l’hôte, et la nouvelle supervision s6 signifie que votre passerelle reste opérationnelle même si elle plante. Que vous exécutiez une configuration simple ou une combinaison complète tableau de bord + serveur API, les commandes ci-dessus vous y amènent en quelques minutes.