Guide complet 2026 Hermes Agent : installation et configuration — checklist pas à pas avec cas pratique
Les tutoriels Hermes Agent ont l'air complets jusqu'au moment où vous terminez… sans savoir si tout fonctionne vraiment. Ce guide transforme l'installation, la configuration, le premier lancement et un cas pratique concret en six checklists par étapes — chaque ligne précise quoi vérifier, comment savoir que c'est bon, et où regarder en premier si ça échoue.
Vous avez peut-être déjà lancé la commande d'installation, mais la clé API est incorrecte. Ou le CLI démarre, mais les permissions sont trop larges et vous ne savez pas où sont les journaux. Une installation et une configuration complètes doivent se valider étape par étape : ce n'est que lorsque l'environnement, l'installation, le modèle, les permissions, les journaux et le cas pratique passent tous que Hermes Agent est réellement prêt.
À retenir dès le départ : sur macOS, l'installateur officiel en une ligne ne demande que Git au préalable ; la configuration vit sous ~/.hermes/ ; les contrôles de santé passent par hermes doctor ; exécutez le cas pratique dans un répertoire de test dédié — n'accordez pas l'accès disque complet dès le premier jour.
Checklist maîtresse : de zéro au cas pratique validé
Parcourez les six étapes dans l'ordre. Ce n'est qu'après avoir coché chaque case que vous devriez brancher Gateway, Cron ou un dépôt de production.
| Étape | Validation clé | Commande / chemin |
|---|---|---|
| ① Pré-installation | Git, réseau, répertoire de test, compte API prêts | git --version, ~/hermes-workspace |
| ② Installation | hermes --version OK, arborescence correcte |
install.sh officiel, ~/.local/bin/hermes |
| ③ Configuration | Provider, modèle, .env, espace de travail, journaux confirmés | hermes setup, ~/.hermes/.env |
| ④ Premier lancement | Ping modèle, lecture/écriture fichiers, journaux, reprise après redémarrage | hermes, hermes doctor |
| ⑤ Cas pratique | Résumé + todos générés, journaux traçables, rollback OK | sample.txt dans le répertoire de test |
| ⑥ Dépannage / clôture | Recherche par couches ; resserrer les permissions avant d'étendre | ~/.hermes/logs/ |
1. Checklist pré-installation
Vérifiez chaque ligne avant de copier la moindre commande curl. L'installateur Git officiel n'a pour prérequis strict que Git ; Python 3.11, Node.js v22, uv, ripgrep et ffmpeg sont gérés par le script d'installation.
| ☐ | Vérification | Critère de réussite | En cas d'échec, regarder d'abord |
|---|---|---|---|
| ☐ | Confirmer macOS et puce | Mac Apple Silicon ou Intel ; version OS conforme à la doc d'installation officielle | Mettre à jour macOS ou utiliser pip / Nix |
| ☐ | git --version |
Version affichée ; si absent, lancer xcode-select --install ou installer git via Homebrew |
Xcode CLT / Homebrew |
| ☐ | Tester le réseau | curl -I https://raw.githubusercontent.com et le domaine de votre provider LLM sont accessibles |
Proxy, DNS, pare-feu d'entreprise |
| ☐ | Confirmer l'espace disque | Au moins 5–10 Go libres (venv Python, Node, dépendances d'automatisation navigateur) | Vider ~/Library/Caches |
| ☐ | Créer compte LLM et clé API | OpenRouter (flexible) ou Anthropic / OpenAI, etc. ; clé dans un gestionnaire de mots de passe, pas collée dans un chat ou une capture d'écran | Console de facturation du provider et disponibilité régionale |
| ☐ | Créer l'espace de test | mkdir -p ~/hermes-workspace/{inbox,outbox,scratch,backups} et chmod 700 ~/hermes-workspace |
Faute de chemin, permissions disque |
| ☐ | Sauvegarder config existante (réinstallation) | Ancien ~/.hermes/ archivé dans backups/ |
Ne pas faire rm -rf ~/.hermes sans sauvegarde |
| ☐ | Préparer le texte d'exemple (cas pratique) | ~/hermes-workspace/inbox/sample.txt existe, 200–500 mots suffisent |
Encodage UTF-8 |
2. Checklist d'installation
Commande macOS officielle (doc mai 2026) :
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bashAlternatives : pip install hermes-agent (PyPI, v0.14+) ; utilisateurs Nix : voir le guide Nix officiel. Définir HERMES_INSTALL_DIR pour un chemin personnalisé — voir la doc officielle.
| ☐ | Vérification | Critère de réussite | En cas d'échec, regarder d'abord |
|---|---|---|---|
| ☐ | Vérifier la source de la commande | URL pointe vers NousResearch/hermes-agent repo main/scripts/install.sh |
Ne pas utiliser de scripts one-click inconnus |
| ☐ | Surveiller la sortie d'installation | Pas d'erreur fatale ; clone, venv, uv, étapes Node terminées sans abort | Timeout réseau → réessayer ; permissions → éviter sudo sauf mode root voulu |
| ☐ | source ~/.zshrc puis which hermes |
Chemin = ~/.local/bin/hermes (installation par utilisateur) |
PATH non rafraîchi → nouveau terminal ; confirmer ~/.local/bin dans PATH |
| ☐ | hermes --version ou hermes doctor |
CLI affiche version/diagnostics ; pas de command not found |
Appel accidentel du Python système au lieu du launcher venv |
| ☐ | Vérifier l'arborescence d'installation | Code dans ~/.hermes/hermes-agent/ ; répertoire de données ~/.hermes/ créé |
HERMES_HOME surchargé de façon inattendue |
| ☐ | Contrôler les dépendances runtime | hermes doctor affiche vert / indices de correction pour Python, Node, ripgrep, etc. |
Éléments manquants dans la sortie doctor ; essayer hermes update |
3. Checklist de configuration
Fichiers principaux : ~/.hermes/config.yaml (paramètres) et ~/.hermes/.env (clés API et variables d'environnement). Lancez l'assistant complet au premier setup :
hermes setup # assistant complet
# ou étape par étape :
hermes model # choisir provider et modèle
hermes tools # activer/désactiver les outils
hermes config set KEY value| ☐ | Vérification | Critère de réussite | En cas d'échec, regarder d'abord |
|---|---|---|---|
| ☐ | Configurer le provider LLM | Après hermes model, config.yaml contient model.default ; exemple OpenRouter : OPENROUTER_API_KEY dans .env |
Faute de clé, limites régionales du provider, solde du compte |
| ☐ | Permissions du fichier secrets | chmod 600 ~/.hermes/.env ; aucune clé en clair dans config.yaml |
Clé accidentellement commitée dans yaml ou git |
| ☐ | Répertoire de travail | MESSAGING_CWD=~/hermes-workspace (ou chemin absolu) dans .env |
Chemin manquant, répertoire iCloud sync mal choisi |
| ☐ | Backend terminal et permissions | Phase d'essai : garder terminal.backend: local + approvals.mode: manual ; envisager docker/ssh pour la production |
Mode YOLO ou GATEWAY_ALLOW_ALL_USERS activé par erreur |
| ☐ | Emplacement des journaux | ~/.hermes/logs/ existe et est inscriptible ; pas sur un chemin Dropbox/iCloud sync |
Disque plein, permissions du répertoire |
| ☐ | Jeu d'outils | hermes tools n'active que ce dont le cas pratique a besoin (lecture/écriture fichiers, terminal) ; ajouter navigateur/gateway plus tard |
Outils supplémentaires élargissent la surface de permissions |
| ☐ | Intégrité de la config | hermes config check passe ; après mise à jour lancer hermes config migrate si nécessaire |
Saut de version sans migrate |
4. Checklist premier lancement
cd ~/hermes-workspace
hermes # CLI interactif| ☐ | Vérification | Critère de réussite | En cas d'échec, regarder d'abord |
|---|---|---|---|
| ☐ | Ping modèle | Prompt court du type « Dis OK » obtient une réponse cohérente en quelques secondes ; pas de API key not set |
hermes model, noms de variables .env, page de statut du provider |
| ☐ | Lecture/écriture fichiers | L'agent crée ping.txt dans scratch/ et le relit ; fichiers restent à l'intérieur de l'espace de travail uniquement |
cwd, invites de confidentialité macOS, approbation refusée par erreur |
| ☐ | Écriture des journaux | Après la conversation, ~/.hermes/logs/ contient de nouvelles entrées ou horodatages mis à jour |
Niveau de log, permissions du répertoire |
| ☐ | Fermer et rouvrir le terminal | Nouveau terminal : hermes démarre toujours ; config intacte |
Profil shell n'a pas persisté PATH |
| ☐ | Reprise après redémarrage (optionnel) | Après reboot le CLI fonctionne ; si hermes gateway install a été lancé, le service launchd redémarre selon la doc officielle |
launchctl list | grep hermes, journaux gateway |
| ☐ | Contrôle final hermes doctor |
Aucun élément bloquant ; méthode d'installation détectée correctement (git / pip / nix) | Corriger les items doctor un par un — ne pas réinstaller aveuglément |
5. Checklist cas pratique : résumé de texte + extraction de todos
Réalisez votre première tâche vérifiable dans un répertoire de test. Ne pointez pas vers des dépôts de production, consoles cloud ou ~/Documents.
5.1 Préparer l'entrée
cat > ~/hermes-workspace/inbox/sample.txt <<'EOF'
Notes de standup hebdomadaire (échantillon test)
- Alex : finir la doc API v2 la semaine prochaine
- Jordan : corriger le 403 login d'ici mercredi
- Sam : comparer Hermes Agent vs OpenClaw, rapport vendredi
EOF
cp ~/hermes-workspace/inbox/sample.txt ~/hermes-workspace/backups/sample.txt.bak5.2 Prompt de tâche (coller dans le CLI hermes)
Lis inbox/sample.txt et crée deux fichiers dans outbox/ :
1) summary.md — résumé en moins de 200 mots
2) todos.md — liste de todos Markdown avec propriétaire et date d'échéance par item
Ne modifie pas l'original dans inbox. N'accède pas aux chemins hors de l'espace de travail.| ☐ | Vérification | Critère de réussite | En cas d'échec, regarder d'abord |
|---|---|---|---|
| ☐ | Fichiers de sortie existent | outbox/summary.md et outbox/todos.md créés ; noms et dates correspondent à l'entrée |
Approbation en attente, hallucination du modèle |
| ☐ | Original inchangé | diff inbox/sample.txt backups/sample.txt.bak ne montre aucune différence |
Contraintes du prompt, permissions des outils |
| ☐ | Journaux traçables | Les journaux contiennent les enregistrements d'appels d'outils de cette session | Chemin des logs, niveau de log |
| ☐ | Vérification rollback | rm outbox/*.md puis relancer la tâche avec succès ; la sauvegarde reste restaurable |
Cache de session, verrous de fichiers |
| ☐ | Observation des coûts | La console du provider affiche une consommation de tokens attendue ; plafond de dépenses défini si supporté | Modèle surdimensionné, boucle d'outils |
| ☐ | Limite de permissions | L'agent n'a pas lu ~/.hermes/.env ou ~/.ssh ; commandes dangereuses ont déclenché une approbation manuelle |
Config outils, mode d'approbation |
6. Checklist dépannage : recherche par couches — réinstallation en dernier
Quand quelque chose casse, descendez couche par couche. La plupart des cas « installé mais cassé » viennent du PATH, des clés ou du cwd — pas d'une installation Hermes corrompue.
| Couche | Symptôme | Vérifier d'abord | Correctif courant |
|---|---|---|---|
| Dépendances | hermes: command not found |
PATH, ~/.local/bin |
source ~/.zshrc |
| Réseau | Timeout install/modèle | curl GitHub, API provider | Proxy, DNS, autre réseau |
| Clé | API key not set |
Noms de variables ~/.hermes/.env |
hermes model ou hermes config set |
| Provider | 401/429/5xx | Statut provider, solde, ID modèle | Changer de modèle, définir des limites, réessayer plus tard |
| Permissions | Impossible d'écrire / commande refusée | cwd, file d'approbation, TCC macOS | Approuver la commande, corriger le chemin workspace |
| Chemins | Config introuvable | HERMES_HOME, conflit multi-utilisateur |
Unifier HERMES_HOME ou compte dédié |
| Journaux | Échec silencieux | ~/.hermes/logs/, errors.log |
Corriger la config à partir des mots-clés des logs |
| Service arrière-plan | Gateway ne répond pas | Statut launchd, jeton, liste blanche | Sous-commandes hermes gateway, doc gateway officielle |
7. Checklist après validation : avant les vrais workflows
- ☐ Sauvegarder à nouveau
~/.hermes/(config, skills ; sessions si nécessaire) - ☐ Confirmer que
approvals.modereste manual ou conforme à la politique d'équipe - ☐ Si Gateway activée : liste blanche / appairage DM configurés ; pas de
GATEWAY_ALLOW_ALL_USERS - ☐ Définir plafonds de dépenses et alertes dans la console du provider
- ☐ Relire manuellement la qualité de outbox avant de lier un vrai dépôt
- ☐ Lire la doc Security officielle avant d'étendre outils ou backend terminal
Une fois chaque étape validée, étendez vers Telegram Gateway, Cron ou intégration CI. Pour resserrer davantage les limites de permissions et de clés sur Mac, consultez notre guide sécurité Hermes Agent sur Mac.
Faire tourner Hermes sur Mac mini pour une validation plus propre
Hermes Agent repose sur Git, Python, Node et les outils terminal Unix — tous natifs sur macOS, sans WSL ni galère de pilotes. Faire tourner l'agent sur un Mac mini dédié isole les essais CLI, Gateway et journaux de votre MacBook quotidien ; la mémoire unifiée Apple Silicon aide le routage Ollama local, et Gatekeeper, SIP et FileVault ajoutent une intégrité au niveau système.
Le Mac mini M4 consomme environ 4 W au repos, tourne sans ventilateur et en silence, et convient à un nœud agent 24/7 ; couplé à hermes gateway install via launchd, les services reprennent après redémarrage. Si vous suivez cette checklist, le Mac mini M4 est l'un des hôtes dédiés au meilleur rapport qualité-prix — procurez-vous-en un maintenant et validez chaque étape sur du matériel stable.