Hermes Agent y Syncthing: gateway, Telegram y sincronización

Hermes Agent y Syncthing al Instante

Conectar servicios externos suele costar más de lo que debería: recordar rutas, exportar variables de entorno, reparar servicios rotos y comprobar a mano si el proceso sigue vivo. Los scripts hermes-connect y [[syncthing-solucion-segura-abierta|syncthing]]-connect reducen todo eso a un comando, con diagnóstico incluido.

Este proyecto escribe artículos en un vault de Obsidian y los sincroniza con el móvil. Ahora el agente que redacta es Hermes Agent, al que puedes escribirle directamente por Telegram desde cualquier lugar.

Antes había que recordar la ruta exacta de cada servicio, arreglar servicios launchd rotos a mano y comprobar con ps si algo seguía vivo. Cada paso era una oportunidad de equivocarse.

El enfoque actual concentra el ciclo de vida completo en un solo archivo por servicio:

Detección automática — encuentra el binario o el intérprete sin que se lo digas
Diagnóstico previo — informa qué falta antes de fallar con un error críptico
Reparación automática — arregla servicios obsoletos al arrancar
Gestión de estado — guarda el PID, escribe logs y limpia tras un cierre

Los scripts se apoyan en una librería compartida (scripts/sh/lib/common.sh) que evita duplicar código de colores, lectura de .env y gestión de procesos.

Aquí está el cambio de fondo. Antes Telegram lo atendía un bot propio que llamaba a un script generador. Ahora lo sirve el gateway de Hermes Agent: al escribir al bot hablas con el agente, con acceso a sus skills, memoria y herramientas.

npm run hermes                 # arrancar
npm run hermes -- check        # diagnóstico
npm run hermes -- status
npm run hermes -- logs

Antes (bot propio)	Ahora (gateway de Hermes)
Un script que generaba texto	El agente completo, con razonamiento
Sin acceso a las reglas del vault	Lee `AGENTS.md` y las reglas del repo
Categorías inventadas	Usa la skill `markeup-post-creator`
Wikilinks que no pasaban el linter	Valida con `npm run validate:wikilinks`
Solo texto	Voz, imágenes, archivos, memoria
Código propio que mantener	Lo mantiene Hermes

La configuración vive una sola vez en ~/.hermes/.env:

Variable	Contenido
`TELEGRAM_BOT_TOKEN`	Token del bot (de @BotFather)
`TELEGRAM_ALLOWED_USERS`	IDs de Telegram autorizados

⚠️ Telegram solo admite un proceso por bot. Si arrancas otro bot con el mismo token, el gateway se cae con Conflict: terminated by other getUpdates. Por eso el token ya no está duplicado en el .env del repo: hay una sola fuente. El comando check detecta este conflicto antes de que ocurra.

Este es el detalle que más tiempo ahorra. Hermes instala un servicio launchd que guarda la ruta absoluta de su intérprete. Si el proyecto se mueve de sitio, esa ruta deja de existir y el servicio falla en silencio.

El script lee el plist, comprueba si la ruta del ejecutable sigue existiendo y, si no, reinstala el servicio por su cuenta:

npm run hermes
# ⚠ El servicio apunta a una ruta que ya no existe. Reparándolo…
# ✓ Servicio reinstalado y arrancado (inicio automático activo)
# ✓ Gateway operativo

Para que el agente conozca las normas del repositorio existe un AGENTS.md en la raíz. Ahí está lo que no puede adivinar: cuáles son las 5 categorías válidas, la Regla de Oro de los wikilinks (alias obligatorio), los 21 campos del frontmatter y qué comandos ejecutar tras editar contenido.

Syncthing sincroniza la carpeta de contenido entre el Mac y el móvil. El script se adapta a cómo esté instalado, que es su principal ventaja.

npm run syncthing              # detectar y arrancar
npm run syncthing -- check     # diagnóstico
npm run syncthing -- id        # Device ID de este Mac
npm run syncthing -- folder    # carpeta y pasos

El binario puede estar en cuatro sitios distintos. El script los prueba en orden y funciona igual en todos los casos:

Prioridad	Ubicación	Caso típico
1	`PATH`	Instalación manual o enlace simbólico
2	`/Applications/Syncthing.app`	App de escritorio de macOS
3	`/opt/homebrew/bin`	Homebrew en Apple Silicon
4	`/usr/local/bin`	Homebrew en Intel

Cuando detecta una instalación de Homebrew, delega el arranque en brew services. Si es la app de macOS, lanza la GUI con open -a. El resultado es el mismo comando en ambos escenarios.

Aquí está la diferencia clave: no basta con que el proceso exista. Un proceso puede estar vivo y la interfaz caída. Por eso el script consulta la API REST para confirmar que responde de verdad.

Estado	Significado
`OPERATIVO`	El proceso vive y la interfaz responde
`ARRANCANDO`	Hay proceso, pero la API aún no contesta
`DETENIDO`	Sin proceso

Esta distinción evita el fallo más frustrante: que el script diga «ya está corriendo» mientras tú ves la web caída. Cuando detecta el estado ARRANCANDO, espera de forma activa en lugar de devolver un falso negativo inmediato.

La app de macOS puede tardar 1-2 minutos en levantar la interfaz la primera vez (arranque de la GUI + generación de claves + indexado). El script espera hasta 120 segundos y te avisa de que es normal.

El paso que más dudas genera es conseguir el ID del dispositivo. En lugar de navegar por menús, id lo extrae de la API REST o del archivo de configuración:

npm run syncthing -- id
# OFNESLT-FQDWUTG-IL2KZ4T-SFJJIYC-V5GYB3A-Q6DW3V2-EWIB2E7-AK73GQE

El comando folder completa el proceso mostrando la ruta exacta a compartir y los pasos siguientes. Es la información que antes había que buscar en la guía de instalación.

Nota de seguridad: install nunca se ejecuta solo. Siempre pide confirmación explícita antes de lanzar brew install.

Los dos scripts comparten una estructura de mando predecible, así que aprender uno es aprender el otro.

Comando	Hermes	Syncthing
Sin argumento	Arranca Hermes + Telegram	Detecta y arranca
`check`	Binario, token, skills, conflictos	Binario, config, proceso, API
`status`	Gateway, Telegram, servicio	Estado real + Device ID
`stop` / `restart`	Detiene / reinicia	Detiene / reinicia
`logs`	Log del gateway	—
`id` / `folder`	—	Identidad y carpeta

Cada script acepta help (o -h) y muestra su propia referencia. También puedes invocarlos directamente si prefieres no pasar por npm:

./scripts/sh/hermes-connect.sh help
./scripts/sh/syncthing-connect.sh help

Los scripts devuelven código distinto de cero cuando algo falla. Es un detalle pequeño con consecuencias grandes: permite encadenar comandos, detectar problemas desde otros scripts o fallar correctamente en CI.

npm run hermes -- check || echo "hay algo que arreglar"

Síntoma	Causa probable	Solución
`The token was rejected by the server`	Token revocado o incorrecto	Genera otro con @BotFather y `npm run hermes -- setup`
`Conflict: terminated by other getUpdates`	Dos procesos con el mismo bot	`npm run hermes -- check` y para el otro
El gateway no arranca	Ruta obsoleta en el servicio	`npm run hermes` (se repara solo)
Telegram no responde	Fallo de conexión con la API	`npm run hermes -- logs`
Syncthing no aparece	No está instalado	`npm run syncthing -- install`
Dice `DETENIDO` y no arranca	App de macOS sin daemon activo	`npm run syncthing` lo reinicia sola
No sincroniza el móvil	Folder ID distinto	`npm run syncthing -- folder`

La ganancia real no está en escribir menos, sino en fallar mejor. Un diagnóstico que señala la causa concreta ahorra más tiempo que un comando corto que falla en silencio.

El cambio de fondo va más allá de los scripts: al delegar Telegram en Hermes, el agente que te responde conoce las reglas del repositorio. Ya no inventa categorías ni produce enlaces que rompen el build, porque tiene las mismas normas que aplicamos al escribir a mano.

Si trabajas con servicios externos —agentes, sincronización, túneles—, el patrón se traslada bien: un script por servicio, una librería común, y el ciclo de vida completo en un solo sitio. El árbol de scripts organiza todo por extensión (sh, py, js, mjs), así que encontrar el archivo correcto es inmediato.

Para el detalle de cada flag y su efecto, la referencia está en la documentación de operación.

Hermes Agent y Syncthing

Hermes Agent y Syncthing: gateway, Telegram y sincronización

Scripts Connect: Hermes Agent y Syncthing al Instante

Posts que enlazan a este artículo

Hermes Agent y Syncthing al Instante