Hermes Agent, c'est l'agent IA autonome open-source de Nous Research — un agent qui vit là où vous l'installez (poste local, VPS à 5 €, cluster GPU ou infra serverless), qui apprend au fil de l'usage, qui crée ses propres compétences (skills) après avoir résolu une tâche complexe et qui reste joignable depuis Telegram, WhatsApp, Discord, Slack, Signal ou email — le tout via une seule licence MIT.
Ce tuto est un guide vendor-neutre : les commandes viennent du README officiel du dépôt GitHub et de la documentation officielle. Rien n'y est inventé. À la fin, vous aurez un agent d'accueil client fonctionnel sur Telegram — et vous saurez comment le sécuriser sérieusement.
Ce n'est pas
Hermes Agent n'est ni un copilote d'IDE, ni un wrapper autour d'une seule API cloud, ni un simple chatbot. C'est un agent autonome qui gagne en capacité au fil du temps grâce à une boucle d'apprentissage native (skills auto-créées, mémoire persistante, modèle utilisateur qui s'affine session après session).
Vocabulaire indispensable
Avant d'installer quoi que ce soit, alignons le vocabulaire. Sans ces bases, la documentation officielle est confuse au premier passage.
| Terme | Ce que ça veut dire concrètement |
|---|---|
| Assistant vs agent | Un assistant comprend et répond. Un agent exécute des actions (agenda, CRM, envoi d'emails, appels d'API). Hermes est un agent. |
| SOUL.md | Fichier Markdown qui définit la personnalité de l'agent : ton, règles de conversation, limites. C'est le premier fichier que vous écrivez et le plus important. |
| Skill | Compétence procédurale que l'agent crée automatiquement après une tâche complexe — puis qu'il ré-utilise et améliore au fil de l'usage. Vit dans ~/.hermes/skills/. |
| Mémoire persistante | MEMORY.md (mémoire générale) et USER.md (modèle utilisateur). Persiste entre les sessions. |
| Gateway | Processus qui connecte l'agent aux messageries (Telegram, WhatsApp, Discord, etc.). Un seul gateway pilote tous les canaux. |
| Sub-agent | Sous-agent isolé qu'Hermes peut spawn pour paralléliser un workstream (sans consommer de contexte dans la session principale). |
| MCP | Model Context Protocol — standard pour connecter des serveurs d'outils tiers à Hermes. Extension propre du périmètre sans hacker le core. |
| Tool Gateway (Nous Portal) | Bouquet de 4 outils gérés (web search, image generation, TTS, browser) accessible par OAuth via hermes setup --portal. |
| Provider | Fournisseur de modèle LLM. Anthropic, OpenAI, OpenRouter, Ollama (local), ElevenLabs (TTS), Nous Portal. |
Choisir son infrastructure
Réponse directe. Pour la majorité des cas TPE/PME, un VPS Linux à 5-10 €/mois (Hetzner, OVH, Scaleway) suffit largement. Hermes tourne bien avec 1 vCPU et 2 Go de RAM tant que le modèle LLM reste distant (cloud).
Machine locale (Linux/macOS/WSL2/Windows natif)
Gratuit, zéro dépendance externe. Idéal pour tester. Contrainte : l'agent ne tourne que quand la machine est allumée, donc les tâches cron programmées la nuit ne s'exécutent pas.
VPS à 5-10 €/mois — recommandé pour la prod
Hermes tourne en continu, le gateway messagerie reste joignable, le cron scheduler s'exécute même la nuit. Sauvegardez ~/.hermes/ régulièrement.
Serverless (Daytona, Modal, etc.)
Coût quasi nul quand l'agent est idle. Plus complexe à mettre en place — réservé si vous avez déjà des workflows serverless. Voir la doc officielle pour les intégrations concrètes.
Choisir son fournisseur de modèle LLM
| Provider | Coût tokens | Confidentialité | Notes |
|---|---|---|---|
| OpenRouter | Multi-modèles à la carte, pay-as-you-go | Dépend du modèle sélectionné | Pratique pour tester plusieurs modèles rapidement. |
| Anthropic (Claude) | Facturation directe Anthropic | DPA disponible | Excellent sur les tâches longues et agentiques. |
| OpenAI (GPT) | Facturation directe OpenAI | DPA disponible | Modèles multimodaux, très bon écosystème d'outils. |
| Ollama (local) | Gratuit en tokens | 100 % local — aucune donnée sortante | Nécessite du CPU/GPU. Idéal pour un déploiement RGPD strict. |
| Nous Portal | OAuth clé en main | Passe par l'infra Nous Research | Setup ultra-rapide via hermes setup --portal. |
Contexte suffisant, sinon troncature
Prévoyez un modèle avec une grande fenêtre de contexte (idéalement 100 k tokens ou plus). Sinon vos sessions sont tronquées au milieu d'une tâche longue et l'agent perd le fil. Claude Sonnet 4+, GPT-4.1+ et les modèles récents d'OpenRouter sont confortables sur ce critère.
Installer Hermes Agent en une commande
Réponse directe. Une seule ligne de commande, selon votre OS. Les deux one-liners ci-dessous sont pris verbatim de la documentation officielle.
Linux, macOS, WSL2, Android (Termux)
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
Windows natif (PowerShell)
iex (irm https://hermes-agent.nousresearch.com/install.ps1)
L'installateur télécharge et met en place uv (le gestionnaire de paquets Python d'Astral), Python 3.11 dans un venv isolé, Node.js, ripgrep, ffmpeg, et sur Windows un Git Bash portable (MinGit) — le tout dans %LOCALAPPDATA%\hermes\ sans admin.
Le répertoire principal ($HERMES_HOME) est :
- Linux / macOS / WSL2 →
~/.hermes/ - Windows natif →
%LOCALAPPDATA%\hermes\
Windows Defender qui bloque uv.exe : c'est un faux positif
Certains antivirus (Windows Defender, Bitdefender) flag uv.exe comme un malware. C'est une détection heuristique erronée sur un binaire Rust non signé. La documentation officielle propose une vérification cryptographique via gh attestation verify. Whitelistez le dossier %LOCALAPPDATA%\hermes\bin\, pas le hash — Hermes met à jour uv et le hash change à chaque version.
Lancer le setup wizard
hermes setup
Ce wizard interactif vous demande de choisir un provider, un modèle, les tools activés et éventuellement une messagerie. Il détecte aussi automatiquement un dossier ~/.openclaw et propose une migration (voir plus bas).
Raccourci — si vous voulez le chemin le plus court vers un agent qui parle :
hermes setup --portal
Cette variante déclenche une connexion OAuth avec Nous Portal qui vous donne accès à un modèle plus les quatre outils gérés (web search, image generation, TTS, browser) en une seule authentification.
Premier démarrage — la TUI
Une fois le setup terminé :
hermes
Vous êtes dans la TUI (Terminal User Interface) et vous pouvez commencer à parler à l'agent. Quelques slash commands utiles dès le premier jour :
| Commande | À quoi ça sert |
|---|---|
/new ou /reset | Démarrer une nouvelle conversation |
/model claude:sonnet-4 | Changer de modèle sans quitter la TUI |
/personality [nom] | Charger une personnalité alternative |
/skills | Lister les skills disponibles |
/usage | Voir la consommation de tokens |
/compress | Compresser le contexte de la session |
/insights --days 7 | Résumé LLM des sessions des 7 derniers jours |
/stop | Interrompre la tâche en cours |
Toute la personnalité et la mémoire vivent maintenant sous $HERMES_HOME. Sauvegardez ce dossier — c'est votre agent.
Écrire son SOUL.md — le fichier de personnalité
Réponse directe. SOUL.md est un fichier Markdown que vous rédigez à la main pour définir le ton, les règles de conversation et les limites de l'agent. C'est le fichier le plus important du système.
Fil rouge du tuto : un agent d'accueil client pour une TPE qui qualifie les demandes entrantes et propose un rendez-vous. Voici un SOUL.md minimal mais fonctionnel :
# SOUL.md — Agent d'accueil "MAG&Cie"
## Rôle
Tu es l'agent d'accueil de MAG&Cie, cabinet de conseil technologique à Nantes.
Ton objectif est de :
1. Comprendre la demande du visiteur en 2 à 3 messages max.
2. Qualifier son besoin (TPE / PME, sujet : cyber, IA, dev, autre).
3. Proposer un rendez-vous découverte gratuit ou renvoyer vers la ressource pertinente.
## Ton et style
- Chaleureux mais direct, jamais pompeux.
- Français par défaut, tutoiement uniquement si le visiteur tutoie en premier.
- Phrases courtes. Zéro jargon inutile.
- Emojis : maximum un par message, seulement si ça ajoute quelque chose.
## Règles
- Ne jamais promettre de délais ni de tarifs. Renvoyer vers l'équipe MAG&Cie pour tout devis.
- Ne jamais deviner : si tu ne sais pas, tu le dis et tu proposes le contact humain.
- Les données visiteur ne sont utilisées que pour la conversation en cours.
## Ressources à disposition
- Page contact : https://www.mag-cie.com/fr/contact/
- Prise de RDV : https://www.mag-cie.com/fr/rendez-vous/
- Assistants IA : https://www.mag-cie.com/fr/assistants-ia/
- Audit cyber : https://www.mag-cie.com/fr/audit-cybersecurite/
Placez ce fichier à la racine de $HERMES_HOME/. Hermes le charge automatiquement au démarrage. Vous pouvez aussi créer plusieurs personnalités et basculer via /personality [nom].
Bonne pratique — le SOUL.md court gagne
Un SOUL.md long finit par diluer les consignes clés. Restez sous 150-200 lignes au total. Si vous devez ajouter des règles, découpez en fichiers de contexte séparés (voir le concept de context files dans la doc officielle).
Connecter Telegram, pas à pas
C'est la section la plus recherchée. On y va calmement.
Créer un bot Telegram via BotFather
Dans Telegram, cherchez @BotFather et démarrez une conversation. Envoyez /newbot, donnez un nom d'affichage puis un identifiant unique se terminant par _bot. BotFather vous renvoie un HTTP API token — c'est le secret à protéger.
Lancer le setup du gateway côté Hermes
Dans votre terminal : hermes gateway setup. Sélectionnez Telegram, collez le token quand demandé. Hermes le stocke dans sa configuration chiffrée (ne jamais le mettre dans un fichier committé).
Démarrer le gateway en arrière-plan
hermes gateway start. Le process reste ouvert et écoute les messages entrants. Sur un VPS, lancez-le sous systemd ou tmux pour qu'il survive à la déconnexion SSH.
Envoyer le premier message au bot
Ouvrez votre bot dans Telegram, écrivez « bonjour ». L'agent répond selon le SOUL.md que vous avez défini. Testez ensuite les slash commands : /model, /skills, /usage, /stop.
Ne jamais commiter le token du bot
Le token BotFather donne un contrôle total sur votre bot. Si vous le committez sur GitHub, il est aspiré par des bots en quelques minutes et votre agent peut devenir vecteur de spam. Toujours le stocker en variable d'environnement ou dans un coffre (1Password, Bitwarden, Vault, age, sops).
Autres messageries — même mécanique
Le gateway pilote plusieurs canaux depuis un seul processus : Discord, Slack, WhatsApp, Signal, Email, Home Assistant, Teams. Chacun a ses propres étapes de setup (documentées dans le guide Messaging Gateway officiel), mais le pattern reste hermes gateway setup → suivre les instructions → hermes gateway start.
Skills et mémoire — la boucle d'apprentissage
Réponse directe. Hermes crée automatiquement des skills après avoir résolu une tâche complexe et les auto-améliore au fil de l'usage. C'est le cœur du positionnement « self-improving agent » revendiqué par Nous Research.
- Skills (
~/.hermes/skills/) : mémoire procédurale. Réutilisées automatiquement quand une situation similaire se présente. Vous pouvez aussi en écrire manuellement — le format est documenté sur agentskills.io, le standard ouvert que Hermes suit. - Mémoire générale (
MEMORY.md) : faits durables. Hermes s'auto-nudge pour persister ce qui doit l'être. - Modèle utilisateur (
USER.md) : Hermes construit progressivement une représentation de qui vous êtes (modèle dialectique via Honcho). Cette compréhension s'affine session après session. - Recherche cross-session : full-text search FTS5 sur toutes les conversations passées, avec résumé LLM à la demande.
Pour écrire une skill manuellement, créez un fichier .md dans ~/.hermes/skills/ en respectant le format documenté. Chaque skill a un nom, une description d'usage et des instructions procédurales que l'agent applique quand la description matche la situation courante.
Automatiser — le cron scheduler
Réponse directe. Hermes embarque un cron scheduler natif qui exécute des tâches récurrentes en langage naturel et livre le résultat sur n'importe quelle plateforme (Telegram, Discord, email…). Aucun outil externe requis.
Exemples réalistes pour une TPE :
- « Chaque lundi à 9 h, résume les emails clients reçus le week-end et envoie-moi la synthèse sur Telegram. »
- « Chaque nuit à 3 h, sauvegarde le contenu de
~/.hermes/sur mon stockage distant. » - « Chaque 1er du mois, vérifie que mes noms de domaine expirent dans plus de 30 jours et alerte-moi sinon. »
Configuration via hermes en session interactive : décrivez la tâche, Hermes crée l'entrée cron pour vous. Voir la documentation cron officielle pour la gestion (liste, désactivation, historique).
Étendre l'agent — l'intégration MCP
Hermes se connecte nativement à n'importe quel serveur MCP (Model Context Protocol) — le standard ouvert d'Anthropic pour brancher des outils tiers à un agent LLM. Concrètement : votre CRM, votre agenda, votre base de connaissances interne, votre système de tickets.
Deux mouvements possibles :
- Consommer un serveur MCP existant (par ex. Google Calendar, HubSpot, Notion). Voir la liste des serveurs MCP disponibles — l'intégration côté Hermes se fait en quelques lignes de configuration.
- Créer un serveur MCP sur-mesure pour vos outils métier. C'est précisément notre offre MAG&Cie de création MCP si vous voulez déléguer.
Sécurité — la section non négociable
Réponse directe. Un agent auto-hébergé qui peut envoyer des emails, appeler des APIs et exécuter des commandes shell est un atout stratégique et une surface d'attaque. Ce que vous ne sécurisez pas devient le canal d'accès du prochain incident. Cette section est la casquette RSSI de MAG&Cie — la plupart des tutos concurrents n'y consacrent pas trois lignes.
Command approval
Hermes propose nativement un système d'approbation de commandes : toute commande shell exécutée par l'agent peut nécessiter une confirmation humaine explicite. Activez-le sur les patterns dangereux (rm, curl | bash, tout ce qui modifie /etc ou sort du sandbox). Voir la doc Security → Command approval.
DM pairing
Sur les messageries, seuls les utilisateurs paired peuvent parler à l'agent. Le premier message d'un inconnu ne déclenche rien tant que l'appairage n'est pas explicitement approuvé. Activez-le dès le premier déploiement, ce n'est pas une option de confort.
Container isolation
Le dépôt fournit des docker-compose.yml prêts à l'emploi. Isolez l'agent dans un conteneur avec un utilisateur non-root, un système de fichiers en lecture seule sauf /tmp et $HERMES_HOME, et pas d'accès réseau vers l'intranet.
Prompt injection : moindre privilège
Un agent qui lit le web ou des emails peut recevoir des instructions malveillantes cachées dans le contenu qu'il ingère. Principe de base : n'activez que les tools strictement nécessaires. Un agent d'accueil client n'a pas besoin d'accès terminal, ni de lire vos emails, ni d'appeler votre CRM en écriture.
Secrets hors config
Toutes les clés API (LLM, Telegram, CRM…) doivent être en variables d'environnement ou dans un coffre (Vault, age, sops). Jamais en clair dans un fichier de config versionné. Vérifiez avec git secrets ou gitleaks avant le premier push.
Exposition réseau réduite
Le gateway n'a pas besoin d'être joignable depuis Internet — ce sont Telegram/Discord/etc. qui poussent les messages via long-polling ou webhooks. Si vous exposez malgré tout un port, mettez du TLS, une auth et un pare-feu qui limite les IP entrantes. Mises à jour régulières (hermes update) pour les correctifs de sécurité.
RGPD — où vivent les données ?
Toutes les données de conversation transitent par le fournisseur LLM que vous choisissez. Sous vos conditions contractuelles avec lui — pas celles de Nous Research (sauf si vous utilisez Nous Portal, auquel cas seule cette partie transite par leur infra). Pour un déploiement RGPD strict : préférez Ollama local (100 % on-premise) ou un provider avec DPA et localisation UE, appliquez la minimisation (ne pas laisser l'agent copier des données personnelles dans MEMORY.md sans nécessité) et documentez ce flux dans votre registre des traitements. Un audit cybersécurité MAG&Cie valide la conformité d'un déploiement existant.
Migrer depuis OpenClaw
Si vous venez d'OpenClaw, Hermes importe automatiquement l'essentiel :
hermes claw migrate # Migration interactive (preset complet)
hermes claw migrate --dry-run # Aperçu de ce qui sera migré, sans rien toucher
hermes claw migrate --preset user-data # Migration sans les secrets (clés API)
hermes claw migrate --overwrite # Écrase les fichiers en conflit
Ce qui est importé : SOUL.md, les mémoires (MEMORY.md, USER.md), les skills utilisateur, l'allowlist de commandes, la configuration des messageries, les clés API allowlistées (Telegram, OpenRouter, OpenAI, Anthropic, ElevenLabs) et les instructions workspace (AGENTS.md).
Les pièges les plus fréquents
1 — Modèle avec fenêtre de contexte trop petite
Sur les tâches longues, un modèle limité à 32k tokens tronque en cours de session et l'agent perd le fil. Choisissez un modèle 100k+ (Claude Sonnet 4+, GPT-4.1+, Gemini 2, DeepSeek Chat récent).
2 — Agent lancé en root
Sur un VPS, ne lancez jamais Hermes sous root. Créez un utilisateur dédié (useradd hermes-agent), donnez-lui les droits juste nécessaires, exécutez le gateway sous cet utilisateur.
3 — Oubli des mises à jour
Hermes évolue vite (v0.18.0 sortie le 1er juillet 2026). Lancez hermes update régulièrement, surveillez le dépôt GitHub, appliquez les correctifs de sécurité rapidement.
4 — Sur-permissionner les tools dès le départ
N'activez pas les 60+ tools intégrés d'un coup. Démarrez avec le strict nécessaire (envoi de message, lecture d'un doc). Ajoutez à la demande, un à un. Chaque tool activé est une surface d'attaque de plus.
5 — Gateway exposé sans authentification
Si vous ouvrez un port pour un webhook, mettez une authentification (secret partagé, mTLS) et un pare-feu qui restreint les IP sources. Un gateway exposé sans auth est un cheval de Troie potentiel.
6 — Antivirus qui bloque `uv.exe` en silence
Sur Windows, si l'installation échoue mystérieusement, vérifiez que Defender ou Bitdefender n'a pas mis uv.exe en quarantaine. Whitelistez le dossier %LOCALAPPDATA%\hermes\bin\, pas le hash.
Checklist de mise en production
Avant d'ouvrir votre agent à des utilisateurs réels :
Avant le go-live
- Installation vérifiée avec
hermes doctor— aucune erreur, aucun warning rouge. -
SOUL.mdrelu, testé sur une dizaine de scénarios plausibles + adversariaux. - Provider LLM configuré, clé API en variable d'environnement ou coffre (jamais en dur).
- Gateway Telegram (ou autre) testé bout-en-bout — envoi, réception, slash commands.
- Command approval activé sur les commandes shell dangereuses.
- DM pairing activé — seuls les utilisateurs approuvés parlent à l'agent.
- Isolation Docker en place (utilisateur non-root, FS majoritairement read-only, réseau restreint).
- Cron scheduler configuré (si tâches récurrentes) + logs surveillés.
- Sauvegarde quotidienne de
$HERMES_HOMEsur stockage distant chiffré. -
hermes updateplanifié régulièrement (cron mensuel + surveillance des releases). - Fichiers
SOUL.md,MEMORY.md,USER.md,~/.hermes/skills/sauvegardés séparément. - Registre RGPD à jour — provider LLM, données envoyées, base légale, durée de conservation.
Coûts réels
- Logiciel — gratuit (licence MIT).
- Hébergement — 0 € si vous exécutez en local, ~5-10 €/mois si vous prenez un VPS Linux dédié.
- Tokens LLM — variables selon usage. Pour un agent d'accueil TPE avec ~200 conversations/mois sur Claude Sonnet, comptez quelques dizaines d'euros/mois. Pour un usage Ollama local avec un modèle 8B sur votre propre GPU : 0 € en tokens.
- Sauvegardes — quelques Go/mois sur un stockage type Backblaze B2 ou Wasabi. Négligeable.
Un accompagnement clé en main ? Deux options MAG&Cie
Ce tuto vous permet de déployer et sécuriser Hermes Agent vous-même. Si vous préférez déléguer ou si vous voulez un pré-déploiement sécurisé, voici deux offres MAG&Cie qui prolongent naturellement ce guide :
Assistant IA opérationnel, sans gérer l'infrastructure
Vous voulez un assistant sur Telegram ou WhatsApp qui marche demain, sans passer une journée à faire tourner un gateway ? C'est exactement l'objet de notre offre Assistants IA sur mesure : setup, hébergement et monitoring gérés par MAG&Cie, à partir de 150 € HT + 20 € HT/mois.
Auditer ou sécuriser un déploiement existant
Vous avez déjà installé Hermes (ou un autre agent) et vous voulez un regard RSSI externe sur la sécurité ? Notre audit cybersécurité TPE/PME couvre l'auto-hébergement d'agent : posture réseau, isolation, gestion des secrets, RGPD, prompt injection. Pour une intégration structurée dans vos process, voir aussi l'accompagnement IA MAG&Cie.
Aller plus loin
- Documentation officielle Hermes Agent — la référence à jour, version après version.
- Dépôt GitHub NousResearch/hermes-agent — code source, releases, issues, SECURITY.md.
- agentskills.io — le standard ouvert des skills, compatible Hermes.
- Serveurs MCP disponibles — catalogue de connecteurs prêts à l'emploi.
- Tuto MAG&Cie : ajouter le SSO Google/Microsoft à votre application — pour sécuriser l'accès humain à une application qu'Hermes pilote.
Toutes les commandes de ce tuto proviennent de la documentation officielle Hermes Agent et du README GitHub du dépôt Nous Research au 2 juillet 2026 (Hermes Agent v0.18.0). Vérifiez la documentation officielle avant tout déploiement — le projet évolue vite.