Donnez à Hermes Agent un accès SSH à vos serveurs sans lui confier de clé

15 oct. 2026 · Termalin Team ai-agentsmcpsshsecuritytutorial

Hermes Agent exécute déjà des commandes shell sur une machine distante. Son backend de terminal SSH pointe vers un seul hôte et lance chaque commande par ssh. C’est très bien pour un serveur unique. Dès que vous en avez plus d’un, ou que vous ne voulez pas d’une clé privée posée sur la machine qui fait tourner l’agent, le backend n’est pas le bon outil. La configuration plus propre consiste à relier Hermes à un serveur MCP distant qui atteint vos serveurs à sa place — aucune clé sur la machine de l’agent, plusieurs hôtes, des règles par connexion et un journal d’audit. Cet article traite les deux : comment le backend SSH fonctionne aujourd’hui, et comment brancher Termalin à la place comme serveur MCP.

Transparence : nous développons Termalin. Les détails sur Hermes Agent ci-dessous proviennent de sa documentation publique et de son suivi de tickets, consultés le 15 octobre 2026.

Comment Hermes Agent utilise SSH aujourd’hui

Hermes Agent exécute ses outils via un backend de terminal. L’un de ces backends est SSH. Vous le définissez dans ~/.hermes/config.yaml :

terminal:
  backend: ssh

Les identifiants vont dans ~/.hermes/.env :

TERMINAL_SSH_HOST=my-server.example.com
TERMINAL_SSH_USER=ubuntu

TERMINAL_SSH_PORT vaut 22 par défaut, et TERMINAL_SSH_KEY est un chemin vers une clé privée (la clé par défaut du système est utilisée si vous le laissez vide). La documentation décrit le mécanisme sans détour : il « exécute des commandes sur un serveur distant via SSH », réutilise la connexion avec ControlMaster et un keepalive de 5 minutes en inactivité, et chaque commande est un nouveau ssh … bash -c.

Trois faits découlent de cette conception, et ce sont eux qui poussent les gens à chercher autre chose :

Un backend, c’est un hôte. TERMINAL_SSH_HOST et TERMINAL_SSH_USER sont tous deux obligatoires, et le backend n’a aucun inventaire multi-hôtes. Pour travailler sur un second serveur, vous le reconfigurez.
Une clé privée réside sur la machine Hermes, soit en tant que fichier, soit via le ssh-agent du système. Tout ce qui peut lire cette machine peut utiliser la clé, et la clé ouvre chaque hôte qui lui fait confiance.
Hermes copie ses propres identifiants sur la machine distante. La documentation note que pour les backends SSH, Modal et Daytona, Hermes pousse l’état de votre ~/.hermes/ — fichiers d’identifiants, skills, cache — dans le bac à sable distant le temps de la session, et resynchronise les fichiers d’état modifiés au démontage.

La documentation avance tout de même un argument valable en faveur du backend SSH : comme l’agent tourne sur une autre machine, il « ne peut pas modifier son propre code ». Cette isolation est réelle, et nous y revenons plus bas.

Les problèmes que l’on rencontre

Le suivi de tickets de hermes-agent présente un ensemble reconnaissable de tickets ouverts autour de ces chemins SSH. Cités par numéro, sans surinterpréter ce que chacun signifie pour vous :

Le backend SSH échoue avec « path too long for Unix domain socket » quand vous utilisez des profils nommés (#133436).
/reload ne vide pas les environnements SSH en cache après un changement de configuration (#71085).
Le mode SSH de l’application de bureau a son propre lot : une sonde macOS qui échoue environ une seconde après le démarrage (#80836), et des blocages et dépassements de délai d’OpenSSH sous Windows (#118983, #138378, #127320).
Une tempête de tentatives au démarrage, de l’ordre de 25 connexions SSH par minute (#134197).
hermes update échoue sur les réseaux qui bloquent le port 22 (#133439).

Certains concernent l’application de bureau plutôt que le backend, et certains pourraient déjà être résolus au moment où vous lisez ces lignes. C’est le motif d’ensemble qui compte : le backend SSH est une fine enveloppe autour d’une seule connexion ssh, il hérite donc de chaque aspérité de cette connexion — y compris le besoin que le port 22 soit joignable.

Une alternative sans clé : Termalin comme serveur MCP distant

Hermes Agent prend en charge MCP. Il peut dialoguer avec des serveurs stdio et des serveurs HTTP distants, avec un en-tête Bearer ou OAuth. C’est l’ouverture. Au lieu de donner à l’agent une clé et un seul hôte, vous le pointez vers un serveur MCP distant qui sait déjà atteindre votre parc.

Termalin est un client SSH doté d’un serveur MCP hébergé. Chaque serveur que vous voulez rendre joignable fait tourner un Connector — une installation en une ligne qui appelle vers l’extérieur et n’écoute jamais sur un port, si bien qu’il fonctionne derrière un NAT et un CGNAT, et que le port 22 n’a pas besoin d’être ouvert. À l’inscription, le sshd du serveur fait confiance à l’autorité de certification SSH de Termalin. Chaque connexion utilise ensuite un certificat à courte durée limité à votre compte. Aucune clé durable ne se trouve sur la machine, et aucune n’est remise à l’agent.

Les serveurs MCP se placent sous la clé de premier niveau mcp_servers dans ~/.hermes/config.yaml. Il y a deux façons de s’authentifier. Sur un VPS — l’endroit habituel où tourne Hermes — la clé API est plus simple, commencez donc par là.

Option A — clé API (idéale sur un VPS)

Créez une clé API dans l’espace web de Termalin, limitez son périmètre aux serveurs que cet agent doit toucher, mettez-la en lecture seule ou sur une liste de commandes autorisées, et donnez-lui une expiration. Placez-la dans ~/.hermes/.env :

TERMALIN_API_KEY=tk_live_your_key_here

Puis ajoutez le serveur. Hermes résout les références ${VAR} au moment de la connexion au serveur, y compris dans headers :

# ~/.hermes/config.yaml
mcp_servers:
  termalin:
    url: "https://termal.in/api/v1/mcp"
    headers:
      Authorization: "Bearer ${TERMALIN_API_KEY}"

Vérifiez la connexion, puis rechargez MCP dans une session :

hermes mcp test termalin

/reload-mcp

Le Streamable HTTP est le transport par défaut pour les serveurs url, et c’est ce que parle termal.in, vous n’avez donc pas besoin d’une ligne transport:.

Option B — connexion OAuth (pour un portable)

Si Hermes tourne sur votre propre machine avec un navigateur, OAuth évite de stocker une clé :

# ~/.hermes/config.yaml
mcp_servers:
  termalin:
    url: "https://termal.in/mcp"
    auth: oauth

hermes mcp login termalin

À la première connexion, Hermes affiche une URL d’autorisation, ouvre votre navigateur quand il le peut, et attend le rappel OAuth sur un port loopback local. La connexion de Termalin accepte cette redirection en loopback (http://127.0.0.1:<port>/callback), donc auth: oauth fonctionne de notre côté.

Sur un VPS sans affichage, le rappel en loopback ne peut pas joindre votre portable. Deux contournements fonctionnent avec Termalin : coller l’URL de redirection dans l’invite de Hermes, ou rediriger le port avec ssh -N -L <port>:127.0.0.1:<port> user@host et terminer la connexion dans le navigateur de votre portable. Hermes propose aussi un flux par code d’appareil (device code), mais la connexion de Termalin ne l’offre pas — sur un serveur, la clé API de l’Option A est la voie la plus simple.

Ce que vous obtenez une fois connecté

Après hermes mcp test termalin (ou hermes mcp login termalin) et /reload-mcp, les outils de Termalin apparaissent pour l’agent : hosts_list pour voir quels serveurs il peut atteindre, ssh_exec et ssh_exec_many pour exécuter des commandes sur un ou plusieurs, sftp_list / sftp_read / sftp_write pour les fichiers, server_metrics et alerts_list pour la santé, et job_start / job_status / job_stop / job_list pour les tâches qui survivent à un seul appel.

Les différences pratiques avec le backend SSH :

Plusieurs serveurs à la fois. ssh_exec_many exécute la même commande sur un ensemble d’hôtes. Pas de limite à un seul hôte, ni de reconfiguration pour changer de machine.
Des règles par connexion. Dans la carte « Applications d’IA », vous définissez une politique de commandes pour cette connexion : accès complet, une liste de commandes autorisées, ou lecture seule. Commencez en lecture seule, élargissez ensuite.
Un journal d’audit. Chaque commande que l’agent exécute est marquée comme la sienne, enregistrée et affichée dans la grille de surveillance en direct. « L’agent a fait ceci » est un filtre, pas une reconstitution. Voyez l’audit de ce que fait un agent (en anglais).
Des tâches en arrière-plan. Une longue migration ou un long build s’exécute comme une tâche, de sorte qu’une opération lente ne bloque pas la session ni ne se heurte à un délai fixe.
Aucun port ouvert. Le Connector appelle vers l’extérieur, ce qui contourne aussi la catégorie de problèmes « port 22 bloqué ».

Révoquer l’accès tient en un interrupteur, pas en une rotation de clés sur chaque hôte. Pour le raisonnement derrière ce compromis, voyez pourquoi ne pas confier votre clé SSH à un agent et le rayon d’impact (en anglais).

Quand garder plutôt le backend SSH

Ce n’est pas un cas où une option l’emporte sur toutes les lignes.

Si vous avez exactement une machine, que vous gardez déjà une clé sur la machine Hermes et que vous ne voulez rien d’autre dans la boucle, le backend SSH est le moins à configurer.
L’argument d’isolation de la documentation tient : tourner sur un hôte séparé signifie que l’agent ne peut pas modifier son propre code. La voie MCP conserve aussi cette propriété, puisque les commandes s’exécutent sur vos serveurs, pas sur la machine de l’agent — mais si le backend SSH vous donne déjà cela et que rien de plus n’est nécessaire, il n’y a aucune raison de changer.
Les outils MCP et de supervision de Termalin nécessitent un forfait Pro (10 $/mois, ou 8 $/mois facturé annuellement — 96 $/an), ou l’essai de 14 jours, et un Connector sur chaque serveur. Une clé seule et le backend SSH ne coûtent rien.

Utilisez Termalin quand vous avez plusieurs serveurs, quand vous ne voulez pas de clé sur la machine de l’agent, quand les serveurs sont derrière un NAT, ou quand vous avez besoin de règles par connexion et d’une trace d’audit. Gardez le backend SSH quand une clé sur un hôte est vraiment tout ce dont vous avez besoin.

Dépannage

Les outils n’apparaissent pas. Lancez hermes mcp test termalin, confirmez que l’url est correcte et que TERMALIN_API_KEY est défini dans ~/.hermes/.env. Puis /reload-mcp dans la session.
401 de l’endpoint. La clé API est absente, incorrecte ou expirée. Créez-en une nouvelle dans l’espace web et mettez à jour ~/.hermes/.env.
La référence ${TERMALIN_API_KEY} est envoyée telle quelle. Hermes développe ${VAR} au moment de la connexion ; vérifiez que la variable est dans ~/.hermes/.env (ou dans le shell qui a lancé Hermes) et reconnectez-vous.
L’OAuth n’aboutit jamais sur un VPS sans affichage. Le rappel en loopback ne peut pas joindre votre portable. Redirigez le port avec ssh -N -L <port>:127.0.0.1:<port> user@host, ou collez l’URL de redirection dans l’invite. Sur un serveur, la voie par clé API est plus simple.
Mauvais transport. Les serveurs url utilisent le Streamable HTTP par défaut, ce qu’emploie termal.in. Ne mettez transport: sse que pour les serveurs qui ne parlent que le SSE — pas celui-ci.

Questions fréquentes

Hermes Agent prend-il en charge MCP ? Oui. Il se connecte à des serveurs stdio et à des serveurs HTTP distants, avec un en-tête Bearer ou OAuth, configurés sous mcp_servers dans ~/.hermes/config.yaml.

Puis-je l’utiliser avec Hermes Agent sur un VPS ? Oui, et la voie par clé API y est la plus facile. Le flux OAuth exige un navigateur ou l’un des contournements sans affichage ci-dessus.

Dois-je ouvrir un port sur mes serveurs ? Non. Le Connector appelle vers l’extérieur, il fonctionne donc derrière un NAT et un CGNAT sans aucun port entrant. Voyez SSH derrière un NAT (en anglais).

Ma clé SSH est-elle donnée à l’agent ? Non. Les serveurs sont atteints avec des certificats à courte durée émis à chaque connexion. Aucune clé durable ne quitte Termalin, et aucune n’est placée dans l’environnement de l’agent.

Termalin est un client SSH multiplateforme avec un serveur MCP hébergé, un gardien des clés et une politique d’agent par hôte. Vous utilisez un autre agent ? La même configuration sans clé fonctionne pour OpenClaw, Codex (en anglais) et d’autres — ou téléchargez l’app pour commencer.