Hermes Relay — Connetti le Istanza | Easy Understand Hermes Agent

Pensa a Hermes Relay come a una cabina telefonica che ti richiama — non devi dare il tuo indirizzo di casa, fai una sola chiamata verso l’esterno e dall’altra parte possono raggiungerti in qualsiasi momento attraverso quella stessa linea.

Cos’è Hermes Relay?

Hermes Relay è un sistema di connettori per il gateway Hermes Agent. Permette al tuo gateway di comunicare con piattaforme di messaggistica come Discord, Telegram o Slack senza detenere alcun loro token bot o password.

Invece, un servizio separato (il “connettore”) possiede quelle credenziali. Il tuo gateway si limita a chiamare verso l’esterno il connettore tramite una singola connessione WebSocket sicura — e poi tutti i messaggi fluiscono avanti e indietro attraverso quella linea aperta.

Perché è Utile?

Ecco i vantaggi principali, in parole povere:

Nessuna porta aperta necessaria. Il tuo gateway funziona anche dietro un router di casa o un firewall cloud. Effettua solo connessioni in uscita, quindi non devi esporre nulla su internet.
Nessun segreto bot sulla tua macchina. Il connettore conserva tutti i token delle piattaforme. Se il tuo gateway viene rubato, l’attaccante non ottiene nulla di utile.
Un gateway, molte piattaforme. Il connettore dice al tuo gateway cosa può fare (lunghezza dei messaggi, markdown, modifica, thread, ecc.) nel momento in cui si collegano. Nessuna regola codificata — si adatta e basta.

Quando usarlo: Se gestisci direttamente i tuoi bot, salta Relay e usa gli adattatori nativi (Telegram, Discord). Relay è pensato per configurazioni in cui un connettore condiviso o ospitato gestisce il lato piattaforma — come l’hosting multi-tenant o quando semplicemente non vuoi i token sulla tua macchina.

Come Registrare il Tuo Gateway

La registrazione è una configurazione una tantum. Esegui un singolo comando e Hermes fa il resto.

Prima di tutto, assicurati di avere un token di registrazione (emesso dal tuo fornitore di connettori). Poi esegui:

hermes gateway enroll \
  --token <enrollment-token> \
  --connector-url wss://connector.example.com/relay

Ecco cosa succede passo dopo passo:

Hermes controlla il tuo login esistente (~/.hermes/auth.json) per dimostrare a quale organizzazione appartieni.
Se hai configurato il tuo provider di identità (per configurazioni air-gapped o self-hosted), usa quello invece.
Invia il token di registrazione all’endpoint /relay/enroll del connettore tramite TLS.
Il connettore verifica che il token sia valido, monouso e corrisponda al tuo tenant.
Poi emette un segreto per-gateway e una chiave di consegna — e li restituisce una sola volta.
Hermes li salva in ~/.hermes/.env:

GATEWAY_RELAY_ID
GATEWAY_RELAY_SECRET
GATEWAY_RELAY_DELIVERY_KEY

Tutto qui. Il tuo gateway ora è “registrato” e può chiamare il connettore ogni volta che ne ha bisogno.

Cosa Succede Dopo?

Una volta registrato, il tuo gateway:

Chiamerà l’URL del connettore che hai fornito
Riceverà un descrittore delle capacità (cosa può fare la piattaforma frontend)
Inizierà a scambiare messaggi e azioni normalizzati attraverso quella stessa socket

Nessuna porta in ingresso, nessuna credenziale extra, nessun codice specifico per piattaforma.

Riepilogo e Consiglio Pratico

Riepilogo: Hermes Relay è un modo pulito per collegare il tuo gateway alle piattaforme di messaggistica senza possedere le loro credenziali o aprire porte. È perfetto per hosting condiviso, ambienti NAT o qualsiasi configurazione in cui vuoi tenere i segreti lontani dalla tua macchina principale.

Consiglio pratico: Mantieni sempre il tuo token di registrazione monouso e di breve durata. Se mai hai bisogno di ruotare le credenziali, esegui di nuovo il comando di registrazione con un token fresco — e ricorda di eliminare il vecchio GATEWAY_RELAY_SECRET dal tuo file .env prima di aggiornarlo. Un po’ di igiene fa la differenza.