Installer Hermes Agent sur Windows, WSL et Linux : le tuto propre

Le guide pilier t’a donné la carte : ce que fait Hermes Agent, ce qu’il ne fait pas, et pourquoi ça vaut le coup de l’installer en local. Maintenant on passe au terrain.

Ce tuto t’emmène d’une machine vide à une installation saine. Sans bricolage, sans étapes inventées, et sans transformer ton système en champ de mines. L’idée n’est pas de tout couvrir — c’est de te donner un chemin propre, qui tient debout, et qui te laisse dans un état exploitable pour la suite de la série.

Ce que tu auras à la fin Hermes Agent installé via le chemin officiel sur ton OS, la commande hermes disponible dans ton terminal, et un diagnostic qui confirme que l’installation est saine. Pas encore de modèle branché, pas encore de tools exotiques : une base propre, c’est tout.

Avant de commencer Ce tuto ne remplace pas la doc officielle de Nous Research. Il te donne le chemin le plus droit, explique les décisions qui comptent, et pointe les pièges que tu vas rencontrer. Pour les options d’install pointues ou les changements liés à une version précise, reporte-toi à la doc officielle et aux release notes du projet.

Ce qu’il faut avant d’installer Hermes Agent

Pas besoin d’une machine de guerre. Hermes Agent est un runtime d’agent : il orchestre un modèle et des outils, il ne fait pas tourner le modèle lui-même. Tant que tu restes sur des providers externes (OpenRouter, Nous Portal, un endpoint compatible), les besoins matériels sont minimes. C’est quand tu brancheras un modèle local sérieux, via llama.cpp ou équivalent, que le GPU et la RAM deviendront un sujet. Ce point est couvert dans le tuto Hermes Agent + llama.cpp : brancher un modèle local proprement.

Ce qu’il te faut vraiment à ce stade :

  • Un terminal où tu es à l’aise. Tu dois savoir lancer une commande, lire une sortie, corriger une variable d’environnement.
  • git installé. L’installeur officiel le considère comme seul prérequis. Sur Linux et WSL, il est presque toujours déjà là. Sur Windows, il sera fourni par WSL2 lui-même.
  • Un accès réseau propre. Pas de proxy d’entreprise qui bloque GitHub, pas de DNS cassé. L’installeur télécharge le dépôt, uv, Python 3.11 et des dépendances Python et Node : s’il ne peut rien atteindre, rien n’avancera.
  • Un compte ou une clé d’API chez un fournisseur de modèle, ou un endpoint local fonctionnel. Tu peux installer Hermes Agent sans, mais dès la première conversation, il te faudra un modèle à interroger. Autant l’avoir prêt sur le côté.

Un rappel important, parce qu’on le voit trop souvent oublié : ici, on installe l’agent, pas l’écosystème complet. On ne monte pas un modèle local, on ne configure pas des messageries, on n’installe pas de skills communautaires. Une chose à la fois.

Le choix le plus propre selon ton cas

Le point qui règle la moitié des galères avant même qu’elles arrivent : choisir le bon environnement dès le départ.

Le chemin officiel couvert ici vise surtout Linux, macOS et WSL2. Sous Windows, le passage propre reste WSL2, pas Windows natif. D’autres environnements peuvent exister côté projet, mais ils sortent du périmètre de ce tuto.

Traduction concrète pour toi :

  • Tu es sous Linux. Tu installes directement. Fin du débat.
  • Tu es sous Windows. Tu n’installes pas Hermes Agent dans PowerShell ni dans cmd. Tu installes WSL2 (Ubuntu fait très bien le boulot), et tu installes Hermes Agent dans WSL, pas à côté.
  • Tu es sous macOS. Hors périmètre de ce tuto, mais le chemin est proche de Linux.

Pour Windows, la tentation est toujours la même : “j’ai déjà Python d’installé, je vais tenter en natif, on verra bien.” Mauvaise idée. Tu vas te battre avec des chemins, des shells, des outils qui attendent un environnement POSIX, et tu finiras par tout casser un dimanche soir. WSL2 te donne une vraie Linux à côté de Windows, sans machine virtuelle lourde, et tu gardes ton poste de travail habituel. C’est littéralement le chemin conçu pour toi.

Si tu hésites encore : sous Windows, pars sur WSL2 sans te poser de questions. Le reste de ce tuto traite Windows par l’angle “prépare WSL2, puis suis la section Linux/WSL”.

Installation sur Windows (via WSL2)

Pas de section “Windows natif” ici. Elle n’existe pas dans la voie officielle, et je ne vais pas te faire bricoler un truc qui cassera à la première mise à jour. À la place, on monte proprement WSL2 et on installe Hermes Agent dedans.

Étape 1 — Activer WSL2

Depuis un PowerShell lancé en administrateur, on lance la commande d’installation officielle de WSL. Elle active les composants nécessaires et installe une distribution Ubuntu par défaut.

wsl --install

Redémarre la machine si l’installeur te le demande. Au premier lancement d’Ubuntu, tu dois créer un nom d’utilisateur Linux et un mot de passe : ce sont tes identifiants dans WSL, rien à voir avec ton compte Windows.

Vérifie ensuite que tu es bien en WSL2 :

wsl --status

Tu dois voir une version par défaut 2. Si ta distribution est encore en WSL1, wsl --set-default-version 2 ne la convertit pas : cette commande ne change que la version par défaut des nouvelles installations. Convertis la distro existante avec wsl --set-version Ubuntu 2 (ou wsl --set-version <NomDeTaDistro> 2), puis relance-la. Hermes Agent attend un environnement WSL2 moderne, pas une vieille WSL1.

Étape 2 — Préparer la distribution Ubuntu

Ouvre Ubuntu depuis le menu démarrer. Tu arrives dans un vrai terminal Linux. On met à jour et on s’assure que git et curl sont là :

sudo apt update && sudo apt upgrade -y
sudo apt install -y git curl

Rien de compliqué : on nettoie le terrain avant de poser quoi que ce soit dessus.

Étape 3 — Installer Hermes Agent

À partir d’ici, tu es dans Linux. La suite est identique à l’installation Linux “pure” — rends-toi à la section Installation sur Linux ci-dessous et suis-la à la lettre. Toutes les commandes se lancent dans ce même terminal Ubuntu, pas dans PowerShell. C’est le point à ne pas confondre.

Vérification finale côté Windows

Une fois l’installation Linux faite, reviens ici pour un check spécifique WSL :

  • Tu dois pouvoir ouvrir un terminal Ubuntu et taper hermes pour obtenir une réponse du programme.
  • Tes fichiers de travail devraient rester dans le système de fichiers WSL (par exemple ~/hermes-lab/), pas sur un chemin Windows monté du type /mnt/c/.... Les montages fonctionnent, mais les perfs et les permissions y sont moins bonnes, et ça génère des bugs étranges côté outils.

Erreurs classiques sous Windows

  • Lancer l’installeur dans PowerShell. Ça échoue tout de suite : le script est fait pour bash. Tu dois être dans Ubuntu/WSL.
  • Rester en WSL1. Certaines dépendances réseau et système se comportent mal. Force le passage en WSL2.
  • Travailler sous /mnt/c. Ça “marche”, mais tu vas rencontrer des ralentissements et des soucis de permissions. Reste dans ~/ côté WSL.
  • Oublier que tu as deux mondes. Ton git config Windows n’est pas celui de WSL. Ton éditeur Windows ne voit pas forcément tes fichiers WSL pareil. Ne mélange pas les deux terminaux pendant l’install.

Installation sur Linux (et WSL2 une fois prêt)

Là on entre dans le chemin officiel, identique pour une machine Linux native et pour un Ubuntu sous WSL2. L’ensemble de cette section s’applique aux deux.

Option A — L’installeur officiel (recommandé)

C’est la voie que recommande Nous Research pour la grande majorité des utilisateurs. Un seul script, qui se charge de tout : uv, Python 3.11, le clonage du dépôt, l’environnement virtuel, les dépendances, et la mise en place de la commande hermes au niveau utilisateur.

On le lance depuis ton home, dans un shell propre :

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh

Tu dois voir le script enchaîner les étapes : téléchargement de uv, création d’un environnement Python 3.11, installation des paquets, mise en place du binaire hermes. Lis la sortie au lieu de la scroller : c’est là que tu verras passer les vrais problèmes (réseau, permissions, dépendances système manquantes).

Quand c’est terminé, recharge ton shell pour que la commande hermes soit disponible :

source ~/.bashrc

Si tu es sous zsh, remplace par source ~/.zshrc. Ensuite, un simple :

hermes

doit lancer Hermes Agent. Au premier démarrage, un assistant de configuration te demandera quel fournisseur de modèle tu veux brancher et te guidera pour poser une clé d’API. Tu peux aussi lancer ou relancer les étapes de config plus tard avec des commandes dédiées comme hermes model, hermes tools ou hermes setup. Pas besoin de tout configurer ce soir : on valide que le programme démarre, c’est déjà beaucoup.

Option B — L’installation manuelle

Utile si tu veux comprendre ce qui se passe, contrôler chaque étape, ou travailler sur le code. Pas nécessaire pour simplement utiliser l’agent.

On installe d’abord uv, un gestionnaire de paquets Python rapide :

curl -LsSf https://astral.sh/uv/install.sh | sh

Puis on clone le dépôt avec ses sous-modules, et on prépare un environnement virtuel sous Python 3.11 :

git clone --recurse-submodules https://github.com/NousResearch/hermes-agent.git
cd hermes-agent
uv venv venv --python 3.11
export VIRTUAL_ENV="$(pwd)/venv"
uv pip install -e ".[all]"

À ce stade, l’agent est installable depuis l’intérieur du dépôt. Selon la version, tu pourras rendre la commande hermes globale via un lien symbolique dans ~/.local/bin/ — la doc officielle décrit la manip à jour, et c’est le genre de détail qui peut bouger d’une version à l’autre. Reporte-toi à elle plutôt que de coller une ligne vue sur un forum.

Vérification finale

Le projet fournit une commande de diagnostic faite exactement pour ça :

hermes doctor

Lis la sortie ligne par ligne. Elle te dit ce qui est en place, ce qui manque, et ce qui cloche. C’est le seul vrai signal d’une installation saine. Un hermes qui démarre ne prouve pas grand-chose ; un hermes doctor propre, si.

Un second test utile : lance hermes, laisse l’assistant te proposer un provider, et pose une question toute bête au modèle (“dis bonjour en français”). Si tu obtiens une réponse, la boucle est bouclée : runtime + provider + terminal communiquent.

Erreurs classiques sous Linux / WSL

  • Python système qui s’invite. Tu avais déjà un Python 3.10, 3.12, un pyenv, un conda à moitié configuré. uv gère sa propre version, mais si ton shell pointe ailleurs, tu vas t’emmêler. Installe dans un shell propre, sans environnement virtuel déjà activé.
  • source ~/.bashrc oublié. Tu lances hermes, ton shell te répond command not found, tu paniques. Dans 90 % des cas, il suffit de recharger le shell ou d’ouvrir un nouveau terminal.
  • Dépendances système manquantes. Sur des distributions minimalistes, il manque parfois build-essential, ripgrep, ffmpeg. Le hermes doctor les repère : installe au fur et à mesure, pas en préventif.
  • Installation dans un dossier exotique. Pose le dépôt dans un endroit simple, dans ton home. Évite les chemins avec espaces, accents ou liens symboliques fantaisistes.

Vérifier que tout fonctionne vraiment

Installer, ce n’est pas valider. Avant d’aller plus loin, fais tourner ce trio court :

  1. hermes doctor — lecture complète de la sortie, rien de rouge, pas d’avertissement critique.
  2. hermes — le programme démarre, l’assistant te pose éventuellement une question de config, et tu atteins une invite de conversation.
  3. Une question triviale au modèle — une réponse lisible arrive, sans erreur d’authentification ni time-out.

Si les trois passent, ton installation est exploitable. Si l’un des trois coince, tu sais exactement où regarder : pas la peine de tout réinstaller, tu as le point de rupture.

Symptômes classiques d’une install bancale à surveiller :

  • hermes démarre mais toute requête échoue → clé d’API mal posée dans ~/.hermes/.env, ou provider mal sélectionné. Relance hermes model.
  • Lancement qui traîne dix secondes puis plante → réseau, proxy, DNS. Teste un curl vers l’endpoint du provider pour isoler.
  • Tout marche mais le hermes doctor gueule sur un outil manquant → pas grave, installe l’outil quand tu en auras besoin, n’ajoute pas tout préventivement.

Les erreurs les plus fréquentes

Vues dix fois, citées dix fois, reproduites dix fois :

  • Installer Hermes Agent et un modèle local en même temps. Tu empiles deux sources de bugs. Agent d’abord, modèle ensuite, dans cet ordre.
  • Activer trente tools au premier lancement. Chaque tool ajoute une surface d’erreur. Démarre avec le minimum, valide, ajoute un par un.
  • Mélanger Windows natif et WSL2. Deux installations Python, deux git, deux caches, deux shells. Impossible à débugger. Choisis un côté.
  • Coller un config.yaml trouvé sur un dépôt inconnu. Tu importes des choix que tu ne comprends pas et qui ne correspondent pas à ta version. Pars de l’exemple officiel, modifie ce que tu comprends.
  • Confondre “agent installé” et “modèle branché”. Hermes Agent peut démarrer sans qu’aucun modèle ne réponde. Un run “silencieux” ne veut pas dire que tout est cassé : ça veut souvent dire que tu n’as pas encore donné de cerveau à l’agent.

Ce que tu ne dois pas faire

Court, mais ferme :

  • Ne lance pas dix outils d’un coup au premier démarrage.
  • Ne mélange pas ton install Windows natif et ton install WSL “pour comparer”.
  • Ne modifie pas config.yaml avant d’avoir validé un hermes doctor propre.
  • Ne te jette pas sur les skills communautaires ou les intégrations messagerie tant que l’agent de base ne répond pas correctement.
  • Ne désactive pas la sécurité par défaut “parce que c’est chiant”. Tu le paieras.

La règle est simple : une installation saine, d’abord. L’écosystème, après. Si tu inverses l’ordre, tu passeras plus de temps à débugger qu’à utiliser l’outil.

La suite logique

Tu as maintenant un Hermes Agent installé proprement, un hermes doctor lisible, et une première conversation qui tourne. C’est la base. À partir de là, tu peux attaquer la suite de la série sans te demander si ton socle tient :

  • Brancher un modèle local via llama.cpp pour sortir des providers distants.
  • Lire ligne par ligne un config.yaml minimal et comprendre ce que chaque option fait vraiment.
  • Ajouter des tools un par un, en validant l’impact.
  • Mettre en place une hygiène de sécurité au quotidien.

Tu peux revenir au guide complet Hermes Agent pour reposer le cadre, enchaîner avec Hermes Agent + llama.cpp : brancher un modèle local proprement, ou lire Hermes Agent : comprendre et régler la config sans tout casser pour la suite logique.

L’installation propre, c’est le truc ennuyeux qu’on bâcle et qui coûte trois soirées plus tard. Tu viens de ne pas la bâcler. Le reste de la série sera plus simple pour ça.