2026 — Guide complet d'installation et de configuration Hermes Agent : tutoriel pas à pas de zéro à la mise en service

2. Ce que la plupart des tutoriels oublient

1. Le plafond : « démarrage réussi ». Une bannière de bienvenue dans le terminal ne prouve pas que le modèle est joignable, que les outils fichiers fonctionnent ou qu'une passerelle reçoit des messages. Hermes n'est vraiment utilisable qu'après contrôle d'environnement, connectivité modèle, limites de permissions, journaux traçables et acceptation d'un cas à faible risque.
2. Coût caché : clés et chemins éparpillés. Les clés API ne vivent que dans des notes ; config.yaml et .env divergent ; le workspace pointe vers tout le répertoire personnel — une erreur peut réécrire des clés SSH ou un dépôt de production.
3. Stabilité et audit : installer puis oublier où sont les journaux. En cas de panne, les réinstallations à l'aveugle effacent les indices dans ~/.hermes/logs/errors.log ; sans sauvegarde, impossible de revenir en arrière après une mise à jour.

3. Préparation avant installation : checklist Mac et environnement

Objectif : éviter de découvrir un problème réseau, Git ou disque en plein milieu de l'installation. Critère de réussite : chaque point ci-dessous est coché avant de lancer le script d'installation.

• Système : macOS 12+ (Intel ou Apple Silicon ; Apple Silicon offre plus d'options d'inférence locale, mais les modèles cloud suivent toujours la doc de chaque fournisseur).
• Git : l'installateur officiel via git n'exige que Git comme prérequis dur (git --version ≥ 2.30 recommandé). Sans Git, installez d'abord Xcode Command Line Tools ou brew install git.
• Réseau : accès à GitHub raw (script d'installation) et à l'API du fournisseur LLM choisi ; définissez HTTPS_PROXY tôt en environnement proxy d'entreprise.
• Disque : l'installation officielle tire Python 3.11, Node.js v22, ripgrep, ffmpeg et le dépôt — réservez ≥ 2 Go libres (plutôt 1,5–3 Go avec le cache Skills ; suivez la doc actuelle).
• Permissions : l'installation par utilisateur ne nécessite pas sudo ; si vous avez déjà installé en root, les données peuvent être sous /root/.hermes, pas sous les chemins décrits ici.
• Sauvegarde : si un ancien ~/.hermes existe, lancez d'abord cp -a ~/.hermes ~/.hermes.bak-$(date +%F).
• Répertoire de test : créez un workspace isolé (nous utilisons ~/hermes-lab partout). Ne pointez pas le premier cas vers ~/Documents, des dépôts git de production ou des dossiers contenant des secrets.

# Auto-contrôle rapide avant installation (copier-coller)
git --version
sw_vers
df -h ~
mkdir -p ~/hermes-lab/{inbox,outbox,archive}
echo "Exemple lab Hermes : notes de planification T2." > ~/hermes-lab/inbox/sample.txt

Si échec, vérifier : erreurs Git → CLT/Homebrew ; disque faible → vider Téléchargements ou autre volume ; timeout réseau → changer de réseau ou miroir — ne réinstallez pas trois fois sans comprendre pourquoi.

4. Installation officielle d'Hermes Agent

Objectif : utiliser l'installateur maintenu par Nous Research pour que Python, Node et la CLI soient gérés pour vous. Source : documentation officielle Installation (revérifiez numéros de version et options avant publication).

4.1 Recommandé : installation git en une ligne (suit main)

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

L'installateur configure automatiquement uv, Python 3.11, Node.js v22, ripgrep, ffmpeg, clone le dépôt, crée un venv et ajoute hermes au PATH. Disposition typique par utilisateur :

• Code : ~/.hermes/hermes-agent/
• Données et config : ~/.hermes/ (surcharge via HERMES_HOME)
• CLI : ~/.local/bin/hermes

4.2 Alternative : pip install (Python 3.11+ déjà présent)

pip install hermes-agent
hermes postinstall   # optional: Node, browser, ripgrep, ffmpeg + setup

PyPI suit les versions taguées ; pour la pointe, préférez le script git ci-dessus. hermes update se comporte différemment selon la méthode — faites confiance à hermes doctor.

4.3 Trois actions obligatoires après installation

source ~/.zshrc          # ou ouvrir une nouvelle fenêtre terminal
hermes version           # noter la version pour le dépannage futur
hermes doctor            # diagnostic auto ; ajouter --fix pour tenter des réparations

Critère de réussite : which hermes pointe vers ~/.local/bin/hermes ; hermes doctor sans FAIL bloquant. Si échec, vérifier : 20 dernières lignes du journal d'installation → PATH → si vous avez invoqué le hermes brut du dépôt avec le Python système (utilisez le lanceur venv).

À éviter : supprimer ~/.hermes et réinstaller immédiatement — sauvegardez d'abord la sortie terminal et hermes doctor, sinon réseau et permissions se confondent.

5. Configurer modèles et clés API

Objectif : permettre à Hermes d'appeler votre fournisseur LLM. Critère de réussite : test fumée non interactif avec réponse cohérente ; hermes auth list ou .env contient l'entrée et la clé n'est pas en clair dans l'historique shell.

5.1 Configuration interactive (recommandée la première fois)

hermes setup          # full wizard: models, tools, gateway, etc.
# or step by step:
hermes model          # pick provider and default model
hermes tools          # enable tool sets as needed

5.2 Variables d'environnement et fichiers de config

La config principale est en général dans ~/.hermes/config.yaml ; les secrets dans ~/.hermes/.env (confirmez avec hermes config path et hermes config env-path). Exemple (noms de variables selon la doc actuelle du fournisseur — ne copiez pas d'anciens noms) :

# Example: OpenRouter (replace with your key; never commit to git)
hermes config set OPENROUTER_API_KEY "sk-or-v1-xxxxxxxx"

# or edit .env directly (chmod 600 ~/.hermes/.env)
echo 'OPENROUTER_API_KEY=sk-or-v1-xxxxxxxx' >> ~/.hermes/.env

Limite : tarifs, quotas API, disponibilité régionale et politiques de confidentialité évoluent — lisez les conditions actuelles avant la production. Cet article ne vous enferme pas dans un seul nom de modèle.

6. Workspace, permissions et journaux

Objectif : après installation, rendre les opérations traçables, bornées et réversibles. Principe : moindre privilège — n'autoriser d'abord que le répertoire de test, puis ouvrir progressivement les projets réels.

• Workspace : définir ~/hermes-lab dans config.yaml ou la session ; y ajouter AGENTS.md décrivant outils autorisés et limites (voir la doc officielle Context Files).
• Permissions macOS : les outils terminal/fichiers peuvent demander l'accès complet au disque — lors de la première acceptation, n'accordez que ce qu'exige le répertoire de test, pas tout le disque.
• Journaux : par défaut ~/.hermes/logs/ (agent.log, errors.log, gateway.log). Inspecter avec hermes logs list, hermes logs errors --since 30m.
• Hygiène des secrets : chmod 600 ~/.hermes/.env ; pas de zip de sauvegarde dans des dossiers synchronisés ; ne jamais laisser l'agent lire ~/.ssh, des données de paiement ou un kubeconfig de production.
• Exécution en arrière-plan (optionnel) : pour les passerelles Telegram/Discord, hermes gateway setup et hermes gateway install ; l'exploitation longue durée est couverte dans notre guide de maintenance longue durée Hermes.

Critère de réussite : après avoir indiqué à l'agent « lecture/écriture uniquement dans ~/hermes-lab », les tentatives hors chemins de test sont refusées ou journalisées pour audit.

7. Acceptation au premier lancement : runbook en sept étapes

Ces sept étapes font passer de « configuration terminée » à « prêt pour l'exploitation » — exécutez-les telles quelles et conservez captures d'écran ou extraits de journaux.

1. Diagnostic : hermes doctor --fix → aucun FAIL non résolu.
2. Ping modèle : hermes chat -q "Réponds exactement : HERMES_OK" → la réponse contient HERMES_OK.
3. Lecture fichier : faire lire ~/hermes-lab/inbox/sample.txt et répéter la première phrase.
4. Écriture fichier : écrire ~/hermes-lab/outbox/ping.txt → visible avec cat.
5. Journaux : hermes logs errors --since 10m → pas de nouvel ERROR (ou éléments bénins documentés).
6. Fermer le terminal : quitter la fenêtre, en ouvrir une nouvelle, refaire l'étape 2 → écarte un PATH valide seulement dans la session courante.
7. Redémarrage optionnel : redémarrer le Mac et refaire l'étape 2 (si passerelle installée, ajouter hermes gateway status).

Seuils de référence (acceptation personnelle, pas un SLA officiel) : réponse fumée < 60 s ; 0 ligne ERROR inexpliquée dans errors.log sur 10 min ; après écriture de test, ls -la ~/hermes-lab/outbox affiche le nouveau fichier.

8. Premier cas pratique : résumé + tâches + sortie réversible

Scénario : lire un texte d'exemple dans le répertoire de test, produire un résumé en français et trois tâches, écrire une sortie Markdown et conserver une copie pour retour arrière. Ce cas couvre le résultat d'installation (CLI), le résultat de configuration (modèle) et un workflow réel (lire → raisonner → écrire → journaux).

# 1. Préparer l'entrée (ignorer si la section 3 l'a déjà créée)
cat > ~/hermes-lab/inbox/weekly-notes.txt <<'EOF'
Cette semaine : brouillon du guide d'installation Hermes terminé.
Suivis : configurer les alertes budget OpenRouter ; évaluer la passerelle Telegram la semaine prochaine.
Risque : ne jamais committer de clés API dans git.
EOF

# 2. Session interactive (ou une instruction composée)
hermes
# Dans la session, envoyer (exemple de prompt) :
# "N'utilise que le répertoire ~/hermes-lab. Lis inbox/weekly-notes.txt,
#   rédige un résumé de moins de 150 mots plus 3 tâches en français,
#   enregistre dans outbox/summary-and-todos.md,
#   et copie le fichier original vers archive/weekly-notes.bak"

# 3. Vérification non interactive
ls -la ~/hermes-lab/outbox/summary-and-todos.md
ls -la ~/hermes-lab/archive/
hermes logs agent -n 30 --since 15m

Critères de réussite :

• summary-and-todos.md contient un résumé et trois tâches cohérents avec le fichier source.
• archive/ contient une sauvegarde utilisable pour un diff.
• Les journaux montrent les appels d'outils correspondants ; la facturation/tableau de bord du fournisseur reflète cette exécution (vérifie le coût).

Retour arrière : rm ~/hermes-lab/outbox/summary-and-todos.md && cp ~/hermes-lab/archive/weekly-notes.bak ~/hermes-lab/inbox/weekly-notes.txt. Si échec, vérifier : modèle a tronqué le fichier → permission refusée sur outbox → erreurs outils dans errors.log.

9. Dépannage : couche par couche, éviter les réinstallations à l'aveugle

Checklist de faits avant publication (mainteneurs) : URL install.sh officielle, macOS minimum, noms de répertoires par défaut, sous-commandes CLI, variables d'environnement fournisseur, chemins de journaux — mettre à jour l'article si quelque chose change. Pour les lecteurs : en cas d'erreur, lancer hermes doctor, lire errors.log, puis seulement envisager une réinstallation.

10. Étapes suivantes : du répertoire de test aux workflows réels

Une fois l'acceptation validée, étendez dans cet ordre — ne sautez pas directement aux dépôts de production ou aux systèmes de paiement :

1. Ajoutez un répertoire de side-project réel à la liste autorisée ; bloquez toujours ~/.ssh et la lecture/écriture globale *.
2. Activez hermes cron pour des tâches quotidiennes à faible risque (ex. inventaire Téléchargements — toujours limité aux dossiers de test).
3. Configurez une passerelle messagerie (Telegram/Discord) en mode appairage pour bloquer les inconnus (voir la doc Security officielle).
4. Établissez un rythme hebdomadaire hermes backup --quick, puis lisez le guide de maintenance longue durée pour les exercices de mise à jour et retour arrière.