Installer Hermes Agent : le guide complet et les 6 pièges qui font perdre une demi-journée

• Combien de temps prend vraiment l'installation ?
• Piège n°1 : pourquoi le script postinstall reste-t-il bloqué 30 minutes ?
• Faut-il utiliser le wizard interactif ou la configuration en ligne de commande ?
• Pourquoi le build du dashboard échoue-t-il avec npm run build ?
• Pourquoi hermes dashboard --host 0.0.0.0 est-il refusé ?
• Pourquoi le dashboard affiche « GATEWAY START STARTED » alors que rien ne démarre ?
• Pourquoi un service lancé dans le sandbox est-il invisible depuis l'hôte ?
• Combien de temps prévoir, concrètement ?

Combien de temps prend vraiment l'installation ?¶

Les tutoriels annoncent cinq minutes. curl | bash, deux ou trois questions, et c'est fini — c'est en tout cas ce que promet la documentation officielle. Nous avons chronométré une installation réelle le 1er août 2026, sur une machine Windows avec WSL2 (Ubuntu 22.04), Hermes Agent en version 0.19.1 (build du 2026.7.30). Résultat : 3 heures et 40 minutes, dont plus de la moitié perdue sur des blocages qu'aucune documentation ne mentionne.

Ce n'est pas qu'Hermes Agent soit mal conçu. Le logiciel, une fois en route, tourne très bien — 67 skills et une petite soixante-dizaine d'outils disponibles nativement, c'est du sérieux. Le problème, c'est le chemin entre git clone et un agent qui répond réellement sur Telegram. Ce guide documente ce chemin tel qu'il est, avec les messages d'erreur exacts copiés du terminal, pas une version arrangée après coup.

Si vous êtes sur Windows, sachez tout de suite que WSL2 n'est pas une option parmi d'autres : c'est la seule voie fiable. Nous détaillons pourquoi dans notre guide dédié à l'installation sur Windows. Et si vous découvrez Hermes Agent à l'instant, notre guide complet — ce que c'est, combien ça coûte, ce qu'il ne sait pas faire répond aux questions qu'on nous pose le plus souvent avant même de parler installation.

Piège n°1 : pourquoi le script postinstall reste-t-il bloqué 30 minutes ?¶

Premier arrêt, à peine deux minutes après le lancement de install.sh. Le script enchaîne une série de tâches post-installation, et l'une d'entre elles s'appelle unicode-animations. Sur le papier, c'est anodin : une bannière ASCII animée qui s'affiche au démarrage, rien de plus. En pratique, lancée en mode non interactif (ce qui est le cas par défaut dans un terminal WSL2 sans TTY complet), cette étape ne se termine jamais. Le curseur clignote, aucune erreur ne remonte, et rien ne se passe.

Nous avons laissé tourner 30 minutes avant de couper. Pas de timeout, pas de message, rien. Un Ctrl+C suffit à débloquer la suite de l'installation — l'animation n'est pas une dépendance bloquante, juste un script mal isolé qui ne détecte pas l'absence de terminal interactif.

Ce qu'il faut faire : si l'installation semble figée sur une étape qui mentionne des animations, une bannière ou un logo, n'attendez pas. Interrompez avec Ctrl+C et relancez le script suivant — dans nos tests, l'interruption de cette étape précise n'a jamais cassé la suite de l'installation.

Faut-il utiliser le wizard interactif ou la configuration en ligne de commande ?¶

Une fois l'installation des dépendances terminée, install.sh enchaîne automatiquement sur hermes setup, un assistant interactif : nom de l'agent, fournisseur de modèle, clé API, canal préféré. Pratique si vous êtes devant votre écran et disponible pour répondre à sept ou huit questions à la suite. Beaucoup moins pratique si vous scriptez l'installation, si vous l'exécutez dans un pipeline, ou simplement si vous voulez configurer par étapes sans rester bloqué devant le wizard.

L'alternative existe mais n'est documentée nulle part de façon visible : hermes config set. Cette commande permet de fixer chaque paramètre individuellement, sans passer par le wizard :

Copierhermes config set model.provider openrouter
hermes config set model.name anthropic/claude-sonnet-4.5
hermes config set channels.telegram.enabled true

Un détail qui a son importance au moment de choisir un fournisseur de modèle : sur un modèle gratuit (nous avons testé poolside/laguna-s-2.1:free), l'agent a purement et simplement inventé une installation qu'il n'avait pas faite, et l'a annoncée comme réussie. Aucune alerte, aucun message d'erreur — juste une affirmation fausse présentée avec assurance. Ce n'est pas un bug isolé : c'est le genre de comportement qu'on retrouve régulièrement sur les modèles gratuits ou très légers, moins fiables sur le suivi d'instructions longues. Pour un agent censé gérer de vraies tâches (e-mails, rendez-vous, paiements), ce n'est pas un détail.

Sur les 32 canaux disponibles (Telegram, WhatsApp, Microsoft Teams, Google Chat, e-mail IMAP/SMTP…), Telegram reste de loin le plus rapide à activer : un appairage par QR code, moins de deux minutes, sans configuration réseau particulière. WhatsApp fonctionne aussi, mais via un pont non officiel — plus fragile qu'une intégration Cloud API officielle, et à réserver à un usage secondaire tant que ce point n'est pas stabilisé.

Si vous arrivez d'un autre agent — OpenClaw notamment — sachez que le wizard hermes setup propose une migration automatique des données depuis ~/.openclaw : nous détaillons ce qui se transfère réellement, et ce qui ne se transfère pas, dans notre comparatif Hermes Agent vs OpenClaw.

La configuration complète vit dans deux fichiers : ~/.hermes/config.yaml pour les réglages, et ~/.hermes/.env pour les secrets (clés API, tokens). Un point qui nous a fait perdre vingt minutes : la clé container_persistent, qui contrôle la persistance du bac à sable Docker, doit être imbriquée sous la section terminal: — pas placée à la racine du fichier :

Copierterminal:
  container_persistent: true

Placée au mauvais niveau, elle est silencieusement ignorée. Pas d'erreur de syntaxe, pas d'avertissement : le conteneur repart simplement de zéro à chaque session.

Pourquoi le build du dashboard échoue-t-il avec npm run build ?¶

Le dashboard web d'Hermes Agent n'est pas livré pré-compilé : il faut le construire vous-même avec npm run build. Sous Node.js 20 (la version LTS installée par défaut sur la plupart des images WSL2 récentes), le build échoue avec une pile d'erreurs liées à des dépendances qui attendent une API plus récente — rien d'exotique, juste une incompatibilité de version.

Nous avons reproduit l'erreur, changé uniquement la version de Node, et relancé : succès immédiat sous Node 22. Aucune autre modification.

Avec nvm déjà installé, le changement de version prend dix secondes :

Copiernvm install 22
nvm use 22
npm run build

Sans nvm, comptez plutôt quinze minutes pour installer une version récente de Node proprement sur Ubuntu, le temps de configurer le dépôt NodeSource.

Pourquoi hermes dashboard --host 0.0.0.0 est-il refusé ?¶

Une fois le dashboard construit, l'envie logique est de l'exposer sur toutes les interfaces réseau pour y accéder depuis une autre machine : hermes dashboard --host 0.0.0.0. Résultat : la commande est refusée, sans lancer le service.

La raison est en fait une bonne nouvelle de sécurité : Hermes Agent refuse d'exposer le dashboard sur une interface publique tant qu'aucune authentification n'est configurée. Le dashboard donne accès à la configuration de l'agent, à ses journaux, parfois à ses secrets — l'exposer sans mot de passe sur 0.0.0.0 serait une faille ouverte à quiconque atteint le port.

La correction se fait dans ~/.hermes/config.yaml, sous la section dashboard: :

Copierdashboard:
  basic_auth:
    username: votre_utilisateur
    password: un_mot_de_passe_solide

Une fois cette section renseignée, --host 0.0.0.0 est accepté normalement. À l'usage, mieux vaut de toute façon garder le dashboard sur 127.0.0.1 et passer par un tunnel SSH si vous devez y accéder à distance — l'exposer publiquement, même protégé par mot de passe, reste une surface d'attaque supplémentaire.

Pourquoi le dashboard affiche « GATEWAY START STARTED » alors que rien ne démarre ?¶

C'est le piège le plus déroutant des six, et de loin celui qui coûte le plus de temps. Le gateway est le composant qui relie l'agent aux canaux externes — Telegram, WhatsApp, e-mail. Lancer hermes gateway start sans avoir installé le service au préalable renvoie ce message, mot pour mot :

CopierGateway service is not installed
Run: hermes gateway install

Jusque-là, rien d'anormal — l'erreur est claire et dit exactement quoi faire. Le problème apparaît si vous passez par le dashboard web plutôt que par le terminal : l'interface affiche « GATEWAY START STARTED », comme si tout se déroulait normalement, puis rien ne se passe. Aucun message d'échec, aucune bascule vers un état d'erreur visible. Le statut reste bloqué sur un intitulé qui laisse croire que le démarrage est en cours, indéfiniment.

Nous avons perdu 40 minutes sur ce seul piège, à vérifier les ports, les logs Docker, la configuration réseau — avant de relancer la même commande directement dans le terminal et de voir enfin le vrai message d'erreur que le dashboard avalait silencieusement.

La séquence correcte, dans l'ordre, ne souffre aucune exception :

Copierhermes gateway install
hermes gateway start

Pourquoi un service lancé dans le sandbox est-il invisible depuis l'hôte ?¶

Hermes Agent exécute son bac à sable (le "sandbox" où l'agent peut lancer des commandes, des scripts, des serveurs de test) dans un conteneur Docker basé sur l'image nikolaik/python-nodejs:python3.11-nodejs20. Tant qu'on reste dans le paradigme "l'agent exécute du code et vous récupérez le résultat en texte", tout va bien. Les complications commencent dès qu'on demande à l'agent de démarrer un service réseau — un serveur de développement, une API de test.

Le conteneur reçoit une adresse IP interne au réseau Docker, typiquement dans la plage 172.18.x.x. Un service lancé à l'intérieur écoute bien sur cette IP, mais les ports ne sont pas publiés vers l'hôte par défaut. Résultat : depuis votre machine, curl 172.18.0.5:3000 ou même curl localhost:3000 ne renvoient rien — le service tourne, mais il est injoignable de l'extérieur du conteneur.

Ce n'est pas un bug : c'est le comportement standard de Docker sans mapping de ports explicite. Mais ce n'est documenté nulle part dans le contexte d'Hermes Agent, et l'erreur ressemble à un service qui ne démarre pas alors qu'il tourne très bien — juste invisible.

Combien de temps prévoir, concrètement ?¶

En comptant large : une heure pour l'installation des dépendances et le clonage, une heure quarante pour les six pièges ci-dessus si vous les rencontrez sans les connaître à l'avance, et le reste pour la configuration fine (canaux, priorités, premiers tests). Si vous suivez ce guide en connaissant déjà les six pièges, comptez plutôt 45 minutes à une heure de bout en bout.

Si votre objectif est un serveur dédié plutôt qu'une installation locale, la question du choix de VPS et de son coût réel (hébergement + inférence du modèle) mérite un calcul à part — nous l'avons détaillé dans notre comparatif des offres VPS pour Hermes Agent.