Conectar o Desktop a Várias Instâncias do Hermes

Registre em um único aplicativo desktop todo backend do Hermes que você tem — o runtime local, gateways remotos na sua rede local ou em VPS, hosts SSH e instâncias do Hermes Cloud — e use os agentes de todos eles lado a lado. As conexões são persistentes: cada gateway registrado disca os próprios backends e WebSockets sob demanda, e os agentes em segundo plano continuam transmitindo enquanto você olha outro gateway.

Esta é a contraparte, no lado do desktop, de Rodar Vários Gateways ao Mesmo Tempo: aquela página trata de hospedar vários gateways em uma máquina; esta trata de um aplicativo desktop falando com várias máquinas.

Onde encontrar

Tudo fica na página unificada Settings → Gateways (versões mais antigas tinham páginas separadas de Gateway e Connections; links diretos antigos para Connections redirecionam para lá). Três portas levam até ela:

• Settings → Gateways — a própria página (Cmd/Ctrl+, e depois Gateways na navegação de configurações). O registro de conexões é uma seção dessa página, abaixo dos controles de modo de conexão no nível da máquina.
• A barra de perfis na lateral — o botão de tomada na ponta direita da barra (dica: "Connect another Hermes gateway…") leva direto à página Gateways. Ele fica sempre visível, mesmo antes de você criar um segundo perfil ou uma segunda conexão.
• A paleta de comandos — Cmd/Ctrl+K e depois digite Gateways (também casa com connections, add gateway, remote, ssh, instances).

O registro de gateways

A seção Registered gateways de Settings → Gateways gerencia uma lista nomeada de gateways do Hermes. A introdução diz sem rodeios: "Manage this device and every Hermes gateway it can reach through remote, SSH, or Cloud connections." Cada entrada é uma conexão:

Tipo	O que é	Autenticação
Local	"The Hermes runtime managed by this app."	automática
Remote gateway	"A Hermes gateway reachable over HTTP(S) — LAN, Tailscale, or the internet."	token de sessão ou OAuth
SSH	"A Hermes install reached over SSH." O aplicativo abre o túnel e inicia o painel por você	chave SSH + token adotado
Hermes Cloud	"A hosted instance discovered through your Hermes Cloud account."	login no portal

Regras que vale conhecer:

• Toda conexão precisa de um nome de dispositivo único ("Homelab", "Notebook do trabalho"). O nome aparece em todo lugar em que a instância aparece — selos na lista, handles, resultados de atualização. A unicidade ignora maiúsculas e minúsculas, então Homelab e homelab não podem coexistir.
• A entrada local é gerenciada pelo aplicativo (ela ostenta uma pílula App-managed) e não pode ser removida. Remover qualquer outra conexão derruba os backends e túneis vivos dela; a instância em si fica intacta.
• Uma conexão é sempre a Primary (pílula na linha dela): é a alternativa do registro para chamadas multi-gateway que não nomeiam um gateway. Make primary não troca o espaço de trabalho atual em Sessions; remover a primária faz voltar para a entrada local.
• At startup, return to Sessions on the last-used gateway controla em qual gateway a página Sessions abre depois de reiniciar o aplicativo por completo. Vem desligado, então Sessions abre na Primary. Ligue para retomar o gateway mais recente que conectou com sucesso. Uma troca que falhou nunca é lembrada, e um gateway salvo que foi removido ou está indisponível cai de volta na Primary.
• O Test sonda tanto a perna HTTP quanto a WebSocket da conexão, então passar (o aviso "Reachable") significa que o chat vai funcionar de verdade — não só que o host respondeu ao ping.
• Duplicatas são rejeitadas ao salvar: existe sempre só uma entrada local; entradas remote e cloud são deduplicadas pela URL normalizada (com espaços aparados, barras finais removidas e em minúsculas — e entre os dois tipos, então uma entrada cloud e uma remote não podem apontar para a mesma URL); entradas SSH são deduplicadas pelo user@host:port normalizado mais o perfil remoto.
• Entradas cloud normalmente vêm do fluxo de login/descoberta do Hermes Cloud no topo da página Gateways — o tipo Hermes Cloud no editor de nova conexão aponta você para lá.

Troque de gateway pela barra lateral de Sessions. Perfis, chats, mensagens e cron continuam limitados àquele gateway; o backend de janela gerenciado pelo aplicativo ainda é escolhido pelos controles de modo de conexão acima. A Primary é a alternativa do registro e não troca o espaço de trabalho atual.

Adicionar uma conexão, passo a passo

1. Abra Settings → Gateways e role até o registro de conexões (ou clique na tomada na barra de perfis).
2. Clique em Add connection.
3. Escolha o tipo: Local, Hermes Cloud, Remote gateway ou SSH. (Local fica desabilitado enquanto existir a entrada local gerenciada pelo aplicativo — o que é quase sempre; Hermes Cloud direciona você ao fluxo de login/descoberta na nuvem acima.)
4. Preencha os campos:
   • Name — obrigatório, único; é o "nome de dispositivo" mostrado em todo lugar em que essa instância aparece (texto de exemplo: Homelab). No máximo 64 caracteres.
   • Só para remote gateway:
     • Gateway URL — a URL base de um backend hermes serve em execução, por exemplo http://homelab.lan:9119. Prefixos de caminho de proxy reverso funcionam.
     • Authentication — escolha Session token ou OAuth:
       • Session token — cole o token de sessão do painel do gateway remoto. Ao editar, "Leave blank to keep the saved token."
       • OAuth — faça login pelo fluxo de navegador do Nous Portal; não há token para colar.
   • Só para SSH:
     • SSH host — um campo composto no formato user@host:22 (usuário e porta são opcionais). A sua chave SSH é usada; o aplicativo adota um token de painel pelo túnel.
5. Clique em Save connection (ou em Cancel).
6. Clique em Test na nova linha e espere pelo "Reachable".

Edite depois qualquer entrada não local com o botão de lápis, ou remova-a com o botão de lixeira — a remoção pede confirmação e lembra você de que "The instance itself is not touched — you can add it again any time."

O backend remoto é um processo hermes serve em execução

Nada aqui funciona a menos que o backend esteja mesmo no ar e acessível na outra máquina. O aplicativo desktop se conecta a ele; não o inicia por você (com exceção das conexões SSH, em que o aplicativo inicia o painel pelo túnel sob demanda). Veja Conectar a um backend remoto para a configuração do lado do backend — provedores de autenticação, vinculação a um endereço fora do loopback e orientações sobre Tailscale.

Migrar das configurações de conexão única

A primeira execução de uma versão com suporte a registro importa as suas configurações existentes automaticamente: o modo de conexão global e quaisquer sobrescritas antigas por perfil vindas de Settings → Gateway viram entradas nomeadas no registro (deduplicadas por URL/host). (Versões mais novas não oferecem mais sobrescritas por perfil na página de configurações de Gateways — as conexões de gateway são no nível da máquina, e os perfis são descobertos a partir dos gateways que você conecta.) O arquivo de configuração antigo fica intacto, então versões mais antigas na mesma máquina continuam funcionando. Se um nome migrado colidiu, ele ganhou um sufixo (Homelab 2).

Agentes entre gateways

Cada perfil em cada conexão registrada é um agente. A lista unificada é o que as superfícies multi-gateway (e a lista do Modo Bot embutido) renderizam:

• Quando o mesmo nome de perfil existe em vários gateways, os handles são desambiguados como @nome-dispositivo — research no seu Homelab aparece como @research-homelab, enquanto um perfil único entre todos os gateways mantém o nome puro.
• A enumeração é ansiosa, mas os sockets são preguiçosos: o aplicativo lista os agentes por REST sem discar o WebSocket de cada gateway. Um gateway inacessível reporta o erro na própria linha, em vez de quebrar a lista; conexões SSH continuam a conectar sob demanda até você abrir um agente nelas pela primeira vez (nada de túneis surpresa).
• Abrir um agente disca o gateway dele — chats, sessões e memória vivem na máquina dona do perfil, exatamente como se você estivesse usando aquela instância diretamente.

Cada par (conexão, perfil) ganha o próprio backend e socket, agrupados com a mesma coleta por ociosidade dos backends locais por perfil — os agentes em segundo plano continuam transmitindo enquanto você olha outro gateway.

Trocar e delimitar escopo

O pé da barra lateral segue uma hierarquia: gateway → perfil → sessões. Gateways são máquinas ou backends hospedados; perfis são agentes isolados do Hermes que vivem em um gateway.

• Com um único gateway registrado, nenhum controle de gateway é acrescentado. O Desktop só local mantém a mesma barra de perfis e o mesmo fluxo de teclado de antes.
• Com vários gateways, a barra lateral mostra um seletor nomeado de gateway. O ícone de dispositivo, nuvem, rede ou terminal identifica o tipo de conexão; os avatares de perfil continuam sendo um controle separado, depois do divisor. Esse mesmo seletor escala de dois gateways até uma frota maior, sem transformar backends em ícones parecidos com perfis nem espremer as ações de perfil para fora da barra.
• Selecionar um gateway restaura o último perfil usado ali. A pílula de início volta ao perfil padrão dela e a pílula de camadas mostra All profiles on this gateway. Cmd/Ctrl+1–9 continuam trocando de perfil dentro do gateway ativo.
• Com vários gateways, a barra de perfis vira uma barra de frota: os perfis de todo gateway registrado ficam na mesma faixa, cada grupo encabeçado pelo ícone do tipo daquele gateway (dispositivo, rede, terminal, nuvem) — o mesmo ícone que o seletor de gateway usa. Os quadrados do gateway ativo aparecem exatamente como em um Desktop de gateway único; os quadrados dos outros gateways ficam esmaecidos ("em repouso"). Passar o mouse sobre um quadrado em repouso mostra o nome da máquina dele (omer · This device), então dois perfis de mesmo nome em máquinas diferentes nunca se confundem.
• Clicar em um quadrado em repouso faz a mesma troca que o seletor de gateway, indo para aquele (gateway, perfil) exato: o quadrado gira enquanto o destino é discado, o gateway anterior continua pintado até o destino responder, e um destino morto faz o clique falhar com uma mensagem, em vez de deixar a janela trocada pela metade. Os grupos mantêm a ordem do registro, qualquer que seja o gateway ativo, então um quadrado nunca se move sob o ponteiro que o clicou. O clique com o botão direito em um quadrado em repouso oferece Switch to, Color, Rename, Edit SOUL.md e Delete, todos executados no gateway do próprio quadrado; a confirmação de exclusão nomeia a máquina.
• Um gateway que a última enumeração não conseguiu alcançar mantém os quadrados dele, marcados com um ponto âmbar no ícone — uma máquina dormindo continua sendo sua. Dois registros de um mesmo backend colapsam em um único grupo. Passando de treze quadrados na frota, a faixa se condensa em um menu dividido por gateway.
• O gateway selecionado sobrevive a fechar e reabrir o aplicativo apenas quando Settings → Gateways → At startup, return to Sessions on the last-used gateway está ligado. A preferência e o id do gateway ficam no registro de dados de usuário do aplicativo, então substituir ou atualizar o pacote do aplicativo não os zera.
• Com mais de treze perfis no gateway ativo, a faixa de avatares deles se condensa em um seletor nomeado de perfil. Conjuntos grandes de gateways e de perfis podem, portanto, coexistir sem mudar o modelo gateway → perfil → sessões.
• This device continua sendo um gateway de primeira classe mesmo quando uma conexão remota é a Primary. Ele pode manter as sessões locais disponíveis durante uma queda remota, mas o aplicativo não chama isso de "modo offline": o modelo ou as ferramentas selecionadas ainda podem exigir acesso à internet.
• A lista de sessões, os canais de mensagens, as tarefas cron, as configurações, os arquivos e a memória são todos limitados ao (gateway, perfil) ativo. Trocar de um gateway do Telegram para um gateway do Signal não pode deixar na barra lateral os grupos de canais ou as sessões do gateway anterior.
• Só exibir o seletor lê o registro local de conexões do Electron. Gateways remotos são abertos apenas quando selecionados; não há sondagem periódica da frota.
• Passar o mouse sobre um agente pré-aquece o backend dele, para que a troca não pague uma partida a frio.
• A página Capabilities (Skills / Tools / MCP) tem um escopo equivalente: o seletor Configuring dela lista todo agente (perfil, dispositivo) da lista unificada, e escolher um lê e grava as skills, os conjuntos de ferramentas e os servidores MCP daquela máquina, sem trocar o espaço de trabalho de Sessions. Instalações pelo hub, chaves de ambiente e configuração de MCP vão todos para o backend do agente selecionado. O botão de hot-reload em uma sessão viva da aba MCP aparece só para agentes no gateway ao qual a janela está conectada; edições em outras máquinas passam a valer na sessão seguinte delas.

Adicione, teste, renomeie ou remova gateways em Settings → Gateways. O botão de tomada ao lado das ações de perfil é um atalho para essa única casa de gerenciamento, não um segundo fluxo de adição.

Sessions e Modo Bot

A página Sessions mostra de propósito um gateway ativo por vez: isso mantém arquivos, ferramentas, canais, cron e histórico de sessão em um único contexto de execução compreensível. A barra de perfis da frota amplia só o seletor — o espaço de trabalho continua vivendo em exatamente um (gateway, perfil) depois de cada clique. O Modo Bot atende a outro propósito e pode apresentar a lista unificada, agrupada por gateway, para que a pessoa abra um agente em um NAS e outro em um VPS pela mesma superfície. Abrir um bot ainda ativa a rota (gateway, perfil) exata dele.

Menções diretas a bots e delegação continuam locais ao gateway por padrão. Cruzar a fronteira de um backend muda sistema de arquivos, credenciais, ferramentas e contexto de confiança, então a execução entre gateways deve ser uma ponte explícita, e não um efeito colateral acidental de compartilhar uma janela do Desktop.

Atualizar todas as instâncias de uma vez

Settings → Gateways → Update all instances (exibido assim que mais de uma conexão está registrada) despacha o hermes update para toda conexão elegível em paralelo:

• Local atualiza pelo próprio pipeline de atualização do aplicativo (o mesmo fluxo de Settings → Updates).
• Conexões remote e SSH recebem a ordem de se atualizarem pelo próprio backend — a atualização roda naquela máquina.
• Instâncias do Hermes Cloud são puladas com uma nota "Managed by Hermes Cloud": a plataforma gerencia as versões delas.

Cada instância reporta de forma independente, então uma máquina inacessível nunca trava o lote. Backends que gerenciam atualizações por fora (Docker, Nix) recusam educadamente com a mensagem deles, linha por linha.

Você raramente precisa do botão em Settings, no entanto: assim que existe mais de um alvo de atualização, os recursos normais de atualização do aplicativo (Update now no painel About, ⌘K Update Hermes, o aviso de atualização pronta) executam a mesma distribuição automaticamente — primeiro o backend ativo, depois todo outro gateway elegível e, por último, o próprio aplicativo desktop. Veja Atualizar no guia do desktop.

Observações de segurança

• Onde ficam os tokens. Tokens de sessão de gateway remoto (e tokens OAuth de login nativo, indexados pela URL base do gateway) são guardados no diretório de dados de usuário do aplicativo como arquivos acessíveis só pelo dono (0600), no processo principal do Electron; o renderizador e os plugins nunca veem os bytes do token.
• Criptografia opcional pelo chaveiro. Por padrão, os tokens não passam pelo chaveiro do sistema operacional — no macOS em particular, o safeStorage do Electron guarda uma chave por aplicativo no chaveiro de login, e um chaveiro trancado ou quebrado transforma isso em um pedido de senha a cada inicialização. Se você quiser criptografia em repouso além das permissões de arquivo, ligue Settings → Gateway → "Encrypt saved secrets with the OS keychain"; os segredos já armazenados são recriptografados no lugar (Keychain no macOS, DPAPI no Windows, o backend de chaveiro de sessão no Linux). Desligar de volta descriptografa tudo outra vez.
• O arquivo de registro (connections.json dentro do diretório de dados de usuário do aplicativo) guarda rótulos, URLs e hosts — segredos só aparecem dentro de envelopes criptografados.
• O host.connections() do SDK de plugins devolve de propósito rótulos, tipos e o id da primária — nunca material de token.

Para quem escreve plugins

O SDK de plugins do Desktop expõe a superfície multi-gateway diretamente:

• host.connections() — a lista de conexões registradas (rótulos, tipos, primária; nunca bytes de token).
• host.agents() — a lista unificada: uma linha por (gateway, perfil) com o handle @nome-dispositivo já calculado.
• host.ensureAgent(connectionId, profile) — ativa o gateway de um agente para que as chamadas seguintes de host.request cheguem ao backend dele.
• host.warmAgent(connectionId, profile) — pré-aquecimento de socket do tipo dispare-e-esqueça (intenção de hover).

Os quatro são detectados por recurso: em uma versão mais antiga do Desktop eles não existem e um plugin deve recorrer ao fluxo de gateway único profiles.list. A lista multi-gateway do Modo Bot é o consumidor de referência.

Solução de problemas

• "Connection test failed" — o backend não está acessível naquela URL a partir desta máquina. Confira se o hermes serve está rodando no host remoto, se a porta está aberta e (na autenticação por token) se o token está atual. Rode Test de novo depois de corrigir.
• Um agente aparece, mas não abre — rode Test na conexão dele. A perna WebSocket falhar enquanto o HTTP passa geralmente significa que um proxy, firewall ou a proteção de autenticação/origem do gateway está bloqueando o /api/ws.
• Um gateway remoto está faltando na lista — o backend dele está fora do ar ou inacessível; a lista o mostra entre os gateways, com o erro. Conexões SSH aparecem como connect-on-demand até o primeiro uso — isso é de propósito, não é falha.
• "Update Hermes Desktop to chat with agents on other connections" — o aplicativo é anterior à pilha de múltiplas conexões; atualize o próprio aplicativo desktop.
• Nomes de dispositivo duplicados — não é possível; os nomes são forçados a ser únicos na hora de salvar. Se um nome migrado colidiu, ele ganhou um sufixo (Homelab 2).
• "Could not save the connection" — normalmente é um Name faltando, um nome já em uso ou uma Gateway URL / SSH host mal formada; a mensagem de erro diz exatamente qual é a violação.

---