Tutoriel 16 : Déploiement avec Docker

Bon retour parmi nous, explorateurs d’Hermes ! Dans le tutoriel précédent, nous avons appris à exécuter Hermes Agent directement sur nos machines. Aujourd’hui, on passe au niveau supérieur : on installe Hermes dans un conteneur Docker. C’est un vrai changement de jeu pour garder votre environnement propre, portable et facile à mettre à jour.

Deux façons de faire cohabiter Docker et Hermes

Avant de plonger, il est important de comprendre que Docker et Hermes Agent peuvent fonctionner ensemble de deux manières distinctes :

Exécuter Hermes dans Docker – L’agent lui-même vit dans un conteneur. C’est ce que nous allons voir aujourd’hui.
Docker comme backend de terminal – Hermes tourne sur votre machine hôte, mais chaque commande qu’il exécute se fait dans un bac à sable Docker persistant. C’est excellent pour la sécurité et l’isolation, mais c’est un sujet pour un autre jour.

Aujourd’hui, on se concentre sur l’option 1. La beauté de cette approche, c’est que toutes vos données — configuration, clés API, sessions, compétences et souvenirs — vivent dans un seul répertoire sur votre machine hôte, monté dans le conteneur à /opt/data. Le conteneur lui-même est sans état, donc vous pouvez tirer une nouvelle version et mettre à jour sans rien perdre.

Démarrage rapide : votre premier conteneur

Si vous êtes complètement nouveau avec Hermes, le chemin le plus simple est de créer un répertoire de données et d’exécuter l’assistant de configuration de manière interactive. Il vous guidera pour saisir vos clés API et les enregistrer dans ~/.hermes/.env.

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

Un mot de prudence : évitez les consoles VPS basées sur le navigateur (comme celles de Hetzner Cloud) pour ces commandes. Elles déforment souvent les caractères spéciaux comme :, @ et =, ce qui peut corrompre silencieusement vos arguments docker run. Connectez-vous toujours via SSH (ssh root@<host>) pour une saisie sans risque de copier-coller. Si vous devez utiliser la console du navigateur, tapez les commandes manuellement et vérifiez chaque caractère.

Une fois dans l’assistant, il est fortement recommandé de configurer un système de chat (Telegram, Discord, etc.) pour que votre passerelle ait un endroit où envoyer des messages.

Exécution en mode passerelle

Une fois configuré, vous voudrez exécuter Hermes comme une passerelle d’arrière-plan persistante. C’est ainsi qu’il se connecte à vos plateformes de chat et reste actif 24h/24 et 7j/7.

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

Le drapeau -p 8642:8642 expose le serveur API compatible OpenAI de la passerelle et son point de contrôle de santé. Il est facultatif si vous n’utilisez que des plateformes de chat, mais requis si vous voulez que le tableau de bord ou des outils externes atteignent votre passerelle.

Voici une nouvelle fonctionnalité sympa : dans l’image Docker officielle, gateway run est désormais automatiquement supervisé par s6-overlay. Cela signifie que si le processus de la passerelle plante, il est redémarré en quelques secondes sans perdre le conteneur. Vous verrez une trace dans docker logs confirmant la mise à niveau. Si vous voulez l’ancien comportement (où le conteneur se ferme quand la passerelle se ferme), passez --no-supervise ou définissez HERMES_GATEWAY_NO_SUPERVISE=1. Pour la production, la supervision par défaut est strictement meilleure.

Exposer le serveur API

Par défaut, le serveur API est conditionné par API_SERVER_ENABLED=true. Pour l’exposer au-delà de 127.0.0.1 dans le conteneur, vous devrez définir quelques variables d’environnement :

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 doit contenir au moins 8 caractères — générez-en une avec openssl rand -hex 32. Important : ouvrir un port sur une machine exposée à Internet est un risque de sécurité. Ne le faites pas à moins de comprendre pleinement les implications.

Exécuter le tableau de bord

Vous voulez un tableau de bord web pour surveiller votre passerelle ? Définissez HERMES_DASHBOARD=1 et exposez le port 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

Le tableau de bord est également supervisé par s6, donc il redémarre automatiquement en cas de plantage. Sa sortie va dans docker logs <conteneur>.

Une note sur les garde-fous de boucle d’outils

Pour les passerelles sans surveillance, envisagez d’activer les arrêts durs pour les garde-fous de boucle d’outils. La valeur par défaut est false, ce qui convient aux sessions interactives où un humain peut voir les avertissements. Mais dans une passerelle sans surveillance, un agent coincé dans une boucle pourrait ne jamais s’arrêter. Ajoutez ceci au config.yaml de votre profil :

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

Pour conclure

Voilà pour le déploiement Docker ! Vous avez maintenant un conteneur sans état et évolutif, avec toutes vos données montées en toute sécurité sur l’hôte. Dans le prochain tutoriel, nous explorerons le tableau de bord plus en détail. D’ici là, bon conteneur à tous !