Faire tourner Hermes Agent sur Windows avec WSL2

Hermes Agent ne supporte pas Windows natif

Si vous êtes sous Windows et essayez d'installer Hermes Agent, vous allez rapidement vous heurter à un obstacle. La documentation officielle de Hermes l'indique clairement : Windows natif n'est pas supporté. Les plateformes supportées sont Linux, macOS, WSL2 et Android via Termux.

Ce n'est pas un manque qui devrait se combler de sitôt. Hermes utilise des outils shell, une gestion des processus et des conventions de système de fichiers qui sont natives à Linux. Le chemin Windows officiel est WSL2, le Sous-système Windows pour Linux 2, qui vous donne un vrai noyau Linux à l'intérieur de Windows.

Ce guide parcourt la configuration WSL2 complète pour Hermes Agent et explique où la friction apparaît après la première exécution réussie.

Ce qu'est réellement WSL2

WSL2 n'est pas un émulateur ni une couche de compatibilité. Il exécute un vrai noyau Linux dans une machine virtuelle légère. Depuis un shell WSL2, vous avez un environnement Linux complet : système de fichiers, table des processus, gestionnaire de paquets et réseau.

Pour Hermes, cela signifie que tout ce qui fonctionne sur un serveur Linux fonctionne également dans WSL2, avec quelques mises en garde sur la mise en réseau et la persistance que nous couvrirons ci-dessous.

Microsoft livre WSL2 avec les versions modernes de Windows 10 (build 1903 et ultérieures) et Windows 11. Si votre Windows est raisonnablement récent, vous y avez déjà accès.

Étape 1 : Activer WSL2

Ouvrez PowerShell en tant qu'Administrateur et exécutez :

wsl --install

Cette commande active la fonctionnalité WSL, installe la distribution Linux par défaut (Ubuntu) et définit WSL2 comme version par défaut. Un redémarrage est nécessaire pour terminer.

Si vous avez déjà WSL1 installé et souhaitez passer à WSL2 :

wsl --set-default-version 2

Vérifiez ensuite quelle version utilise votre distribution :

wsl --list --verbose

Cherchez la colonne VERSION. Vous voulez 2.

Étape 2 : Configurer Ubuntu dans WSL2

Après le redémarrage, ouvrez Ubuntu depuis le menu Démarrer. Le premier lancement vous guide dans la création d'un nom d'utilisateur et d'un mot de passe Unix. C'est votre utilisateur WSL2, distinct de votre compte Windows.

Mettez à jour la liste des paquets et mettez à niveau les paquets installés :

sudo apt update && sudo apt upgrade -y

Installez curl et les autres outils de base dont Hermes aura besoin :

sudo apt install -y curl git build-essential

Étape 3 : Installer Hermes Agent dans WSL2

Avec un environnement Ubuntu fonctionnel, installez Hermes en utilisant le script d'installation officiel :

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

Après l'installation, lancez la configuration :

hermes setup

Cela vous guide dans la sélection du fournisseur, la configuration du modèle et la configuration optionnelle de Telegram. Choisissez OpenRouter pour la première exécution la plus simple : vous aurez besoin d'une clé API OpenRouter prête.

Après la configuration, démarrez Hermes :

hermes

Si vous voyez l'interface terminal, votre installation WSL2 fonctionne.

Étape 4 : Configuration Telegram dans WSL2

Mettre Hermes sur Telegram dans WSL2 nécessite quelques étapes supplémentaires par rapport à un serveur Linux natif.

La passerelle de messagerie Hermes doit rester active pour recevoir les messages Telegram. Dans WSL2, le processus tourne tant que la session WSL2 est ouverte. Si vous fermez votre terminal, la passerelle s'arrête et les messages Telegram ne seront pas livrés.

Pour garder la passerelle active en arrière-plan :

hermes gateway start --detach

Vérifiez qu'elle tourne :

hermes gateway status

Si vous souhaitez que la passerelle démarre automatiquement au lancement de WSL2, vous pouvez l'ajouter à votre ~/.bashrc ou configurer un service systemd (WSL2 supporte systemd dans les versions récentes sous Windows 11).

Limitations connues de WSL2 pour Hermes

La mémoire et l'état ne survivent pas aux arrêts de WSL2. Par défaut, WSL2 se termine quand vous fermez la dernière session. Les processus en cours s'arrêtent. Si Hermes reçoit des messages Telegram ou exécute des tâches planifiées, elles seront interrompues. Vous devez redémarrer Hermes et la passerelle à chaque démarrage de WSL2.

La mise en réseau est bridgée, pas native. WSL2 crée un adaptateur réseau virtuel. Votre instance Hermes n'a pas d'adresse IP stable depuis la perspective d'internet. Cela compte si vous construisez des intégrations qui doivent recevoir du trafic webhook, mais cela n'affecte pas les appels sortants vers Telegram ou l'API du modèle.

Friction sur les chemins de fichiers. WSL2 a son propre système de fichiers Linux (\\wsl$\Ubuntu\home\... sous Windows). Si vous souhaitez partager des fichiers entre WSL2 et des applications Windows, vous pouvez monter les chemins Windows dans WSL2 (/mnt/c/...). Les fichiers mémoire et de configuration de Hermes vivent dans votre répertoire home WSL2 par défaut, ce qui signifie qu'ils ne sont pas directement accessibles depuis l'Explorateur Windows sans utiliser le chemin réseau.

Performances sur les chemins Windows. Si vous stockez les fichiers Hermes sur le système de fichiers Windows (sous /mnt/c/), les opérations de fichiers seront plus lentes que si elles sont sur le système de fichiers WSL2. Gardez les données Hermes dans le répertoire home Linux pour de meilleures performances.

Nécessite de laisser WSL2 ouvert. Pour que Hermes soit continuellement disponible sur Telegram, votre terminal WSL2 doit rester actif. C'est la principale contrainte opérationnelle pour les utilisateurs Windows qui souhaitent un agent persistant.

Quand l'hébergement géré est le meilleur choix pour les utilisateurs Windows

Pour la plupart des utilisateurs Windows, WSL2 fonctionne suffisamment bien pour l'évaluation et l'apprentissage. Les problèmes apparaissent quand vous souhaitez une disponibilité Hermes persistante et permanente.

WSL2 est un outil développeur, pas un serveur. Le faire tourner en continu signifie que votre machine Windows doit rester allumée, la session WSL2 ne peut pas se fermer, et vous êtes responsable des redémarrages quand les mises à jour Windows forcent un redémarrage.

Si vous voulez Hermes disponible sur Telegram 24 heures sur 24 sans faire tourner votre machine locale, vous avez deux options :

Louer un VPS Linux et y faire tourner Hermes à la place d'en local.
Utiliser l'hébergement géré comme Hermify, où le runtime vit sur un serveur persistant et vous interagissez avec lui via Telegram et le tableau de bord.

Le deuxième chemin ne nécessite aucune connaissance Linux, aucune gestion de VPS, et fonctionne depuis Windows sans WSL2 du tout. Vous n'installez rien en local. Hermify gère le runtime à votre place. Le bot Telegram reste disponible parce qu'il tourne sur un vrai serveur, pas sur votre ordinateur portable.

C'est le chemin que prennent la plupart des utilisateurs Windows quand ils dépassent l'évaluation et veulent Hermes comme véritable assistant quotidien.

Un cadre de décision pratique

| Scénario | Recommandation | |---|---| | Tester Hermes pour la première fois sous Windows | WSL2 convient | | Construire des outils personnalisés ou contribuer à Hermes | WSL2 sur une machine de développement | | Vouloir Hermes sur Telegram disponible toute la journée | Hébergement géré (Hermify) ou un VPS Linux | | Vouloir ignorer entièrement la configuration Linux | Hébergement géré | | Déjà sous Linux en local ou sur un serveur | Linux natif, pas besoin de WSL2 |

WSL2 n'est pas le mauvais outil : c'est le bon outil pour le développement. Pour un usage en production persistant, un runtime côté serveur est plus fiable. Vous pouvez explorer comment l'hébergement géré Hermes se compare à un VPS auto-hébergé si vous souhaitez évaluer les options côte à côte.