Hermes Relay — Conectar Instâncias | Easy Understand Hermes Agent

Pense no Hermes Relay como uma cabine telefônica que liga de volta para você — você não precisa dar o seu endereço, apenas faz uma ligação uma vez, e o outro lado pode falar com você a qualquer momento pela mesma linha.

O Que é o Hermes Relay?

O Hermes Relay é um sistema de conexão para o gateway do Hermes Agent. Ele permite que seu gateway converse com plataformas de mensagens como Discord, Telegram ou Slack sem guardar nenhum token de bot ou senha delas.

Em vez disso, um serviço separado (o “conector”) é o dono dessas credenciais. Seu gateway simplesmente faz uma conexão de saída com o conector através de uma única conexão WebSocket segura — e então todas as mensagens fluem de um lado para o outro por essa linha aberta.

Por Que Isso é Útil?

Aqui estão as maiores vantagens, em palavras simples:

Sem necessidade de portas abertas. Seu gateway funciona até atrás de um roteador doméstico ou firewall de nuvem. Ele só faz conexões de saída, então você não precisa expor nada à internet.
Sem segredos de bot na sua máquina. O conector guarda todos os tokens das plataformas. Se o seu gateway for roubado, o invasor não leva nada de útil.
Um gateway, várias plataformas. O conector informa ao seu gateway o que ele pode fazer (limite de mensagens, markdown, edição, tópicos, etc.) no momento em que eles se conectam. Sem regras fixas — ele simplesmente se adapta.

Quando usar: Se você está rodando seus próprios bots diretamente, pule o Relay e use os adaptadores nativos (Telegram, Discord). O Relay é para configurações onde um conector compartilhado ou hospedado gerencia o lado da plataforma — como hospedagem multi-tenant ou quando você simplesmente não quer tokens na sua máquina.

Como Registrar Seu Gateway

O registro é uma configuração única. Você executa um único comando, e o Hermes faz o resto.

Primeiro, certifique-se de ter um token de registro (emitido pelo seu provedor de conector). Depois, execute:

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

Veja o que acontece passo a passo:

O Hermes verifica seu login existente (~/.hermes/auth.json) para provar a qual organização você pertence.
Se você configurou seu próprio provedor de identidade (para ambientes isolados ou self-hosted), ele usa esse em vez disso.
Ele envia o token de registro para o endpoint /relay/enroll do conector via TLS.
O conector verifica se o token é válido, de uso único e corresponde ao seu tenant.
Em seguida, ele emite um segredo por gateway e uma chave de entrega — e os retorna uma única vez.
O Hermes salva esses dados em ~/.hermes/.env:

GATEWAY_RELAY_ID
GATEWAY_RELAY_SECRET
GATEWAY_RELAY_DELIVERY_KEY

Pronto. Seu gateway agora está “registrado” e pode se conectar ao conector sempre que precisar.

O Que Acontece Depois?

Depois de registrado, seu gateway vai:

Se conectar à URL do conector que você forneceu
Receber um descritor de capacidades (o que a plataforma intermediária pode fazer)
Começar a trocar mensagens e ações normalizadas através desse mesmo socket

Sem portas de entrada, sem credenciais extras, sem código específico de plataforma.

Resumo e Dica Prática

Resumo: O Hermes Relay é uma forma limpa de conectar seu gateway a plataformas de mensagens sem ter as credenciais delas ou abrir portas. É perfeito para hospedagem compartilhada, ambientes NAT ou qualquer configuração onde você queira manter segredos fora da sua máquina principal.

Dica prática: Sempre mantenha seu token de registro como uso único e de curta duração. Se precisar rotacionar as credenciais, basta executar novamente o comando de registro com um token novo — e lembre-se de apagar o GATEWAY_RELAY_SECRET antigo do seu arquivo .env antes de atualizá-lo. Um pouco de higiene faz toda a diferença.