Quelque chose d'autre fait tourner votre dashboard Hermes — et une commande dit enfin quoi


La semaine dernière, vous avez ouvert localhost:8080 et le dashboard a listé des sessions que vous ne reconnaissiez pas. ps aux | grep hermes a renvoyé trois processus : deux avec --profile, un venu d’un conteneur. Vous vous souvenez vaguement d’avoir copié une unit systemd depuis la doc l’hiver dernier, d’avoir essayé Docker Compose ensuite, et Desktop a lancé un backend SSH quelque part entre les deux. La question est simple et presque impossible à trancher de mémoire : lequel tourne encore, à quelle installation sert-il, et lequel toucherais-je si je voulais faire le ménage ?

Jusqu’ici, cette question se réglait à l’estime. hermes gateway migrate existe pour replier les gateway par profile sur une seule gateway d’hôte ; il n’a jamais prétendu inventorier les services d’arrière-plan qui traînent sur la machine. Le nouveau flag fusionné dans main après la v0.23.1 comble ce trou : hermes gateway migrate --backends, une commande qui se contente de rapporter.

Soyons précis sur ce qu’elle ne fait pas, parce qu’elle fait très peu : elle n’arrête, ne redémarre et ne tue rien. Elle n’écrit ni fichier de service, ni unit, ni plist, ni registre. Elle n’ouvre aucune connexion réseau. La migration de backend elle-même n’est pas implémentée — chaque enregistrement se termine par le même avertissement : Report only: changes no service; backend migration is not available yet.

Pourquoi elle doit regarder sans toucher

Voici le contexte. Hermes n’installe jamais de service d’arrière-plan pour hermes serve ou hermes dashboard. Chaque backend présent sur une machine a été monté par quelqu’un d’autre : une unit systemd copiée depuis la doc, un plist launchd écrit à la main, l’unit hermes-backend de NixOS ou Home Manager, le slot longrun s6 dashboard de l’image Docker, un sidecar Compose, un backend SSH de Desktop, ou un processus lancé un après-midi dans un terminal et jamais arrêté.

D’où une situation inconfortable. La seule source de vérité fiable pour « combien de backends existent et à qui appartiennent-ils » est ce que le processus exécute réellement et de quelle unit provient son MainPID — jamais le nom de l’unit. Nix l’appelle hermes-backend ; la copie que vous avez faite depuis la doc s’appelle peut-être hermes-serve.service ; dans le conteneur, c’est un nom de slot. Un rapprochement par nom rate forcément des choses.

La collecte est donc volontairement étroite : elle lance ps, lit /proc et les plists, et interroge systemctl show / list-unit-files ainsi que launchctl print. C’est tout. Elle ne lit délibérément pas le registre de spawn, parce que lire un registre corrompu le met en quarantaine (le renomme), et un rapport en lecture seule ne doit pas produire cet effet de bord.

Un point facile à manquer : le démarrage normal de Hermes s’exécute quand même en premier — il crée l’arborescence HERMES_HOME, écrit un SOUL.md par défaut s’il manque, enregistre l’installation sous HERMES_HOME/installs/<id>/, ouvre logs/agent.log et logs/errors.log, et purge cache/scratch. Donc la commande n’est pas sans effet de bord ; simplement, ces effets restent dans les répertoires de Hermes et ne touchent jamais aux services du système.

L’utiliser : deux invocations et une forme JSON

hermes gateway migrate --backends            # rapport lisible par un humain
hermes gateway migrate --backends --json     # le même rapport en JSON

L’exemple de la doc porte aussi --dry-run, qui n’ajoute rien en mode rapport — la commande ne change rien dans un cas comme dans l’autre, et elle ne rejette pas le flag.

La sortie texte ressemble à ceci (format issu de format_report) :

Serve/dashboard background services (report only; nothing was changed)

• systemd hermes-serve.service (user): PID 41221
    runs:    /root/.hermes/hermes-agent/.venv/bin/python -m hermes_cli serve
    file:    /root/.config/systemd/user/hermes-serve.service
    state:   enabled
    home:    /root/.hermes (this HERMES_HOME)
    report:  Report only: changes no service; backend migration is not available yet.
• container (docker): PID 902
    runs:    python -m hermes_cli serve --host 0.0.0.0 --port 8080
    report:  Report only: changes no service; backend migration is not available yet.
    note:    The process belongs to a container defined by a Compose file or run command.

Le JSON tient dans une enveloppe unique et fixe :

{
  "applied": false,
  "backends": [
    {
      "supervisor": "systemd",
      "running": true,
      "pid": 41221,
      "argv": ["/root/.hermes/hermes-agent/.venv/bin/python", "-m", "hermes_cli", "serve"],
      "unit": "hermes-serve.service",
      "scope": "user",
      "unit_path": "/root/.config/systemd/user/hermes-serve.service",
      "state": "enabled",
      "hermes_home": "/root/.hermes",
      "this_home": true,
      "not_applied": "Report only: changes no service; backend migration is not available yet.",
      "notes": []
    }
  ]
}

applied vaut toujours false. Ce n’est pas un placeholder oublié : les mainteneurs ont retiré de la sortie un champ de conseil de migration, parce que la conception de la migration de service n’est pas encore validée. Le rapport n’énonce que des faits présents — pas de clé de conseil, pas de clé would.

Ce que signifient vraiment les champs

Les deux champs qui valent la lecture sont supervisor et notes, parce qu’ils répondent à la question « qui est responsable du maintien en vie de ce processus » :

superviseur Signification
systemd L’unit a été écrite à la main (Hermes n’en installe jamais)
nix-systemd Le fichier d’unit est généré par Nix et en lecture seule
launchd Le plist a été écrit à la main
nix-launchd Le plist est généré par Nix et en lecture seule
s6 Le slot est déclaré par l’image du conteneur
container Le processus appartient à un fichier Compose ou à un docker run
desktop-ssh / desktop-local Piloté par une session SSH de Desktop ou par l’application Desktop
detached Aucun superviseur ne le possède
manual Lancé depuis un shell ou par un autre programme
unknown Son superviseur n’a pas pu être identifié

hermes_home et this_home répondent à l’autre moitié de la confusion. Un même utilisateur peut avoir plusieurs installations et plusieurs profiles, et le service qui tourne ne sert pas forcément le HERMES_HOME dans lequel vous vous trouvez. Le rapport marque (this HERMES_HOME) pour que vous voyiez d’un coup d’œil si un backend est bien celui que vous utilisez.

Détection : d’abord par ce qu’il exécute, ensuite par son nom

Les backends actifs sont trouvés par leur ligne de commande, donc une unit nommée foo.service qui se trouve lancer hermes serve reste listée.

Les units activées mais actuellement arrêtées ne sont listées que si leur nom correspond à l’un de trois motifs : hermes-serve*, hermes-dashboard*, hermes-backend*. C’est le miroir de la passe systemd de hermes update, qui ne couvre elle aussi que ces trois préfixes (y compris l’unit Nix hermes-backend.service). Les noms en dehors de ces préfixes ne sont touchés par aucune des deux commandes.

Un détail macOS mérite d’être connu : un processus lancé par le launcher backend.waitFor de Nix conserve l’appartenance launchd et son plist d’origine. Un processus orphelin (ppid 1) non reconnu reste unknown au lieu d’être classé detached. Autrement dit, l’outil préfère dire « je ne sais pas » plutôt que de vous donner une mauvaise réponse.

À quoi ça sert, et à quoi ça ne sert pas

Trois usages tiennent la route :

  1. Inventaire avant nettoyage. Avant de supprimer une unit oubliée, lancez la commande une fois et confirmez quel HERMES_HOME elle sert, pour ne pas effacer l’installation que vous utilisez encore.
  2. Débogage d’installation obsolète. Si le dashboard affiche des sessions qui ne correspondent pas à votre machine, vous parlez probablement au backend du conteneur et non à celui-ci.
  3. Scripts d’exploitation en lecture seule. --json plus applied: false la rendent sûre à insérer dans un script de supervision : code de sortie 0, même quand un scan échoue, et aucune chance qu’une sonde modifie la machine.

Ce qu’elle ne fera pas :

  • Elle ne migrera rien. Il n’y a pas de --apply et pas de sortie de conseil. Replier deux gateway par profile sur une gateway d’hôte unique reste un simple hermes gateway migrate (--multiplex, que hermes update lance pour vous) ; --backends n’est qu’un rapport annexe.
  • Elle refuse --yes et --multiplex. La commande sort avec le code 2 et le message « --backends est un rapport en lecture seule », pour que personne ne la prenne pour une migration.
  • Elle ne change pas hermes update. Les units hors de ces trois préfixes restent hors de portée de hermes update.

Statut : sur main, pas dans la v0.23.1

La PR #152245 a été fusionnée le 2026-11-10 à 15:40 UTC, alors que le tag v0.23.1 pointe sur un commit du 11-10 à 00:24 UTC — presque une journée plus tôt. Donc :

  • sur la v0.23.1 ou toute version plus ancienne, hermes gateway migrate --backends est un flag inconnu et la commande n’existe pas encore ;
  • sur une installation depuis les sources qui suit main, elle fonctionne dès aujourd’hui.

Mise à jour (17/11/2026) : ces changements sont sortis dans la v0.23.2 (16 novembre) : un hermes update les récupère. Le « pas dans la v0.23.1 » ci-dessus est un instantané du jour de publication.

Pour creuser la couche gateway, la référence de la commande gateway couvre toute la surface, et deux articles précédents vont plus loin sur la même frontière : régler le watchdog de boucle de la gateway et comment Desktop enregistre les connexions gateway. Si vous faites tourner plusieurs profiles, l’article sur l’allowlist de profile pose la même question de la frontière.

Une commande en lecture seule n’a rien d’excitant. Mais « combien de backends tournent sur cette machine » se répondait jusqu’ici en plissant les yeux sur systemctl list-units et en devinant. Désormais, il y a quelque chose à lire.