Hermes Agent Web Dashboard : accès local, profils et diagnostics

L’interface graphique Hermes Agent Web Dashboard permet d’administrer l’installation de votre agent directement depuis un navigateur web, évitant ainsi la modification manuelle des fichiers de configuration. Le tableau de bord permet de gérer les clés d’accès API, de basculer entre différents profils, d’inspecter l’historique des sessions et d’exécuter un terminal intégré sans altérer manuellement l’environnement système.

Lancement initial et dépendances système

Par défaut, le tableau de bord s’exécute sur l’interface de bouclage local (loopback) :

hermes dashboard

Cette commande démarre un serveur HTTP local et ouvre l’adresse http://127.0.0.1:9119 dans votre navigateur par défaut. Si ce port est déjà utilisé par un autre service local, vous pouvez le redéfinir à l’aide du paramètre --port :

hermes dashboard --port 9120 --no-open

Le drapeau --no-open empêche l’ouverture automatique d’un nouvel onglet dans le navigateur, ce qui est idéal pour les processus en arrière-plan ou les scripts d’automatisation.

Le paquet de base hermes-agent n’inclut pas la pile web par défaut. Dans les environnements Linux, macOS et WSL2, installez les composants optionnels nécessaires dans l’environnement virtuel de l’agent :

cd ~/.hermes/hermes-agent && uv pip install -e ".[web,pty]"

L’option web installe FastAPI et Uvicorn, tandis que pty ajoute ptyprocess pour les systèmes conformes à POSIX. La compilation de l’interface statique du tableau de bord nécessite une installation active de Node.js (lorsque npm est présent, le frontend est compilé automatiquement dès le premier démarrage).

Limites de plateformes : Windows natif et WSL2

D’après le guide Windows (Native), une installation native sous Windows prend en charge les pages de configuration, les métriques, les tâches et la base de données des sessions. En revanche, l’onglet de terminal intégré /chat dépend des pseudo-terminaux POSIX PTY. Cet appel n’étant pas pris en charge dans l’environnement Windows natif, vous devez exécuter l’agent dans WSL2 pour bénéficier de sessions de terminal interactives complètes dans le navigateur.

Il est également essentiel de dissocier les processus : le tableau de bord web et les passerelles de messagerie (messaging gateways pour Telegram, Discord ou d’autres plateformes) fonctionnent comme des démons indépendants. Le lancement de l’interface web n’active pas automatiquement la passerelle de la plateforme correspondante.

Gestion des profils et configuration des modèles

Le tableau de bord opère à l’échelle globale de la machine et administre de manière centralisée l’ensemble des profils configurés. Le sélecteur de profil dans le menu latéral permet de modifier le contexte de travail via le paramètre d’URL ?profile=<nom>.

1. Sections Config et API Keys : La page Config permet de modifier les paramètres du fichier config.yaml, les changements étant enregistrés via le bouton Save. À l’inverse, la page API Keys met à jour les variables d’environnement dans ~/.hermes/.env : les clés sont définies et supprimées individuellement pour chaque variable, sans bouton d’enregistrement global ni validation par lot de l’ensemble des champs.
2. Cohérence du fournisseur et du modèle : Le modèle sélectionné et les identifiants d’accès doivent correspondre strictement au même fournisseur. Lors de l’utilisation d’un service tiers compatible OpenAI, vérifiez scrupuleusement les paramètres du fournisseur en amont : par exemple, les champs requis, les identifiants de modèles et les paramètres de connexion sont décrits dans le guide BetterToken. Un fournisseur tiers fournit uniquement un accès API indépendant aux modèles et n’héberge pas le tableau de bord Hermes ni ne gère les tunnels réseau.
3. Vérification du fonctionnement via Sessions : Pour un test manuel, envoyez une courte instruction en lecture seule. N’oubliez pas que cette requête de test peut être facturée par votre fournisseur. Le succès de l’inférence est confirmé par la réception d’une réponse constructive dans l’interface et l’enregistrement de la consommation de jetons dans les métadonnées de session ou les journaux du fournisseur. La simple apparition d’une nouvelle ligne dans la liste de l’onglet Sessions n’indique que la création de l’enregistrement et ne constitue pas la preuve d’une réponse réussie du modèle.

Accès distant sécurisé

Par défaut, le serveur web écoute exclusivement sur 127.0.0.1. En cas de liaison à des interfaces externes (--host 0.0.0.0), un mécanisme d’authentification (auth gate) est automatiquement activé. Si aucun fournisseur d’authentification n’est configuré, l’agent s’interrompt avec une erreur (fail-closed). L’ancien drapeau obsolète --insecure ne permet plus de contourner l’authentification. Une liaison réseau publique ou externe exige une authentification obligatoire, conformément à la documentation de Hermes Agent.

La méthode recommandée pour se connecter à un serveur distant sans ouvrir de ports publics consiste à utiliser la redirection de port local via un tunnel SSH (remplacez user@your-server par l’adresse et le nom d’utilisateur de votre serveur distant) :

ssh -N -L 9119:127.0.0.1:9119 user@your-server

Si le port local 9119 est déjà occupé par un autre processus sur votre poste de travail, utilisez une variante avec un port local alternatif :

ssh -N -L 9120:127.0.0.1:9119 user@your-server

Avec cette approche, le serveur Hermes sur la machine distante continue d’écouter strictement sur l’interface locale 127.0.0.1, le trafic est chiffré par le tunnel SSH, et le tableau de bord est accessible depuis votre poste à l’adresse http://127.0.0.1:9119 (ou http://127.0.0.1:9120 si vous avez redéfini le port local).

Diagnostic méthodique des pannes

En cas d’erreur, il est essentiel d’isoler la couche défaillante plutôt que de tester l’ensemble de la chaîne technique d’un seul bloc.

+----------------------------------------------------------------+
| 1. HTTP-транспорт      | 127.0.0.1:9119 /api/status            |
+------------------------+---------------------------------------+
| 2. Окружение и PTY     | Node.js / POSIX ptyprocess (WSL2)     |
+------------------------+---------------------------------------+
| 3. Сокеты и каналы     | /api/pty (Chat) / /api/ws (Desktop)   |
+------------------------+---------------------------------------+
| 4. Провайдер инференса | Ключи API, лимиты и сетевой эндпоинт  |
+----------------------------------------------------------------+

Les couches de diagnostic présentées dans l’arbre de décision ci-dessus correspondent à :

• Couche 1 (Transport HTTP) : 127.0.0.1:9119 /api/status
• Couche 2 (Environnement et PTY) : Node.js / POSIX ptyprocess (WSL2)
• Couche 3 (Sockets et canaux) : /api/pty (Chat) / /api/ws (Desktop)
• Couche 4 (Fournisseur d’inférence) : clés API, quotas et point de terminaison réseau

1. Couche réseau (HTTP) : La disponibilité de GET /api/status prouve uniquement que le processus Uvicorn est en cours d’exécution et répond aux requêtes HTTP. Ce point de terminaison non authentifié ne garantit pas la réussite de l’authentification ni la disponibilité de l’interface de discussion interactive.
2. Couche PTY et interface : Une erreur Connection closed peut avoir plusieurs causes distinctes. Dans un environnement Windows natif, l’une des causes diagnostiques principales est l’absence de prise en charge de POSIX PTY (auquel cas l’exécution doit être transférée sous WSL2). Sur les autres plateformes, ce symptôme ne se limite pas à PTY et exige d’inspecter les journaux système ainsi que la connexion socket. Les problèmes d’écran blanc ou d’erreurs de compilation des styles nécessitent de vérifier la version de Node.js et de recompiler les dépendances du frontend.
3. Canaux de sockets et autorisation : Le terminal intégré au navigateur communique via /api/pty, tandis que le client Desktop distant se connecte via /api/ws. Si le client signale que le backend est accessible mais que les sessions ne répondent pas, vérifiez la connexion du canal correspondant : les pannes proviennent souvent de tickets de session absents ou expirés, ou d’un blocage par la protection contre le re-routage DNS (DNS rebinding) lorsqu’il y a discordance entre l’en-tête Host et l’adresse de liaison.
4. Couche du fournisseur de modèle : Une latence excessive ou l’apparition de messages d’erreur après l’envoi d’une requête dans un terminal actif provient généralement du niveau de l’API (clé invalide dans .env, point de terminaison du fournisseur inaccessible, quotas épuisés ou solde insuffisant). Toutefois, les erreurs du fournisseur ne prouvent pas que le serveur du tableau de bord soit lui-même totalement opérationnel : en cas de défaillance, il peut également être nécessaire de vérifier l’état de l’environnement d’exécution (runtime) et le cycle de vie de la session.