# Guide complet — Installer et utiliser Hermes Agent (macOS / Linux) Ce guide vous emmène de zéro à un agent IA fonctionnel sur votre machine : installation, branchement d'un modèle, première session, skills et astuces. Comptez une quinzaine de minutes pour la mise en route. **Toutes les commandes citées proviennent de la [documentation officielle](https://hermes-agent.nousresearch.com/docs)** (méthode exacte de la doc, traduite et remise en ordre). En cas d'écart entre ce guide et la doc, la doc fait foi. --- ## 1. Hermes Agent, en bref Hermes Agent est l'**agent IA open source de Nous Research** (licence MIT). Ce n'est pas un simple chatbot : il agit. Il lit et écrit des fichiers, exécute des commandes dans un terminal, navigue le web, analyse des images, et enchaîne les étapes d'une tâche tout seul grâce à ses outils. Ce qui le distingue : - **Les skills** — des procédures réutilisables (déployer, rédiger une PR, analyser un document…) qu'il charge à la demande et que vous pouvez lui faire créer. - **La mémoire persistante** — il retient vos préférences et votre contexte d'une session à l'autre. - **Tous les fournisseurs de modèles** — DeepSeek, OpenRouter, Anthropic, OpenAI, Google… ou 100 % en local sur votre machine. - **Plusieurs surfaces** — le terminal (CLI et TUI), une application desktop, un tableau de bord web, et même un « gateway » multi-plateformes (Telegram, Discord, Slack…). - **Votre vie privée** — la documentation annonce un stockage local de base et aucune télémétrie Hermes. Cela ne bloque pas les envois de contexte au modèle ni aux outils et services activés. **Un modèle local ne rend pas tout l’agent hors ligne** : lisez les précautions de confidentialité à l’étape 2. **Combien ça coûte ?** Le kit et le logiciel sont gratuits. Selon votre choix, le modèle peut utiliser une **API facturée**, un **abonnement** ou tourner sur votre machine. Les **outils externes** et l’**hébergement** peuvent aussi être payants. Un modèle local évite la facturation API de ce modèle, pas le coût du **matériel** ni de l’**électricité**. ## 2. Avant de commencer **Périmètre du kit** : son script utilise **Bash** sur macOS, Linux ou WSL2, pas dans PowerShell. Lisez ces prérequis avant de le lancer avec votre compte utilisateur normal. Le script ne vérifie pas toutes les dépendances ni la compatibilité de chaque version du système. ### Système et architecture - **macOS Apple Silicon** (M1 et suivants) : méthode officielle en terminal classée Tier 1 par Nous Research. - **Linux / WSL2** (x86_64 ou arm64, aussi appelé aarch64) : la documentation indique des tests sur Ubuntu récent et WSL2. Cela ne garantit pas chaque distribution ni toutes les fonctions optionnelles. - **Windows natif** : suivez la [méthode officielle PowerShell](https://hermes-agent.nousresearch.com/docs/getting-started/installation#windows-native), hors de ce script Bash ; ou utilisez le kit dans WSL2. - **Mac Intel — compatibilité non garantie** : les pages officielles divergent au contrôle du 2026-10-16. Le guide d’installation présente macOS Intel comme non pris en charge, alors que la matrice décrit encore la CLI et des bundles `darwin-x64` construits seulement pour certaines releases. Le message du script du kit sur Intel ne vaut pas validation : consultez les deux sources ci-dessous et demandez confirmation au projet Hermes pour votre machine et votre version avant de lancer un installateur. ### Outils et dépendances Préparez **Git, curl, tar et un utilitaire SHA-256** (`shasum` ou `sha256sum`). L’installateur officiel gère son environnement Python et Node.js ; cela ne remplace pas les prérequis système. Une construction depuis les sources peut nécessiter un **compilateur** et des **bibliothèques système**. Sur Linux, Chromium dépend aussi de bibliothèques fournies par la distribution. Sur Linux glibc, le Node.js géré peut nécessiter `libatomic.so.1`. La documentation indique que l’installateur tente de fournir le paquet adapté s’il manque ; cela peut demander des droits administrateur. Si vous ne les avez pas, transmettez à votre administrateur la commande indiquée par l’erreur, sans relancer tout le kit en root. Les vérifications du kit ne garantissent pas une installation complète de ces composants. ### Modèle et budget avant le premier essai Choisissez un fournisseur ou un serveur de modèle local avec appel d’outils. Le [démarrage officiel](https://hermes-agent.nousresearch.com/docs/getting-started/quickstart) exige au moins **64 000 tokens de contexte** : vérifiez aussi le contexte réellement configuré côté serveur. La mémoire nécessaire dépend du modèle, de sa quantification et du contexte ; aucun minimum RAM universel n’est garanti ici. Le kit et le logiciel sont gratuits ; le **modèle IA, les outils externes et l’hébergement peuvent être payants**. Vérifiez les **tarifs** et les quotas du fournisseur choisi : un abonnement de chat ne couvre pas automatiquement une API ou tous les outils. Définissez un **plafond** de dépenses **si le fournisseur le permet**, et vérifiez ce qu’il couvre ; une alerte de budget n’est pas forcément un blocage. Commencez par un **essai court**, sur un fichier de test sans secrets, avant une tâche longue ou automatisée. Consultez la consommation avec `/usage`, puis le tableau de bord de **facturation** du fournisseur et des outils activés : l’indication dans Hermes **ne remplace pas** leur relevé. Un modèle local évite sa facturation API, mais demande du matériel et de l’électricité. **Source budget consultée le 2026-10-19** : [choix du fournisseur et modes de configuration](https://hermes-agent.nousresearch.com/docs/getting-started/quickstart#2-choose-a-provider). Ces précautions ne constituent ni un tarif garanti ni une installation testée. > **Où le faire tourner ?** Commencez sur une machine compatible dont vous > contrôlez les accès. Un serveur toujours allumé est une option, pas un prérequis. > Dimensionnez-le selon votre usage, sans tarif ni performance garantis ici. > [Hostinger](https://www.hostinger.com/fr?REFERRALCODE=FGUOPENCL2M5) est un lien > partenaire qui peut financer le kit ; son utilisation reste facultative. **Sources officielles consultées le 2026-10-16** : [installation et prérequis](https://hermes-agent.nousresearch.com/docs/getting-started/installation#prerequisites), [matrice des plateformes](https://hermes-agent.nousresearch.com/docs/getting-started/platform-support) et [démarrage](https://hermes-agent.nousresearch.com/docs/getting-started/quickstart). Ce contrôle documentaire indépendant n’est pas une installation testée sur chaque système. Les sections suivantes décrivent la procédure ; elles ne prouvent pas sa réussite sur votre machine. ## 3. Étape 1 — Installer Hermes Agent ### Méthode A — Application desktop (macOS) Téléchargez le paquet depuis le [site officiel](https://hermes-agent.nousresearch.com/), ouvrez le fichier `.dmg` et glissez `Hermes.app` dans Applications. Vous obtenez le CLI **et** l'interface graphique. Si vous avez déjà installé la version terminal, l'app desktop s'ajoute à tout moment avec : ```bash hermes desktop ``` ### Méthode B — Terminal (macOS, Linux, WSL2) — la méthode principale de ce kit La commande officielle, telle qu'elle figure dans la documentation : ```bash curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash ``` Le script de ce kit fait exactement la même chose, avec des vérifications en plus (système supporté, prérequis, pas de root) et des messages en français : ```bash bash scripts/install.sh ``` Ce que fait l'installateur (résumé de la doc) : il récupère les sources, met en place un Python dédié et les outils nécessaires (Node, npm, ripgrep, FFmpeg), crée le lanceur `~/.local/bin/hermes`, prépare le dossier de données `~/.hermes/`, et — si vous êtes dans un terminal interactif — lance l'assistant de configuration. Un journal détaillé est écrit dans `logs/install.log` sous `~/.hermes/`. Options utiles qui existent réellement (documentées) : `--skip-browser`, `--skip-computer-use`, `--non-interactive`, `--verbose`, `--include-desktop`. ⚠️ **Trois pièges à éviter** : 1. **Ne lancez jamais l'installateur avec `sudo` ou en root.** Il installe dans votre dossier utilisateur (`~/.local/bin`), pas au niveau système. 2. N'installez pas Hermes via `pip`, `brew` ou l'AUR : ces méthodes ne sont pas supportées par la doc officielle. 3. Ne copiez pas de clé API dans les fichiers du kit — voyez l'étape 2. ### Vérifier l'installation Rechargez votre shell, puis faites un bilan de santé : ```bash source ~/.zshrc # ou : source ~/.bashrc hermes doctor ``` `hermes doctor` vous dit précisément ce qui manque, s'il manque quelque chose. ## 4. Étape 2 — Brancher un fournisseur de modèle C'est l'étape la plus importante. Le plus simple est l'assistant : ```bash hermes setup ``` Il propose trois modes : **Quick Setup (Nous Portal)** — un abonnement couvre 300+ modèles, sans gérer de clés ; **Full Setup** — vous apportez votre propre clé parmi tous les fournisseurs ; **Blank Slate** — un agent minimal, tout le reste désactivé (pour les utilisateurs avancés). Vous pouvez aussi viser directement le choix du modèle : ```bash hermes model ``` Quelques fournisseurs populaires et leurs variables de clé (documentés) : | Fournisseur | Variable | Où obtenir une clé | |---|---|---| | **DeepSeek** | `DEEPSEEK_API_KEY` | site de DeepSeek | | **OpenRouter** | `OPENROUTER_API_KEY` | openrouter.ai | | **Anthropic** | `ANTHROPIC_API_KEY` | console Anthropic | | **Google AI Studio** | `GOOGLE_API_KEY` ou `GEMINI_API_KEY` | Google AI Studio | | **xAI (Grok)** | `XAI_API_KEY` | console xAI | Pour enregistrer une clé proprement, la doc donne cette commande : ```bash hermes config set OPENROUTER_API_KEY sk-or-... ``` Le même principe vaut pour les autres (par exemple `DEEPSEEK_API_KEY`). **Règle d'or issue de la doc** : Hermes range automatiquement les secrets dans `~/.hermes/.env` (jamais dans `config.yaml`) et les réglages dans `~/.hermes/config.yaml`. Utilisez donc `hermes config set` plutôt que d'éditer des fichiers à la main. ### Un modèle local : sans facturation API du modèle Hermes peut piloter un modèle exécuté sur votre machine via [Ollama](https://ollama.com/). Cela évite la facturation API de **ce modèle**, mais pas le coût du **matériel**, de l’**électricité**, d’un éventuel **hébergement** ni des **outils externes** activés. L’offre Ollama Cloud est un service distinct : elle n’est pas le serveur local décrit ici. Consultez le [guide officiel des modèles locaux](https://hermes-agent.nousresearch.com/docs/integrations/providers#ollama--local-models-zero-config) (source consultée le 2026-10-19), notamment pour régler le contexte côté serveur. Les exemples ci-dessous ne garantissent pas que ce modèle tienne sur votre machine. ```bash # 1. Installez Ollama (ligne de commande donnée par le guide officiel Hermes) curl -fsSL https://ollama.com/install.sh | sh # 2. Téléchargez un modèle (choisissez selon votre RAM) ollama pull qwen3.5:27b ``` Puis branchez-le dans Hermes (`hermes model` → **Custom endpoint**) ou en config : ```yaml model: default: "qwen3.5:27b" provider: "custom" base_url: "http://localhost:11434/v1" ``` Deux conseils du guide officiel : choisissez un modèle qui **sait appeler des outils** (c'est ce qui permet à l'agent d'agir, pas seulement de discuter), et montez son contexte à 64 000 tokens minimum. La mémoire nécessaire dépend du modèle, de sa quantification et du contexte réellement configuré : **aucun minimum RAM universel** n’est garanti ici. Le serveur local traite les appels de ce modèle ; les autres fonctions de l’agent peuvent encore utiliser le réseau. ### Confidentialité : modèle local ne veut pas dire hors ligne **Stockage et transmission sont deux choses différentes.** La FAQ officielle indique que les conversations, la mémoire et les skills de base sont stockés localement dans `~/.hermes/`, sans télémétrie Hermes. Une copie locale ne garantit pas que son contenu ne sera jamais transmis : un **fournisseur de modèle distant** peut recevoir les messages, extraits de fichiers et résultats d’outils ajoutés au **contexte**. Consultez ses règles de conservation avant de lui confier des données. Même avec Ollama sur votre machine, la **recherche web**, le navigateur, les API d’images ou de voix, les serveurs **MCP**, les intégrations de **messagerie** ou les extensions de **mémoire** peuvent contacter des services externes. Les données transmises dépendent des outils et de leur configuration. Les **modèles auxiliaires** (vision, compression…) et les **fournisseurs de secours** peuvent aussi être configurés séparément du modèle principal : vérifiez leur destination, sans supposer qu’un modèle principal local suffit. **Avant un premier essai :** 1. Vérifiez le modèle et son adresse avec `hermes model`, y compris les modèles auxiliaires ; contrôlez aussi les fournisseurs de secours configurés. 2. Examinez les outils avec `hermes tools` et les intégrations activées ; désactivez ce qui est inutile. Limiter les outils web **ne bloque pas à lui seul les accès réseau du terminal**, des scripts ou des extensions. 3. Travaillez sur un **fichier de test sans secrets**, avec les accès minimaux. Ne partagez pas de clés API, de fichier `.env`, de journaux bruts ou de sauvegardes contenant des identifiants dans une demande de support. 4. Si l’absence de sortie réseau est une exigence, prévoyez un **contrôle réseau indépendant** et testez votre configuration dans un environnement isolé. Le kit ne vérifie pas cette propriété : ce guide n’est **pas un audit réseau** ni une garantie de confidentialité de chaque fournisseur ou extension. **Sources officielles consultées le 2026-10-20** : [stockage local et télémétrie](https://hermes-agent.nousresearch.com/docs/reference/faq#is-my-data-sent-anywhere), [outils activés](https://hermes-agent.nousresearch.com/docs/user-guide/features/tools#using-toolsets), [services optionnels](https://hermes-agent.nousresearch.com/docs/integrations/providers#optional-api-keys), [modèles auxiliaires](https://hermes-agent.nousresearch.com/docs/user-guide/configuration#auxiliary-models) et [fournisseurs de secours](https://hermes-agent.nousresearch.com/docs/integrations/providers#fallback-providers). ## 5. Étape 3 — Votre première session ```bash hermes # interface classique hermes --tui # interface moderne (recommandée) ``` Vous verrez une bannière avec votre modèle, vos outils et vos skills. Lancez-vous avec une demande précise et vérifiable, par exemple : - « Résume ce dossier en 5 points et dis-moi quel fichier semble être le point d'entrée. » - « Quelle est l'utilisation de mon disque ? Montre-moi le top 5 des dossiers les plus lourds. » - « Aide-moi à mettre en place un workflow Git propre pour ce projet. » **Ça marche si** : la bannière affiche votre modèle, Hermes répond sans erreur, il utilise un outil (terminal, lecture de fichier…), et la conversation continue normalement. Si c'est le cas, vous avez passé le plus dur. Repères pendant la session : | Action | Comment | |---|---| | Toutes les commandes | tapez `/help` | | Changer de modèle | `/model` | | Voir votre consommation | `/usage` | | Compresser une longue session | `/compress` | | Interrompre / rediriger l'agent | `Ctrl+C`, ou tapez un nouveau message | | Saut de ligne (sans envoyer) | `Alt+Entrée` ou `Ctrl+J` | | Coller une capture d'écran | `Ctrl+V` | | Autocomplétion des commandes | tapez `/` puis `Tab` | **Sessions** : `hermes -c` (ou `hermes --continue`) reprend la dernière session, `hermes -r "titre"` reprend une session nommée (donnez-lui un nom avec `/title`), et `hermes sessions list` liste tout. ## 6. Les skills, expliqués simplement Une **skill** est un document d'instruction que l'agent charge **uniquement quand il en a besoin** : une procédure pas-à-pas pour une tâche précise. Hermes en embarque un catalogue dès l'installation (dans `~/.hermes/skills/`) et en télécharge d'autres à la demande. **Le principe malin** : chaque skill installée devient une **commande slash**. Exemples issus de la doc : `/github-pr-workflow créer une PR`, `/gif-search des GIFs de chats drôles`, ou juste `/excalidraw` pour charger la skill et laisser l'agent vous demander ce que vous voulez. Vous pouvez même en enchaîner plusieurs : ```bash /github-pr-workflow /test-driven-development corrige l'issue #123 et ouvre une PR ``` **Explorer et installer d'autres skills** (un scan de sécurité est fait avant l'installation) : ```bash hermes skills browse # tout le catalogue hermes skills search kubernetes # recherche par mot-clé hermes skills install openai/skills/k8s ``` **Créer les vôtres** — c'est là que ça devient puissant. La commande `/learn` part de n'importe quelle matière : ```bash /learn comment je viens de déployer le serveur de staging /learn https://docs.exemple.fr/api/quickstart /learn mes notes sur la facturation : ouvrir le portail, Nouveau > Facture, joindre le justificatif, envoyer ``` L'agent rédige la skill, et elle devient disponible partout. Vous pouvez aussi lui dire simplement : « sauvegarde ce que tu viens de faire en skill `deploy-staging` » — et la prochaine fois, `/deploy-staging` suffit. ## 7. Astuces qui changent tout - **Soyez précis.** « Corrige le TypeError dans `api/handlers.py` ligne 47 » vaut mieux que « corrige le code ». Collez vos messages d'erreur tels quels. - **Utilisez `AGENTS.md`.** Un fichier `AGENTS.md` à la racine d'un projet (conventions, architecture, « on utilise pytest »…) est lu automatiquement à chaque session. Pour la personnalité globale de l'agent, la doc prévoit `~/.hermes/SOUL.md`. - **Mémoire ou skill ?** La mémoire retient des **faits** (« je préfère les réponses courtes »), les skills des **procédures**. Dites-lui « retiens ça pour la prochaine fois » après une session utile. - **Surveillez les coûts.** `/usage` en cours de route, et `/compress` quand une session devient longue. Évitez de changer de modèle sans arrêt dans une même longue session (ça « casse » le cache du fournisseur et ça coûte plus cher). - **Déléguez le travail parallèle.** Demandez-lui de traiter plusieurs recherches en parallèle via des sous-agents : chaque sous-agent travaille dans son coin et ne renvoie qu'un résumé. - **Sécurité d'abord.** Hermes demande votre approbation avant les commandes dangereuses (`rm -rf`, etc.) : préférez « une fois » ou « session » à « toujours ». Pour bidouiller du code que vous ne connaissez pas, passez les commandes en sandbox : `hermes config set terminal.backend docker`. - **Bots : mettez une liste d'accès.** Si vous connectez Telegram ou Discord, la doc recommande des allowlists (`TELEGRAM_ALLOWED_USERS`, `DISCORD_ALLOWED_USERS`) et déconseille fortement `GATEWAY_ALLOW_ALL_USERS=true` pour un bot qui a accès au terminal. - **MCP** : Hermes peut se connecter à des serveurs d'outils externes (MCP). Le principe et des exemples de configuration sont sur la page [MCP](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp) de la doc. ## 8. Dépannage express Les problèmes les plus fréquents et leurs solutions (d'après la doc officielle) : | Symptôme | Solution | |---|---| | `hermes: command not found` | Rechargez le shell (`source ~/.zshrc` ou `source ~/.bashrc`) ou ouvrez un nouveau terminal. Sinon : `export PATH="$HOME/.local/bin:$PATH"` | | « API key not set » | `hermes model` pour configurer le fournisseur | | Config incomplète après une mise à jour | `hermes config check` puis `hermes config migrate` | | Réponses vides / cassées | Relancez `hermes model` et vérifiez fournisseur, modèle et clé | | Un doute, quelque chose cloche | `hermes doctor` — il dit exactement quoi corriger | Séquence de secours complète recommandée par la doc : `hermes doctor` → `hermes model` → `hermes setup` → `hermes sessions list` → `hermes --continue` → `hermes gateway status`. Besoin d'aide ? La [FAQ officielle](https://hermes-agent.nousresearch.com/docs/reference/faq) et le [Discord de Nous Research](https://discord.gg/nousresearch) — et pour le français, la communauté : . ## 9. Mettre à jour, désinstaller ```bash hermes update # mise à jour de l'installation (sources) hermes --version # vérifier la version installée ``` L'app desktop se met à jour elle-même (bouton de mise à jour). Pour une installation Docker, on tire simplement une nouvelle image ; sur le paquet Termux : `pkg upgrade hermes-agent`. Pour désinstaller, la doc fournit : ```bash hermes uninstall --dry-run # d'abord, pour voir ce qui sera supprimé hermes uninstall # désinstalle (les données peuvent être conservées) ``` `--full` supprime aussi vos données utilisateur ; en cas de doute, faites d'abord une sauvegarde (`hermes backup` — l'archive complète inclut vos identifiants, à garder en lieu sûr). ## 10. Pour aller plus loin - **`demarrage.md`** (inclus dans ce kit) : dix usages concrets pour vos premiers jours. - **Documentation officielle** : — dont le [CLI](https://hermes-agent.nousresearch.com/docs/user-guide/cli), les [providers](https://hermes-agent.nousresearch.com/docs/integrations/providers), le [système de skills](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills) et la [messagerie](https://hermes-agent.nousresearch.com/docs/user-guide/messaging). - **Dépôt GitHub** : . --- **Crédits.** Hermes Agent est un projet de **Nous Research**, publié sous licence MIT. Ce guide est un travail communautaire francophone (OpenClaw France) : il reformule la documentation officielle sans la remplacer. Merci à Nous Research, et bon voyage avec votre agent.