Otro proceso está moviendo tu dashboard de Hermes — y ahora un comando te dice cuál


La semana pasada abriste localhost:8080 y el dashboard listaba sesiones que no reconocías. ps aux | grep hermes devolvió tres procesos: dos con --profile y uno que venía de un contenedor. Recuerdas vagamente haber copiado una unit de systemd de la documentación el invierno pasado, luego haber probado Docker Compose, y que Desktop arrancó un backend SSH en algún punto intermedio. La pregunta es sencilla y casi imposible de responder de memoria: ¿cuál sigue corriendo, a qué instalación sirve, y cuál tocaría si quisiera ordenar el desastre?

Hasta ahora esa pregunta se contestaba adivinando. hermes gateway migrate existe para consolidar los gateways de cada perfil en un único gateway de host; nunca prometió inventariar los servicios en segundo plano que quedaron dando vueltas en la máquina. El nuevo flag que se fusionó en main después de la v0.23.1 cubre justamente ese hueco: hermes gateway migrate --backends, un comando que solo reporta.

Seamos precisos sobre lo que no hace, porque hace muy poco: no detiene, reinicia ni mata nada. No escribe ningún service file, unit, plist ni registro. No abre ninguna conexión de red. La migración de backends en sí no está implementada — cada registro termina con el mismo aviso: Report only: changes no service; backend migration is not available yet.

Por qué tiene que mirar sin tocar

Un poco de contexto. Hermes jamás instala un servicio en segundo plano para hermes serve o hermes dashboard. Todos los backends que encuentres en una máquina los puso otra cosa: una unit de systemd copiada de la documentación, un plist de launchd escrito a mano, la unit hermes-backend de NixOS o Home Manager, el slot longrun dashboard de s6 en la imagen Docker, un sidecar de Compose, un backend SSH de Desktop, o un proceso que arrancaste una tarde en una terminal y nunca cerraste.

Eso genera una situación incómoda. La única fuente confiable para saber cuántos backends hay y de quién son es lo que el proceso realmente ejecuta y a qué unit pertenece su MainPID — nunca el nombre de la unit. Nix la llama hermes-backend; la copia que hiciste de la documentación puede llamarse hermes-serve.service; dentro del contenedor es el nombre de un slot. Si emparejas por nombre, se te van a escapar cosas seguro.

Por eso la recolección es deliberadamente acotada: corre ps, lee /proc y plists, y lanza consultas systemctl show / list-unit-files y launchctl print. Nada más. A propósito no lee el spawn ledger, porque leer un ledger corrupto lo pone en cuarentena (lo renombra), y un informe de solo lectura no debería tener ese efecto colateral.

Hay un detalle fácil de pasar por alto: el arranque normal de Hermes igual corre primero — crea la estructura de HERMES_HOME, escribe un SOUL.md por defecto cuando falta, registra la instalación en HERMES_HOME/installs/<id>/, abre logs/agent.log y logs/errors.log, y limpia cache/scratch. Así que no está libre de efectos secundarios; simplemente ocurren dentro de los propios directorios de Hermes y nunca tocan servicios del sistema operativo.

Cómo se usa: dos invocaciones y una forma JSON

hermes gateway migrate --backends            # reporte legible para humanos
hermes gateway migrate --backends --json     # el mismo reporte en JSON

El ejemplo de la documentación también incluye --dry-run, que en modo reporte no aporta nada — el comando no cambia nada en ningún caso y tampoco rechaza el flag.

La salida de texto se ve así (formato tomado 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.

El JSON es un wrapper fijo:

{
  "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 siempre es false. No es un placeholder olvidado: los maintainers sacaron del output un campo de recomendaciones de migración porque el diseño del servicio de migración no está aprobado. El reporte solo declara hechos presentes — no hay clave de consejos ni clave would.

Qué significan realmente los campos

Los dos campos que vale la pena leer son supervisor y notes, porque responden a “quién se encarga de mantener vivo este proceso”:

supervisor Significado
systemd La unit se escribió a mano (Hermes nunca instala una)
nix-systemd El archivo de unit lo genera Nix y es de solo lectura
launchd El plist se escribió a mano
nix-launchd El plist lo genera Nix y es de solo lectura
s6 El slot lo declara la imagen del contenedor
container El proceso pertenece a un archivo Compose o a un docker run
desktop-ssh / desktop-local Lo posee una sesión SSH de Desktop o la app Desktop
detached Ningún supervisor lo posee
manual Se arrancó desde una shell u otro programa
unknown No se pudo identificar su supervisor

hermes_home y this_home resuelven la otra mitad de la confusión. Un mismo usuario puede tener varias instalaciones y varios perfiles, y el servicio que está corriendo no necesariamente sirve el HERMES_HOME en el que estás parado. El reporte marca (this HERMES_HOME) para que veas de un vistazo si ese backend es el que estás usando.

Detección: por lo que ejecuta, después por cómo se llama

Los backends en ejecución se encuentran por su línea de comandos, así que una unit llamada foo.service que resulta ejecutar hermes serve igual aparece en la lista.

Las units habilitadas pero detenidas en este momento solo se listan cuando su nombre coincide con uno de tres patrones: hermes-serve*, hermes-dashboard*, hermes-backend*. Eso replica la pasada de systemd de hermes update, que también cubre solo esos tres prefijos (incluida la unit hermes-backend.service de Nix). Los nombres que quedan fuera no los toca ninguno de los dos comandos.

Hay un detalle de macOS que conviene conocer: un proceso arrancado por el launcher backend.waitFor de Nix conserva la propiedad de launchd y el home de su plist. Un proceso ppid-1 que no coincide con nada se queda como unknown en lugar de clasificarse como detached. Dicho de otro modo, prefiere decir “no sé” antes que darte una respuesta equivocada.

Para qué sirve y para qué no

Hay tres usos que se sostienen:

  1. Inventario antes de limpiar. Antes de borrar una unit que quedó por ahí, corre esto una vez y confirma qué HERMES_HOME sirve, para no eliminar la instalación que todavía usas.
  2. Depurar instalaciones viejas. Si el dashboard muestra sesiones que no cuadran con tu máquina, probablemente estés hablando con el backend del contenedor y no con este.
  3. Scripts de operación de solo lectura. --json más applied: false lo hacen seguro para meterlo en un script de monitoreo: código de salida 0 incluso cuando falla un escaneo, y ninguna posibilidad de que una sonda modifique la máquina.

Lo que no va a hacer:

  • No va a migrar nada. No existe --apply ni salida de recomendaciones. Consolidar dos gateways por perfil en un gateway de host sigue siendo el simple hermes gateway migrate (--multiplex, que hermes update ejecuta por ti); --backends es un reporte aparte.
  • Rechaza --yes y --multiplex. El comando sale con código 2 y el mensaje “--backends is a read-only report”, para que nadie lo confunda con una migración.
  • No cambia hermes update. Las units fuera de esos tres prefijos siguen fuera del alcance de hermes update.

Estado: en main, no en v0.23.1

El PR #152245 se fusionó el 2026-11-10 a las 15:40 UTC, mientras que el tag v0.23.1 apunta a un commit del 11-10 a las 00:24 UTC — casi un día antes. Por lo tanto:

  • en v0.23.1 o cualquier versión anterior, hermes gateway migrate --backends es un flag desconocido y el comando todavía no existe;
  • en una instalación desde código fuente que siga main, funciona hoy.

Actualización (17/11/2026): estos cambios salieron en la v0.23.2 (16 de noviembre): hermes update los trae. Lo de «no está en la v0.23.1» es una foto del momento de la publicación.

Si quieres profundizar en la capa de gateway, la referencia del comando gateway cubre toda la superficie, y dos notas anteriores van más a fondo en la misma frontera: ajustar el watchdog del loop del gateway y cómo Desktop guarda las conexiones de gateway. Si manejas varios perfiles, la nota sobre la allowlist de perfiles plantea la misma pregunta sobre dónde está el límite.

Un comando de solo lectura no es emocionante. Pero “cuántos backends están corriendo en esta máquina” antes se respondía entrecerrando los ojos frente a systemctl list-units y adivinando. Ahora hay algo que leer.