Installer Hermes AI sur Windows : Desktop, PowerShell et WSL2

Hermes Agent prend en charge Windows 10 et Windows 11. Les utilisateurs disposent de trois scénarios de déploiement : l’exécution native via PowerShell, l’application graphique Hermes Desktop ou un environnement WSL2. Le choix dépend des outils de compilation requis, des contraintes liées au terminal et de l’architecture du système de fichiers.

Choisir son mode d’installation : environnement natif ou WSL2

Avant de procéder à l’installation, il est essentiel de définir le contexte d’exécution de vos tâches :

• PowerShell natif et Hermes Desktop partagent la même structure de données : le code source et l’environnement virtuel sont situés dans %LOCALAPPDATA%\hermes\hermes-agent, tandis que les paramètres utilisateur, l’historique des sessions et les compétences (skills) sont stockés dans %LOCALAPPDATA%\hermes. L’interface graphique et la console CLI sont interchangeables et opèrent sur le même état.
• WSL2 isole l’environnement au sein d’une machine virtuelle Linux et stocke la configuration séparément dans ~/.hermes.

Exemples de sélection d’architecture

1. Projets orientés Windows (PowerShell / .NET / utilitaires système) : si vous automatisez des flux de travail sur l’hôte, exécutez des passerelles d’arrière-plan pour Telegram ou Discord via le planificateur de tâches Windows et travaillez avec des fichiers locaux sur un disque NTFS, privilégiez PowerShell natif ou Hermes Desktop.
2. Projets avec pile Linux (Docker, Make, scripts POSIX) : si votre agent doit compiler des binaires pour Linux, communiquer via des sockets UNIX ou gérer des sessions via le terminal intégré du tableau de bord web, déployez l’agent dans WSL2. Sur les builds Windows natifs, le tableau de bord web prend en charge les métriques et la configuration, mais l’onglet de terminal intégré /chat requiert un POSIX PTY et n’est disponible que sous WSL2.

---

Option 1 : Installation native via PowerShell

Le programme d’installation natif ne nécessite pas de privilèges d’administrateur et configure automatiquement le gestionnaire de paquets uv, un environnement d’exécution isolé Python 3.11, Node.js pour les outils d’automatisation de navigateur ainsi que PortableGit. Vous n’avez pas besoin d’installer Python de manière globale sur votre système.

Ouvrez une console PowerShell standard et exécutez :

iex (irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1)

Le script ajoute %LOCALAPPDATA%\hermes\bin à la variable d’environnement PATH de l’utilisateur actuel. Une fois l’exécution terminée, fermez la fenêtre de la console puis ouvrez une nouvelle session de terminal afin d’appliquer le PATH mis à jour. Pour les paramètres avancés du script, consultez le guide officiel Windows Native.

---

Option 2 : Client graphique Hermes Desktop

Hermes Desktop propose une interface fenêtrée dotée d’une barre latérale pour les sessions, d’un graphe visuel des compétences, de la prise en charge des onglets et de la gestion d’agents en parallèle.

1. Téléchargez le programme d’installation depuis la page de documentation de Hermes Desktop.
2. Lancez le fichier d’installation téléchargé. Lors de la première ouverture, l’application exécute automatiquement le script de configuration des dépendances dans %LOCALAPPDATA%\hermes.

Si vous avez déjà configuré l’agent via PowerShell, l’application desktop récupère immédiatement vos clés d’API existantes et vos conversations enregistrées.

---

Option 3 : Installation dans WSL2

WSL2 fournit un environnement Linux standard (système de fichiers ext4, signaux POSIX, prise en charge des PTY).

Étape 1. Préparer WSL2

Dans une console PowerShell avec les privilèges d’administrateur (Exécuter en tant qu’administrateur), exécutez :

wsl --install

Redémarrez votre ordinateur si le système vous y invite, puis configurez votre nom d’utilisateur Linux et votre mot de passe. Vérifiez ensuite la version de votre distribution :

wsl --list --verbose

Assurez-vous que la colonne VERSION affiche bien 2 pour la distribution sélectionnée (Ubuntu par défaut).

Étape 2. Déployer Hermes Agent

Ouvrez votre terminal Ubuntu et exécutez la commande d’installation selon le guide de démarrage rapide WSL2 :

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

Important : stockez vos dépôts de travail et vos fichiers de projet dans le système de fichiers Linux (par exemple ~/projects/), et non sur un disque Windows monté (/mnt/c/). Les appels inter-systèmes via le protocole 9P peuvent ralentir les performances d’E/S et les opérations git.

---

Vérification de l’environnement et premier lancement

Le diagnostic et l’exécution doivent être effectués dans le terminal correspondant à chaque environnement : utilisez PowerShell pour l’installation native et Hermes Desktop, et utilisez le terminal Ubuntu pour WSL2.

Pour l’installation native et Hermes Desktop, ouvrez une nouvelle session PowerShell et lancez la vérification :

Get-Command hermes
hermes --version
hermes doctor

Pour l’installation dans WSL2, ouvrez le terminal Ubuntu et lancez le diagnostic :

command -v hermes
hermes --version
hermes doctor

La commande hermes doctor vérifie la résolution des chemins pour git, le moteur de navigateur Chromium et les dépendances auxiliaires.

Avant de démarrer une session de chat, vous devez configurer votre fournisseur de modèles : s’il n’est pas encore configuré, exécutez d’abord la commande hermes setup et sélectionnez votre fournisseur de modèles (dans PowerShell pour l’environnement natif, ou dans le terminal Ubuntu pour WSL2).

Une fois la configuration terminée, démarrez une conversation classique dans votre terminal et testez-la avec une tâche ne nécessitant aucune écriture de fichier ; notez que hermes chat n’applique pas de bac à sable (sandboxing) sur les permissions :

hermes chat

Pour votre première requête, envoyez une instruction qui ne nécessite pas d’écriture sur le disque (comme demander l’explication d’un concept architectural). Le résultat attendu est une initialisation réussie de votre fournisseur de modèles configuré et un affichage fluide du texte en streaming sans erreurs d’encodage.

Pour les détails de configuration facultatifs de certains modèles, reportez-vous à la documentation BetterToken.

---

Résolution des pannes courantes

Symptôme observé	Cause	Solution
hermes: The term 'hermes' is not recognized	La session active de la console n’a pas rechargé le User PATH mis à jour.	Redémarrez la fenêtre PowerShell ou appelez directement le binaire : & "$env:LOCALAPPDATA\hermes\bin\hermes.exe".
L’onglet /chat du tableau de bord web affiche une bannière d’erreur	Windows natif ne dispose pas du mécanisme système POSIX PTY.	La gestion des sessions et des tâches fonctionne nativement, mais pour le terminal web dans /chat, lancez l’agent via WSL2.
WinError 193: %1 is not a valid Win32 application	Tentative d’appel direct d’un script sans le wrapper .cmd.	Sous Windows, exécutez les outils Node et npm en indiquant explicitement leur extension (par exemple npx.cmd).
Points d’interrogation (?) à la place des caractères Unicode dans le CLI	Hôte de console obsolète sans prise en charge de CP 65001.	Utilisez Windows Terminal. Vérifiez que la variable d’environnement HERMES_DISABLE_WINDOWS_UTF8 n’est pas définie sur 1.
Latence élevée lors de l’exécution de git status dans WSL2	Le répertoire de travail du projet se trouve sur /mnt/c/....	Déplacez le dépôt dans le répertoire personnel Linux de la distribution (~/code/...) pour bénéficier des performances natives d’ext4.