Installer Hermes Agent en local et le brancher sur OpenRouter

À la fin de ce tutoriel, Hermes Agent fonctionne en ligne de commande sur votre poste, relié à un modèle open-weight (Qwen3.6 35B A3B) via une clé OpenRouter, avec une validation manuelle des commandes à risque. Il s'adresse aux développeurs et aux équipes techniques qui veulent évaluer un agent généraliste capable de coder, avant de lui confier d'autres usages. En option, vous le brancherez sur un modèle servi localement par Ollama.

Hermes Agent est un harness open source sous licence MIT, développé par Nous Research dans le dépôt NousResearch/hermes-agent. Il ne se limite pas au code : il garde une mémoire entre les sessions, crée des skills réutilisables et peut répondre depuis des messageries. Ce tutoriel s'en tient à l'usage en terminal, sur un dépôt de code.

Prérequis

• Un système pris en charge : macOS sur puce Apple (les Mac Intel ne sont pas pris en charge), Linux (x86_64 ou aarch64), WSL2, ou Windows 10/11 en natif via PowerShell. La page Platform Support détaille ces niveaux de support.
• Git, seul prérequis hors Windows. Sous Linux, ajoutez curl et xz-utils (sudo apt install curl xz-utils sur Debian ou Ubuntu).
• Rien d'autre à installer à la main : l'installeur récupère uv, Python 3.11, Node.js, ripgrep et ffmpeg s'ils manquent.
• Un compte OpenRouter crédité et un modèle offrant au moins 64 000 tokens de contexte : Hermes refuse de démarrer avec une fenêtre plus petite.

Les installations par PyPI (pip install hermes-agent) ou par Homebrew figurent parmi les méthodes non prises en charge. Le paquet PyPI n'est d'ailleurs pas à jour : il en reste à la version 0.19.0.

1. Installer Hermes Agent

Sous Linux, macOS et WSL2 :

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

Sous Windows, en PowerShell :

iex (irm https://hermes-agent.nousresearch.com/install.ps1)

Comme pour tout script téléchargé, lisez-le avant de l'exécuter : curl -fsSL https://hermes-agent.nousresearch.com/install.sh -o install-hermes.sh, puis bash install-hermes.sh. Si vous n'avez pas besoin de l'automatisation de navigateur, l'option documentée --skip-browser évite l'installation de Chromium :

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash -s -- --skip-browser

L'installeur place le code dans ~/.hermes/hermes-agent/, la commande dans ~/.local/bin/hermes et vos données dans ~/.hermes/ (sous Windows natif : %LOCALAPPDATA%\hermes). Il clone la branche principale du dépôt : la version installée peut donc être légèrement plus récente que la dernière version publiée. Il enchaîne ensuite sur l'assistant de configuration (hermes setup). Son choix proposé par défaut, Quick Setup (Nous Portal), vous connecte à l'abonnement de Nous Research, pas à OpenRouter : choisissez plutôt Blank Slate (voir la section « Sécurité et confidentialité ») ou Full setup, puis OpenRouter comme fournisseur. Vous pouvez aussi sauter l'assistant avec l'option --skip-setup de l'installeur et passer directement à la section 2.

Rechargez votre shell, puis vérifiez :

source ~/.zshrc    # ou : source ~/.bashrc
hermes --version
hermes doctor

hermes doctor diagnostique la configuration et les dépendances manquantes. Nous Research propose aussi une application de bureau, Hermes Desktop ; ce tutoriel reste sur la ligne de commande.

2. Créer une clé OpenRouter et la brancher

Créer la clé

1. Créez un compte sur openrouter.ai et ajoutez du crédit depuis la page Credits.
2. Sur la page Keys, cliquez sur Create API Key, nommez la clé et fixez une limite de crédit, comme le recommande OpenRouter pour qu'une clé qui fuite ou un agent qui boucle ne vide pas le solde.
3. Copiez la clé.

Brancher la clé dans Hermes

Hermes sépare les secrets, rangés dans ~/.hermes/.env, des réglages, rangés dans ~/.hermes/config.yaml. La méthode la plus sûre est l'assistant interactif :

hermes model

Choisissez OpenRouter et collez la clé quand elle est demandée. L'assistant affiche ensuite une sélection de modèles : si qwen/qwen3.6-35b-a3b n'y figure pas, choisissez Enter custom model name et saisissez cet identifiant. L'assistant écrit la clé dans .env et le modèle dans config.yaml. Qwen3.6 35B A3B est un modèle open-weight sous licence Apache 2.0, compatible avec l'appel d'outils selon le catalogue d'OpenRouter, avec une fenêtre de 262 144 tokens, bien au-dessus du minimum exigé.

Deux alternatives documentées :

# Écrire la clé dans ~/.hermes/.env (attention : elle reste dans l'historique du shell)
hermes config set OPENROUTER_API_KEY sk-or-v1-...

# Forcer fournisseur et modèle pour une seule session
hermes chat --provider openrouter --model qwen/qwen3.6-35b-a3b

Hermes lit aussi la variable OPENROUTER_API_KEY dans l'environnement du processus. Pour contrôler la configuration, hermes config get model affiche le modèle retenu.

Retenez la différence entre deux commandes proches : hermes model, lancé depuis le terminal, ajoute ou configure un fournisseur ; /model, tapé dans une session, bascule seulement entre des fournisseurs déjà configurés.

3. (Option) Utiliser un modèle local

Hermes documente deux voies. Dans l'application de bureau, Settings → Providers → Local Models installe et pilote lui-même un serveur llama.cpp. En ligne de commande, le guide Run Hermes Locally with Ollama passe par un point d'accès personnalisé. Téléchargez le modèle (environ 23 Go selon sa page sur ollama.com) et démarrez Ollama avec une fenêtre de contexte suffisante :

ollama pull qwen3.6:35b-a3b
OLLAMA_CONTEXT_LENGTH=64000 ollama serve

Lancez ensuite hermes model, choisissez Custom endpoint et renseignez :

• URL de base : http://localhost:11434/v1
• clé API : laissez vide (Ollama n'en demande pas)
• modèle : qwen3.6:35b-a3b
• longueur de contexte : 64000

L'équivalent dans ~/.hermes/config.yaml :

model:
  default: qwen3.6:35b-a3b
  provider: custom
  base_url: http://localhost:11434/v1
  context_length: 64000

La documentation d'Ollama propose aussi ollama launch hermes, qui installe Hermes si nécessaire et le configure sur Ollama. Elle indique environ 24 Go de mémoire vidéo pour qwen3.6 en local. LM Studio dispose de son propre fournisseur dans hermes model (adresse par défaut http://localhost:1234/v1).

4. Premier lancement

Avant le premier essai, passez les approbations en mode manuel avec hermes config set approvals.mode manual (voir la section « Sécurité et confidentialité »). Créez ensuite un dépôt jetable avec un bug volontaire :

mkdir ~/essai-hermes && cd ~/essai-hermes
git init
printf 'def add(a, b):\n    return a - b\n\nprint(add(2, 3))\n' > calc.py
git add calc.py && git commit -m "État initial"
hermes --tui

hermes --tui ouvre l'interface terminal recommandée ; hermes seul ouvre l'interface classique. Vérifiez d'abord que la bannière affiche le bon fournisseur et le bon modèle, puis demandez :

Lis calc.py et explique le bug. Ne modifie rien pour l'instant.

Une fois l'explication validée, demandez la correction, puis, si Python 3 est installé, l'exécution de python3 calc.py pour vérifier que le script affiche 5.

Ce qu'il faut observer :

• les appels d'outils (lecture de fichier, écriture, terminal) et leur sortie en continu ;
• une demande d'approbation si une commande figure parmi les motifs jugés dangereux ;
• la consommation, affichée par /usage.

Contrôlez le résultat vous-même avec git diff après la session. hermes -c reprend la dernière session. Pour vos premiers essais sur un vrai projet, hermes chat --worktree crée un worktree git isolé, et --checkpoints enregistre un point de restauration avant les modifications destructrices.

Sécurité et confidentialité

Où vont les données. Selon la FAQ, Hermes n'envoie les appels qu'au fournisseur de modèle configuré et ne collecte pas de télémétrie ; conversations, mémoire et skills restent dans ~/.hermes/. Avec OpenRouter, vos instructions, les fichiers lus et les sorties de commandes transitent par OpenRouter puis par le fournisseur qui sert le modèle. OpenRouter ne conserve pas les prompts sauf activation explicite de la journalisation, mais garde des métadonnées ; la conservation côté fournisseur varie. Dans config.yaml, vous pouvez exclure les fournisseurs susceptibles de conserver vos données ou de s'en servir pour entraîner des modèles :

provider_routing:
  data_collection: "deny"

Avec Ollama, l'inférence reste sur la machine. Deux points propres à Hermes : la mémoire persiste d'une session à l'autre et revient dans les prompts suivants, donc ne lui confiez aucun secret ; les outils optionnels (recherche web, navigateur, passerelle d'outils de Nous Portal) contactent leurs propres services quand vous les activez.

La clé. Elle vit dans ~/.hermes/.env, hors du dépôt. Les outils de fichiers de Hermes refusent de lire les fichiers .env d'un projet et bloquent l'écriture des fichiers d'identifiants (clés SSH, ~/.aws…). Ces protections portent sur les outils de lecture et d'écriture, pas sur les commandes du terminal : d'où l'importance des approbations.

Les commandes. Avant d'exécuter une commande, Hermes la compare à une liste de motifs dangereux (suppression récursive, écriture dans /etc/, curl … | sh, etc.). Seules les commandes qui correspondent à l'un de ces motifs passent par le système d'approbation ; les autres s'exécutent directement. Par défaut, le mode smart fait évaluer ces commandes signalées par un modèle auxiliaire (par défaut, votre modèle principal) : il approuve seul celles qu'il juge sans risque, refuse les dangereuses et vous interroge en cas de doute. Pendant une évaluation, faites-vous soumettre chaque commande signalée :

hermes config set approvals.mode manual

N'activez jamais le mode YOLO (--yolo, /yolo ou HERMES_YOLO_MODE=1) hors d'un environnement jetable : il supprime toutes les approbations, sauf une liste de blocage minimale.

L'isolement. Avec le terminal local par défaut, les commandes s'exécutent directement sur votre machine. hermes config set terminal.backend docker les fait tourner dans un conteneur (Hermes considère alors le conteneur comme la frontière et ne soumet plus les commandes dangereuses à approbation). À l'installation, le mode Blank Slate de hermes setup n'active que les outils de fichiers et de terminal, sans web, mémoire, délégation ni MCP : une bonne base pour un agent de code limité à son rôle.

Dépannage

• hermes: command not found : le shell n'a pas rechargé le PATH. Lancez source ~/.zshrc (ou ~/.bashrc) et vérifiez la présence de ~/.local/bin/hermes.
• API key not set : relancez hermes model ou hermes config set OPENROUTER_API_KEY …, et vérifiez qu'aucune entrée contradictoire ne traîne dans ~/.hermes/.env.
• Modèle introuvable : vérifiez l'identifiant exact (qwen/qwen3.6-35b-a3b pour OpenRouter), puis resélectionnez-le avec hermes model.
• Modèle local refusé ou contexte dépassé : Hermes exige au moins 64 000 tokens de contexte. Alignez la fenêtre d'Ollama (OLLAMA_CONTEXT_LENGTH) et context_length dans config.yaml.
• Configuration incomplète après une mise à jour : lancez hermes config check, puis hermes config migrate. hermes update met Hermes à jour.

Aller plus loin

• Situer Hermes face aux autres harness : Claude Code vs Hermes vs Opencode : lequel choisir ?
• Installer les deux autres harness de cette série : OpenCode et pi.
• Apprendre à cadrer, relire et sécuriser le travail d'un agent de code en équipe : formation Claude Code pour les équipes de développement.