Installer Hermes Agent : guide pas à pas

Introduction

Pour installer Hermes Agent, le chemin le plus fiable consiste à obtenir d’abord une conversation locale fonctionnelle, puis à activer les outils dont vous avez réellement besoin. Cette approche est utile aux builders qui veulent un agent capable de lire des fichiers, lancer des commandes et conserver leurs sessions. Elle évite de confondre installation réussie et agent opérationnel. Si vous cherchez seulement une interface de chat sans accès à votre machine, un service web plus simple sera sans doute un meilleur choix. Ce guide couvre Desktop et CLI sur Linux, macOS, WSL2 et Windows natif, jusqu’au diagnostic et au premier test d’action.

Résumé rapide

1. Choisissez Desktop sur macOS ou Windows pour le parcours le plus direct, CLI pour un terminal, un serveur ou WSL2.
2. Vérifiez Git ; sous Linux, ajoutez curl et xz-utils, puis lancez l’installateur officiel adapté au système.
3. Configurez un fournisseur et un modèle d’au moins 64 000 tokens de contexte avec hermes model ou hermes setup --portal.
4. Contrôlez l’environnement avec hermes doctor, puis testez une conversation et une action terminal non destructive.
5. N’ajoutez passerelle, automatisations et outils sensibles qu’après cette validation minimale.

Choisir la bonne installation avant de commencer

Hermes peut être installé avec son application Desktop ou comme outil en ligne de commande. Le moteur reste le même ; c’est surtout votre surface d’utilisation et votre contexte d’exploitation qui changent. Avant de lancer une commande, décidez où l’agent doit vivre et ce qu’il doit pouvoir faire.

Desktop ou CLI ?

Hermes Desktop est le choix recommandé par la documentation officielle sur macOS et Windows. L’installateur met en place l’application native et la CLI. C’est le chemin adapté si vous voulez démarrer sans assembler vous-même l’environnement, tout en gardant la possibilité d’utiliser ensuite hermes dans un terminal.

La CLI convient mieux à Linux, aux serveurs, à WSL2, à Termux et aux builders qui travaillent déjà dans le terminal. Elle facilite aussi la lecture des diagnostics, le scripting et la séparation entre plusieurs profils. Pour comprendre ce que vous installez avant de lui donner accès à vos fichiers, consultez Hermes Agent : guide pour builders IA.

Contexte	Installation conseillée	Pourquoi
Mac ou PC personnel	Desktop	Démarrage guidé et interface native
Poste Linux	CLI	Intégration naturelle au terminal
Windows orienté développement	Desktop ou WSL2	Desktop pour la simplicité, WSL2 pour un environnement Linux
Windows sans WSL2	PowerShell natif	Parcours disponible, mais à tester avec vos outils Windows
VPS ou machine distante	CLI par utilisateur	Configuration isolée, diagnostic et mises à jour simples
Android	CLI dans Termux	Chemin dédié, avec certaines limites propres à Android

Sur Windows, WSL2 reste souvent le choix prévisible lorsque vos projets, commandes et dépendances ciblent Linux. L’installation Windows native en PowerShell est néanmoins prise en charge. Ne mélangez pas les deux au hasard : une installation dans WSL2 possède ses propres fichiers et son propre $HOME, distincts de l’environnement natif Windows.

Les prérequis réellement nécessaires

Pour l’installateur shell, Git est le prérequis principal hors Windows. Sous Linux, vérifiez aussi curl et xz-utils. Sur Debian ou Ubuntu :

git --version
curl --version
xz --version

sudo apt update
sudo apt install -y git curl xz-utils

Résultat attendu : les trois premières commandes affichent une version, sans command not found. Pour Desktop sous Debian ou Ubuntu, build-essential est également nécessaire afin de compiler les modules natifs.

Vous n’avez normalement pas à installer Python, Node.js, uv, ripgrep ou ffmpeg à la main. L’installateur détecte les composants manquants et les met en place.

Enfin, prévoyez un fournisseur de modèle. Un abonnement compatible, une connexion OAuth ou une clé API peuvent être nécessaires selon le choix effectué. Un modèle local est possible, mais il demande davantage de ressources et un endpoint correctement configuré ; le guide Agent IA avec Ollama aide à décider si cette voie vaut la complexité supplémentaire.

Installer, configurer et diagnostiquer Hermes Agent

La bonne séquence est volontairement stricte : installer, recharger le shell, choisir le modèle, vérifier la santé, puis exécuter une vraie action. Tant que l’étape courante n’a pas son signal de réussite, n’ajoutez pas la suivante.

1. Installer sur Linux, macOS, WSL2 ou Termux

Dans un terminal de votre utilisateur normal, exécutez la commande publiée par la documentation Hermes :

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

Évitez sudo sur votre poste sans raison précise. Une installation par utilisateur place le code dans ~/.hermes/hermes-agent/, crée le lanceur ~/.local/bin/hermes et conserve configuration, sessions et compétences dans ~/.hermes/. Une installation root suit une disposition système différente et convient plutôt à un déploiement administré.

Quand le script se termine, rechargez le profil du shell :

source ~/.bashrc

hermes --version

Résultat attendu : hermes --version affiche une version. Si la commande reste introuvable, ouvrez un nouveau terminal, puis contrôlez le lanceur :

ls -l ~/.local/bin/hermes
printf '%s\n' "$PATH"

Si ~/.local/bin n’apparaît pas dans PATH, ajoutez export PATH="$HOME/.local/bin:$PATH" au fichier de configuration de votre shell et rechargez-le.

2. Installer Hermes Agent sur macOS ou Windows avec Desktop

Téléchargez l’installateur Hermes Desktop depuis le site officiel, ouvrez-le et suivez le parcours système. Sur macOS, acceptez uniquement les demandes nécessaires à votre usage. Sur Windows, choisissez Desktop si vous voulez l’expérience native sans préparer WSL2. Une fois l’application installée, ouvrez aussi un terminal et vérifiez :

hermes --version
hermes doctor

Résultat attendu : la CLI répond et hermes doctor produit un rapport lisible. Si Desktop fonctionne mais que la CLI n’est pas reconnue, redémarrez votre terminal avant de modifier le PATH. L’installateur Desktop installe les deux surfaces ; lancer des réparations manuelles trop tôt complique souvent le diagnostic.

Si vous avez d’abord installé la CLI et souhaitez ensuite Desktop, utilisez :

hermes desktop

3. Installer Hermes Agent sur Windows natif avec PowerShell

Ouvrez PowerShell dans votre session utilisateur, puis exécutez l’installateur officiel :

iex (irm https://hermes-agent.nousresearch.com/install.ps1)

Fermez et rouvrez PowerShell avant le contrôle :

hermes --version
hermes doctor

Résultat attendu : les deux commandes s’exécutent sans erreur de résolution. Si vos projets sont dans WSL2, installez plutôt Hermes à l’intérieur de la distribution Linux avec la commande shell. N’installez pas la version native pour piloter par défaut des chemins WSL : les permissions, chemins et binaires diffèrent, ce qui rend les erreurs d’outils plus difficiles à interpréter.

4. Configurer le premier fournisseur et le modèle

Le choix interactif le plus général est :

hermes model

Sélectionnez votre fournisseur, authentifiez-vous par OAuth ou saisissez la clé lorsque l’assistant le demande, puis choisissez un modèle. Hermes demande un contexte d’au moins 64 000 tokens pour conserver assez d’espace lors des tâches à plusieurs outils. Avec un endpoint local ou compatible OpenAI, vérifiez séparément l’URL de base, le nom exact du modèle et la taille de contexte.

Le chemin court pour Nous Portal est :

hermes setup --portal

Il connecte le compte, choisit le fournisseur et active les outils du Tool Gateway. Pour un contrôle complet, lancez hermes setup; pour une base minimale, choisissez le mode Blank Slate, qui conserve seulement le fournisseur, le modèle et les outils fichier et terminal indispensables.

Les secrets sont stockés dans ~/.hermes/.env, tandis que les réglages non secrets vont dans ~/.hermes/config.yaml. Ne collez jamais une vraie clé dans un dépôt, une capture ou une commande partagée. Préférez l’assistant ou hermes config set NOM_DE_VARIABLE valeur, qui dirige la donnée vers le fichier approprié.

Résultat attendu : l’assistant confirme un fournisseur et un modèle, puis revient au terminal sans erreur d’authentification.

5. Vérifier la santé avant la première conversation

Exécutez :

hermes doctor
hermes config check

hermes doctor inspecte dépendances, méthode d’installation et configuration. hermes config check recherche les options manquantes ou devenues obsolètes après une mise à jour. Corrigez les erreurs, puis relancez les deux commandes. Un avertissement relatif à une fonction que vous n’utilisez pas n’a pas le même poids qu’une erreur de fournisseur ou de modèle.

Démarrez ensuite Hermes :

hermes

Posez une question simple, puis quittez et vérifiez la reprise :

hermes --continue

Résultat attendu : la bannière indique le modèle choisi, une réponse arrive sans erreur et la seconde commande retrouve la session. Si la conversation échoue, relancez hermes model avant d’activer navigateur, passerelle ou automatisations.

6. Valider une action d’outil sans risque

Une réponse textuelle valide le modèle, pas l’agent. Demandez une action locale bornée, par exemple :

Affiche le dossier courant, liste uniquement les fichiers à sa racine et résume ce que tu observes sans rien modifier.

Résultat attendu : Hermes demande éventuellement votre approbation, utilise le terminal ou les opérations fichier, puis restitue des éléments qui existent vraiment. Refusez toute action inattendue. Si aucun outil n’est disponible, ouvrez hermes tools, vérifiez les toolsets actifs, puis démarrez une nouvelle session : les changements d’outils ne s’appliquent pas à une conversation déjà ouverte.

7. Résoudre les échecs fréquents dans le bon ordre

• hermes: command not found : rechargez le shell, ouvrez un terminal neuf et vérifiez ~/.local/bin/hermes ainsi que PATH.
• Clé API absente ou authentification refusée : relancez hermes model; ne dupliquez pas le secret dans plusieurs fichiers.
• Modèle rejeté : contrôlez son identifiant et une fenêtre de contexte d’au moins 64K, surtout en local.
• Configuration incomplète après mise à jour : lancez hermes config check, puis hermes config migrate si le diagnostic le propose.
• Outil invisible : vérifiez hermes tools, puis ouvrez une nouvelle session.
• Endpoint local incohérent : testez d’abord l’endpoint hors Hermes. Une réponse HTTP ne garantit ni le bon nom de modèle ni la compatibilité des appels d’outils.

Cette discipline sépare les couches : binaire, configuration, modèle, session, puis outils. En production ou sur un serveur durable, ajoutez ensuite logs, sauvegarde de configuration, isolation du backend terminal et procédure de mise à jour. Le guide Déployer un agent IA détaille ce passage d’un essai local à un service maintenable.

Checklist d’acceptation :

• hermes --version répond dans une nouvelle session terminal ;
• hermes doctor ne signale aucun bloqueur ;
• le fournisseur répond dans une conversation simple ;
• hermes --continue retrouve la session ;
• une action de lecture utilise réellement un outil ;
• aucune clé n’apparaît dans le dépôt ou les logs partagés.

Exemple concret

Prenons une développeuse sous Windows 11 qui travaille sur un dépôt Python dans Ubuntu via WSL2. Son objectif n’est pas encore de déployer un bot : elle veut que Hermes inspecte le projet sans le modifier. Elle ouvre son terminal Ubuntu, vérifie Git, puis installe la CLI :

git --version
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
source ~/.bashrc
hermes --version
hermes model
hermes doctor

Elle choisit un fournisseur hébergé, termine l’authentification sans copier la clé dans le dépôt et lance hermes depuis la racine du projet. Son test d’acceptation est précis :

Lis uniquement pyproject.toml et les noms de fichiers du premier niveau.
Indique la version Python déclarée et la commande de test probable.
Ne crée et ne modifie aucun fichier.

Le résultat est accepté si Hermes utilise les outils autorisés, cite des informations présentes dans le projet et ne produit aucun changement. Elle contrôle ensuite l’état du dépôt avec git status --short, qui doit rester vide, puis ferme la session et exécute hermes --continue. Si la reprise fonctionne, l’installation, le modèle, les lectures et la persistance de session sont validés séparément.

Ce scénario prouve davantage qu’un simple « bonjour ». Il révèle immédiatement un mauvais dossier de travail, un outil désactivé, une permission incohérente ou une hallucination sur le contenu du dépôt. Pour structurer la suite au-delà de l’outil, Créer son premier agent IA aide à transformer ce contrôle ponctuel en boucle définie et testable.

Bonnes pratiques

Gardez une installation par utilisateur sur un poste individuel. Vous évitez ainsi d’exécuter l’agent en root et séparez mieux code, configuration, sessions et secrets. Avant chaque ajout de capacité, conservez un test minimal reproductible : conversation, reprise de session, lecture seule, puis seulement écriture contrôlée.

Mini-checklist de départ :

• mettez Hermes à jour avec hermes update, puis relancez hermes doctor ;
• activez seulement les outils nécessaires avec hermes tools ;
• inspectez toute commande sensible avant approbation ;
• ne versionnez jamais ~/.hermes/.env ni une clé copiée dans un fichier projet ;
• testez les changements de modèle dans une nouvelle session ;
• pour un usage durable, surveillez les logs et préparez une sauvegarde avant migration.

Ne passez pas directement d’un test local à une passerelle exposée en continu. Les permissions, le réseau, les coûts d’API et la maintenance changent alors de nature. Commencez avec une seule surface et un seul fournisseur stables. Une architecture plus complexe n’est justifiée que lorsqu’un usage réel demande la disponibilité, l’accès distant ou l’automatisation.

Questions fréquentes

Comment installer Hermes Agent sur Linux ?

Vérifiez que Git, curl et xz-utils sont disponibles, puis exécutez curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash comme utilisateur normal. Rechargez ensuite .bashrc ou .zshrc, contrôlez hermes --version, configurez le modèle avec hermes model et terminez l’installation Hermes Agent Linux par hermes doctor.

Comment installer Hermes Agent sur Windows ?

Pour Hermes Agent Windows, l’application Desktop est le parcours recommandé. Vous pouvez aussi employer l’installateur PowerShell natif avec iex (irm https://hermes-agent.nousresearch.com/install.ps1). Si votre travail se déroule surtout dans un environnement Linux, installez WSL2 puis lancez l’installateur shell dans la distribution, sans mélanger chemins Windows et WSL.

Peut-on installer Hermes Agent sur macOS ?

Oui. Pour Hermes Agent macOS, téléchargez Desktop depuis le site officiel ou utilisez l’installateur shell dans le Terminal. Dans les deux cas, vérifiez ensuite hermes --version et hermes doctor. Desktop offre le chemin le plus guidé ; la CLI seule est adaptée si vous préférez travailler exclusivement dans le terminal.

Comment configurer Hermes Agent avec un modèle local ?

Lancez hermes model, choisissez un endpoint personnalisé compatible avec l’API attendue, puis renseignez l’URL et le nom exact du modèle. Pour configurer Hermes Agent correctement en local, prévoyez au moins 64 000 tokens de contexte et validez d’abord l’endpoint séparément. Un modèle trop petit ou sans tool calling fiable limitera fortement l’agent.

Articles liés

Une installation n’est terminée que lorsque le modèle répond, qu’un outil réalise une action vérifiable et que la session peut reprendre. Hermes est pertinent si vous voulez un agent local extensible ; pour un simple chat, une solution moins permissive restera plus facile à maintenir. Une fois ce socle stable, suivez le tutoriel Telegram pour retrouver votre agent depuis n’importe quel appareil.

• Hermes Agent : guide pour builders IA
• Agent IA local : guide pratique
• Agent IA avec Ollama : connecter un modèle local
• Déployer un agent IA : passer du test à la production
• Connecter Hermes Agent à Telegram