2026 Hermes Agent : guide d'installation complet — macOS, Linux, VPS en un clic + Gateway Telegram 24h/24

Hermes Agent, édité par Nous Research, est une plateforme d'agents sous licence MIT qui se place entre une interface terminal et une gateway multicanal. Un processus central peut servir Telegram, Discord, Slack, WhatsApp, Signal et des sessions CLI tout en partageant la même pile mémoire : contexte de session éphémère, documents de skills durables distillés après des tâches difficiles, et modèle utilisateur persistant en Markdown plus recherche épisodique SQLite FTS5. L'appel d'outils, les sous-agents, la planification de type cron et les serveurs MCP optionnels étendent le runtime sans dupliquer le stockage mémoire.

Réussir l'installation n'est que la première porte. Les utilisateurs écrivent à votre bot depuis leur mobile ; ils attendent des réponses qui s'appuient sur des décisions passées, pas un redémarrage à froid chaque matin. Cela suppose un hôte où state.db, les dossiers de skills et les webhooks de gateway survivent aux reboots et aux mises à jour système. Un MacBook de développement convient pour les étapes ci-dessous ; y faire transiter la production Telegram d'un portable qui dort ne convient pas. Les équipes qui dépassent l'hébergement hobby migrent souvent la même archive de configuration vers un Mac cloud dédié ou un VPS toujours allumé une fois la boucle d'apprentissage prouvée.

Cet article suppose un accès shell, HTTPS sortant et le droit de stocker des clés API sur disque. Hermes prend en charge plus de 200 modèles via OpenRouter, Nous Portal, des endpoints compatibles OpenAI et d'autres fournisseurs documentés en amont. Choisissez un fournisseur avant l'installation afin de valider le chemin complet en une seule session.

La plupart des tickets d'installation ne viennent pas d'un curl cassé. Ils viennent d'hôtes inadaptés, de dépendances manquantes ou de clés rangées au mauvais endroit. Le tableau ci-dessous aligne les attentes par plateforme avec ce dont Hermes a réellement besoin pour une gateway Telegram stable.

• Python et dépendances Node : L'installateur officiel tire les runtimes nécessaires. Sur des images VPS minimales, installez les outils de compilation et vérifiez curl, git et un python3 fonctionnel avant de lancer le script.
• Utilisateur Unix dédié : Exécutez Hermes sous un compte non root avec un répertoire home fixe. Mélanger l'état de la gateway avec root ou des comptes partagés complique les permissions de tokens et les sauvegardes.
• Disposition disque : Prévoyez de l'espace séparé pour state.db, l'arborescence des skills et les logs. Un volume racine de 20 Go se remplit vite une fois la recherche épisodique et la distillation de skills tournent plusieurs semaines.
• Réseau : Telegram exige un HTTPS sortant stable et, en mode webhook, un endpoint joignable ou un repli long-polling documenté dans la config gateway. La NAT domestique et la NAT opérateur sur des pools VPS bon marché produisent le schéma classique « ça marche sur mon Mac, mort sur le VPS ».
• Hygiène des secrets : Ne commitez jamais les tokens BotFather ni les clés LLM. Stockez-les dans des fichiers en mode 600 hors git et référencez uniquement les chemins depuis la configuration gateway.

Lancez hermes doctor après l'installation pour faire remonter les dépendances manquantes avant d'accuser Telegram. Corriger la dérive d'environnement en amont évite des heures d'archéologie de logs gateway.

L'installateur amont est identique sur macOS et Linux. Sur un VPS, seule la façon de vous connecter en SSH et le propriétaire du home changent. Suivez ces six étapes dans l'ordre ; elles reflètent ce que nous appliquons sur des instances NUKCLOUD neuves et des images Ubuntu vierges.

1. 01
   Préparer l'hôte : Sur macOS, confirmez les Xcode Command Line Tools ou acceptez l'invite d'installation. Sur un VPS Ubuntu ou Debian, exécutez sudo apt update && sudo apt install -y curl git python3 python3-venv build-essential. Créez un utilisateur dédié tel que hermes avec un home sur disque persistant, pas sur tmpfs.
2. 02
   Lancer l'installateur officiel : Sous cet utilisateur, exécutez le script d'installation en une ligne de Nous Research. Attendez la fin ; le script place le CLI sur le PATH et initialise les répertoires de configuration par défaut. Épinglez la release testée plutôt que de suivre la branche principale sur une gateway de production.
3. 03
   Vérifier binaire et version : Exécutez hermes --version et confirmez que le CLI répond. Si le shell ne trouve pas le binaire, reconnectez-vous pour appliquer le PATH du profil, ou sourcez le fragment que l'installateur affiche.
4. 04
   Diagnostics de santé : Lancez hermes doctor et traitez chaque avertissement avant de configurer les modèles. Doctor contrôle les paquets Python, les permissions disque et les prérequis gateway. Sauter cette étape est le chemin le plus court vers un bot Telegram qui s'installe mais ne reste jamais en ligne.
5. 05
   Démarrer le TUI une fois en interactif : Lancez hermes tui en SSH avec pseudo-TTY. Confirmez que l'interface terminal charge, accepte le clavier et atteint le réseau. Cela prouve le runtime avant de passer en daemon.
6. 06
   Capturer la baseline : Notez la version mineure macOS ou /etc/os-release, le fuseau horaire, le chemin d'install et le listing des dossiers config et mémoire. Archivez cet arbre en tarball avant l'arrivée du trafic Telegram pour pouvoir restaurer si une mauvaise mise à jour corrompt les index FTS5.

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

Sur un VPS neuf, provisionnez d'abord via le panneau fournisseur, attachez les clés SSH, durcissez sshd, puis seulement lancez l'installateur. Si vous dimensionnez une SKU de production, utilisez la page Commander pour choisir RAM et disque avant l'install afin que SQLite et les skills ne partagent pas un volume racine étriqué avec les snapshots OS.

Hermes sans endpoint modèle est une gateway vide. La configuration vit dans des YAML et fichiers d'environnement sous le répertoire home Hermes ; les noms exacts évoluent avec les releases, donc traitez la documentation amont comme source de vérité et gardez votre version épinglée en favori.

Configuration fournisseur : Exportez votre clé API dans un fichier restreint, par exemple ~/.hermes/secrets/openrouter.env en mode 600, puis référencez-le depuis le bloc fournisseur. OpenRouter est le défaut courant pour l'accès multi-modèles ; Nous Portal et les URL de base compatibles OpenAI conviennent aux équipes avec contrats existants. Fixez un slug de modèle par défaut aligné sur budget et latence. Évitez de changer de fournisseur sur une gateway live sans sauvegarder state.db et les dossiers skills au préalable.

Chemins mémoire : Confirmez que MEMORY.md, USER.md et les dossiers skills sont sur des volumes persistants. Sur Docker ou des images VPS éphémères, montez explicitement ces chemins ou vous perdrez la mémoire composée à chaque recréation de conteneur.

Validation CLI : Depuis le TUI ou le mode CLI one-shot, envoyez une invite qui exige un outil ou une écriture mémoire, puis une relance en nouvelle session qui devrait rappeler le fait. Si le rappel échoue après un reboot contrôlé, corrigez la persistance disque avant d'ouvrir Telegram aux humains.

export OPENROUTER_API_KEY="sk-or-v1-xxxxxxxx"
export HERMES_DEFAULT_MODEL="anthropic/claude-sonnet-4"

Relancez hermes doctor après modification de la config fournisseur. La sortie Doctor est le signal le plus rapide que votre clé est visible dans le même contexte utilisateur qui exécutera le daemon gateway.

Telegram est la première gateway demandée parce que BotFather est rapide et les clients mobiles sont partout. Traitez la gestion des tokens comme du travail de sécurité production, pas comme un raccourci de démo.

Parcours BotFather : Dans Telegram, ouvrez @BotFather, lancez /newbot, choisissez un nom d'affichage et un identifiant se terminant par bot, puis copiez le token API HTTP. Stockez-le dans un fichier mode 600 tel que ~/.hermes/secrets/telegram.token. Référencez ce chemin depuis le bloc de configuration gateway Telegram Hermes ; ne collez pas les tokens dans l'historique shell ni dans des dotfiles versionnés.

Démarrage gateway : Utilisez la sous-commande gateway Telegram documentée par Hermes, en général après chargement de l'env fournisseur. Testez avec un message direct au bot avant de l'ajouter à des groupes. Le mode groupe peut exiger d'ajuster la confidentialité via BotFather selon que le bot doit lire tous les messages.

Persistance macOS avec launchd : Créez un plist LaunchAgent qui charge votre fichier env secrets, définit WorkingDirectory sur le home Hermes et lance le binaire gateway avec KeepAlive à true. Chargez avec launchctl bootstrap sous l'utilisateur dédié. Vérifiez avec launchctl print après reboot.

Persistance VPS Linux avec systemd : Créez une unité user systemd avec EnvironmentFile pointant vers vos secrets, Restart=on-failure et WantedBy=multi-user.target ou lingering user activé. Activez le lingering pour l'utilisateur Hermes afin que la gateway survive à la déconnexion SSH : loginctl enable-linger hermes.

[Unit]
Description=Hermes Telegram Gateway
After=network-online.target

[Service]
EnvironmentFile=%h/.hermes/secrets/openrouter.env
EnvironmentFile=%h/.hermes/secrets/telegram.env
ExecStart=%h/.local/bin/hermes gateway telegram
Restart=on-failure
RestartSec=10

[Install]
WantedBy=default.target

Accès admin : Atteignez le TUI en SSH avec forwarding de port ; n'exposez jamais les ports de gestion sur Internet public. Surveillez la croissance des logs, les redémarrages gateway et les erreurs webhook ou long-poll Telegram quotidiennement la première semaine. Après sept jours d'uptime stable, planifiez des sauvegardes tarball hebdomadaires de state.db et des arbres skills.

Aide-mémoire ops jour deux : hermes --version pour la dérive, hermes doctor après upgrade, hermes tui pour le debug interactif, logs gateway via journalctl --user -u hermes-telegram.service sur Linux ou filtres log show --predicate sur macOS. Épinglez-les dans votre runbook à côté des contacts d'astreinte.

L'installateur est volontairement multi-plateforme ; le choix d'hébergement détermine si les utilisateurs Telegram remarquent des trous. Les pools VPS mutualisés séduisent avec des étiquettes à cinq dollars, mais la gigue de bande passante, les CPU sursouscrits et les sessions long-polling cassées apparaissent exactement quand votre modèle utilisateur commence à paraître intelligent. Les Mac Mini à la maison fonctionnent si vous maîtrisez l'alimentation et le FAI ; les équipes entreprise préfèrent souvent un Mac cloud ou un VPS durci avec frontières locataire documentées.

Pour les équipes qui veulent une mémoire Hermes composée sans acheter du matériel avant validation, un Mac cloud compté chez NUKCLOUD préserve la trésorerie pendant que vous mesurez la qualité de rappel et la charge support. Les offres macOS VPS au pool minute sur-vendent souvent le CPU et laissent tomber les gateways pendant les jobs de résumé. Quand Telegram est orienté production, un disque stable, un réseau sortant prévisible et un hôte qui survit aux reboots comptent plus qu'économiser dix euros par mois sur un pool sursouscrit.