Agent Hermes : Configuration d’un serveur headless et d’un bureau à distance
Serveur Headless Hermes avec accès à un bureau à distance
Exécuter l’agent Hermes sur un serveur sans interface graphique (headless) tout en se connectant depuis un client de bureau sur une autre machine nécessite deux processus serveur et une seule connexion client.
L’architecture sépare le backend Hermes en deux processus côté serveur et une surface client côté client. Le backend hermes serve gère les connexions API et tableau de bord, tandis que le processus hermes gateway run gère les canaux de messagerie indépendamment. Le client de bureau se connecte au backend serve, et non au gateway.
--host 0.0.0.0
:9119"] gateway["hermes gateway run
Telegram, Discord, Slack"] end subgraph Client["PC DE BUREAU"] desktop["hermes desktop
(connexion WebSocket)"] end desktop <--->|WebSocket| serve gateway -.->|Partage ~/.hermes/| serve
Deux processus sur le serveur, une application sur le client. Les deux processus serveur partagent la même configuration ~/.hermes/, les compétences (skills), la mémoire et les sessions. Les tâches Cron s’exécutent sur le serveur où le gateway fonctionne.
Pour l’installation, la configuration du fournisseur et la configuration initiale, commencez par Hermes AI Assistant — Installation, Configuration, Flux de travail et Dépanage.
Configurer le serveur sans interface graphique
1. Configurer l’authentification
L’authentification de base offre une protection suffisante pour un LAN de confiance. Ajoutez les identifiants au fichier environnement :
cat >> ~/.hermes/.env << 'EOF'
HERMES_DASHBOARD_BASIC_AUTH_USERNAME=admin
HERMES_DASHBOARD_BASIC_AUTH_PASSWORD=choose-a-strong-password
HERMES_DASHBOARD_BASIC_AUTH_SECRET=$(openssl rand -base64 32)
EOF
chmod 600 ~/.hermes/.env
Le fichier .env réside à côté de config.yaml sous ~/.hermes/. Hermes résout la configuration avec les remplacements CLI en premier, puis config.yaml, puis .env, puis les valeurs par défaut intégrées. Les secrets appartiennent à .env.
2. Démarrer le backend
Exécutez le backend serve sur toutes les interfaces :
hermes serve --host 0.0.0.0 --port 9119
Le backend écoute sur le port 9119 et accepte les connexions WebSocket du client de bureau. Vérifiez qu’il est en cours d’exécution avec un contrôle de statut rapide :
curl -s http://localhost:9119/api/status | jq '.auth_required, .auth_providers'
# Attendu : true "basic"
3. Exécuter en tant que service systemd
Pour un serveur persistant qui survit aux redémarrages, installez un service systemd au niveau de l’utilisateur. Créez le fichier d’unité à /etc/systemd/user/hermes-serve.service :
[Unit]
Description=Backend Serve de l'Agent Hermes
[Service]
EnvironmentFile=%h/.hermes/.env
ExecStart=/home/rg/.hermes/hermes-agent/venv/bin/python -m hermes_cli.main serve --host 0.0.0.0 --port 9119
Restart=on-failure
[Install]
WantedBy=default.target
Rechargez le démon, activez le service et démarrez-le :
systemctl --user daemon-reload
systemctl --user enable hermes-serve
systemctl --user start hermes-serve
Vérifiez le statut du service :
systemctl --user status hermes-serve
4. Démarrer le gateway
Le gateway est un processus séparé qui gère les canaux de messagerie — Telegram, Discord, Slack et autres. Démarrez-le indépendamment :
hermes gateway run
Le gateway et le backend serve sont deux processus distincts. Le gateway gère les sessions, exécute les tâches cron et achemine les messages. Le backend serve fournit la surface API pour les connexions de bureau et du tableau de bord web. Ils partagent le même répertoire personnel mais s’exécutent indépendamment.
Pour la liste complète des commandes et sous-commandes du gateway, consultez la Fiche de référence CLI de l’Agent Hermes. Si votre interface principale est la messagerie mobile, associez cette configuration à Contrôle Vocal Hermes depuis votre Téléphone pour des flux de travail axés sur la voix au-dessus du même processus gateway.
5. Vérifier le backend
Confirmez que le backend répond et que l’authentification est active :
curl -s http://localhost:9119/api/status | jq '.auth_required, .auth_providers'
Sortie attendue :
true
"basic"
Si l’authentification n’est pas activée, la réponse affichera false pour auth_required. Vérifiez que le fichier .env contient les variables correctes et que le service a redémarré après les modifications de configuration.
Se connecter depuis le client de bureau
Option A : Application de bureau Hermes
Installez Hermes Desktop depuis le site officiel. Lancez l’application, accédez à Paramètres → Gateway → Gateway distant, et entrez l’adresse du serveur :
http://<ip-serveur>:9119
Connectez-vous avec le nom d’utilisateur et le mot de passe que vous avez configurés sur le serveur.
Alternativement, définissez l’URL distante via une variable d’environnement :
HERMES_DESKTOP_REMOTE_URL=http://<ip-serveur>:9119 hermes desktop
Option B : Tableau de bord Web
Ouvrez http://<ip-serveur>:9119 dans un navigateur et connectez-vous avec les identifiants d’authentification de base. Le tableau de bord web fournit une interface basée sur le navigateur vers le backend Hermes sans nécessiter d’installation de bureau.
Option C : CLI (Interface en Ligne de Commandes)
Depuis le terminal du PC de bureau, configurez l’URL distante via les paramètres de l’application de bureau ou la variable d’environnement HERMES_DESKTOP_REMOTE_URL. La surface CLI se connecte via le même canal WebSocket que l’application de bureau.
Considérations réseau et sécurité
| Scénario | Recommandation |
|---|---|
| LAN de confiance | --host 0.0.0.0 + authentification de base |
| Exposé à Internet | Utilisez Tailscale (--host <ip-tailscale>) ou un fournisseur OAuth |
| Pare-feu | Ouvrir le port TCP 9119 sur le serveur |
Pour un réseau local de confiance, l’authentification de base sur 0.0.0.0 est adéquate. Si le serveur est exposé à Internet, utilisez Tailscale pour lier à l’IP Tailscale au lieu de 0.0.0.0, ou configurez un fournisseur OAuth pour une authentification plus robuste. Ouvrez toujours le port TCP 9119 dans le pare-feu du serveur lorsque le backend doit accepter des connexions externes.
Distinctions importantes entre les processus
Comprendre la séparation entre les deux processus serveur empêche les erreurs de configuration courantes :
hermes serve— Le backend auquel l’application de bureau et le tableau de bord web se connectent. Gère la surface API et les connexions WebSocket.hermes gateway run— Le processus qui gère Telegram, Discord, Slack et autres canaux de messagerie. Gère les sessions, exécute les tâches cron et achemine les messages.- Ce sont deux processus distincts sur le serveur. Ils partagent la configuration
~/.hermes/, les compétences, la mémoire et les sessions, mais s’exécutent indépendamment. - Les tâches Cron s’exécutent sur le serveur où le gateway est en cours d’exécution.
- Les profils, compétences et mémoire sont configurés côté serveur. Le client se connecte au backend déjà configuré.
Pour une configuration axée sur les profils et des compétences adaptées à différents rôles en production, consultez Compétences de l’Assistant IA Hermes pour des Configurations de Production Réelles.
Dépanage
Le bureau ne peut pas se connecter au serveur
- Vérifiez que le backend est en cours d’exécution :
systemctl --user status hermes-serve - Vérifiez que le port est ouvert :
ss -tlnp | grep 9119 - Testez depuis le serveur :
curl -s http://localhost:9119/api/status - Testez depuis la machine cliente :
curl -s http://<ip-serveur>:9119/api/status - Si le test client échoue, vérifiez les règles du pare-feu :
sudo ufw statusousudo iptables -L
Échec de l’authentification
- Confirmez que le fichier
.enva les permissions correctes :ls -la ~/.hermes/.env(doit être600) - Vérifiez que le secret a été généré :
grep HERMES_DASHBOARD_BASIC_AUTH_SECRET ~/.hermes/.env - Redémarrez le service après les modifications de configuration :
systemctl --user restart hermes-serve
Le gateway ne répond pas aux messages
Le gateway est un processus distinct du backend. Si le bureau se connecte mais que les plateformes de messagerie ne fonctionnent pas :
- Vérifiez le statut du gateway :
hermes gateway status - Démarrez le gateway s’il est arrêté :
hermes gateway start - Consultez les journaux :
hermes logs gateway -f
Références
- Documentation de l’Application de Bureau Hermes Agent
- Guide de Configuration de l’Agent Hermes
- Passerelle de Messagerie de l’Agent Hermes
- Hermes AI Assistant — Installation, Configuration, Flux de travail et Dépanage
- Fiche de référence CLI de l’Agent Hermes — commandes, drapeaux et raccourcis slash
- Compétences de l’Assistant IA Hermes pour des Configurations de Production Réelles
Cet article fait partie du cluster Systèmes IA, qui couvre les assistants auto-hébergés, l’architecture de récupération, l’infrastructure LLM locale et l’observabilité.
