No escritório, seu homelab desaparece: o Webapp agora usa as conexões que o Desktop salvou


Quarta-feira à tarde, um notebook emprestado, uma sala de reunião. Você abre o navegador, digita o endereço do Webapp da máquina que está em casa e quer só dar uma olhada nos cron jobs que rodam no seu homelab. O que aparece é um único gateway: o local. O Desktop tem três ou quatro salvos, e você sabe recitar os nomes de cor — Homelab, notebook do trabalho, aquele VPS que você paga todo mês.

Não é problema de permissão e você não foi deslogado. O Webapp só conhecia o gateway que serve a página. Todo o resto morava no diretório de dados do app desktop, invisível para o lado do navegador.

Em 7 de novembro um lote de commits mudou isso: as conexões salvas deixaram de ser dados privados do desktop e passaram a ser um armazenamento que a máquina inteira compartilha. O Webapp lê a mesma lista e consegue discar qualquer entrada como o Desktop faz.

Um arquivo, dois hosts

A mudança é simples de descrever: o Desktop guardava o registro de conexões e os logins OAuth nativos no diretório userData do Electron. Agora tudo isso vive no home do Hermes, ao lado do ui-preferences.json:

  • gateway-connections.json — as conexões em si: rótulos, URLs, hosts SSH, e o session token e os headers extras de cada entrada
  • gateway-connection-tokens.json — os logins OAuth, indexados por conexão

Os dois arquivos têm modo 0600, só o dono lê. O processo principal do Electron e o servidor do Webapp escrevem e leem o mesmo arquivo, então adicionar o Homelab no Desktop aparece no navegador depois de um refresh — e vice-versa, sem reiniciar nada. Na primeira execução de um build com a lista compartilhada, connections.json, connection.json e native-oauth-tokens.json são copiados uma única vez do diretório userData antigo, mantendo os mesmos ids: ninguém precisa reconfigurar nada e você não fica com duplicatas. Os arquivos antigos são deixados intactos (builds mais velhos continuam funcionando) e nunca mais são lidos.

O contrato de escrita importa, porque dois hosts escrevendo no mesmo arquivo é o truque inteiro: quem escreve pega um lock de diretório <store>.lock, troca o arquivo por inteiro via arquivo temporário mais rename, guarda um arquivo ilegível de lado como .corrupt-<ms> em vez de sobrescrevê-lo, e trata apenas arquivo ausente como “sem store”.

O navegador continua falando com um único gateway

É aqui que a maioria erra. O Webapp não faz o seu navegador discar direto para o VPS — não consegue, e não deveria. Toda requisição e todo socket que sai do navegador continuam indo para o gateway que serve a página, e esse gateway encaminha para o destino salvo:

  • modo token: o X-Hermes-Session-Token salvo
  • modo OAuth: um bearer renovável, com um ticket de uso único para o handshake do WebSocket
  • mais os headers extras salvos naquela conexão

O remoto não precisa de configuração própria — ele vê um cliente comum. Cada gateway salvo entra no seletor de gateways do Webapp e nos grupos de gateway da sidebar, então você troca entre eles, agrupa por Gateway & profile e arrasta seções para a ordem que quiser (isso renomeia e reordena apenas os rótulos da sidebar, nunca o gateway).

O OAuth também foi para o servidor: a máquina que serve a página conduz o fluxo nativo da RFC 8252, guarda o verifier do PKCE, manda o navegador para o /auth/native/authorize do remoto e recebe o callback em /webapp/gateway-connections/oauth/callback. Os tokens rotacionam pelo /auth/native/refresh do remoto — um em andamento por conexão de cada vez; um 401 derruba o login, uma queda de rede mantém.

Se o seu navegador não está na máquina que serve a página — o caso normal, já que você está no escritório e o gateway está em casa — o redirect cai no seu próprio loopback e o servidor nunca vê. Aí o editor de conexão oferece um campo para colar esse endereço de volta, o que conclui o login.

Conexões SSH também funcionam no navegador. O servidor carrega um port do caminho SSH do Desktop: um ControlMaster para o host da entrada, o mesmo spawn de serve --isolated --host 127.0.0.1 --port 0 (com arquivo de session token e nonce de dono) sob o mutex do update-marker remoto, e um forward só em 127.0.0.1 para o relay mirar. A propriedade é limitada ao connection store desta máquina, então Desktop e gateway nunca reap um do outro o serve. As duas pontas precisam ser Linux ou macOS; um remoto ou host local Windows é recusado como plataforma não suportada.

O preço, dito sem rodeios

Aqui eu quero que você pare e leia duas vezes.

A fronteira de confiança do Webapp é “qualquer um que consiga fazer login nesta página”. Quando alguém consegue, passa a poder usar todo gateway salvo nesta máquina — como quem for o dono da credencial salva. A documentação diz isso sem amaciar: salve apenas gateways que você deixaria essas pessoas acessarem.

O que limita o estrago é o que o navegador consegue fazer com as respostas: uma resposta encaminhada roda sob uma content policy de sandbox, nunca é cacheada pelo navegador e não consegue redirecionar para fora daquele gateway; o relay não mantém cookie jar; remover uma conexão fecha na hora os sockets abertos dela.

Cinco motivos para uma credencial cair no endereço errado

Metade deste lote são correções de bug, e todas pertencem à mesma família: a credencial e o endereço para onde ela foi enviada podiam discordar. Essa parte ensina mais que a feature.

Um: duas leituras por dial. O dial lia a URL da entrada e depois relia token, headers e login por id. Uma edição que chegasse entre as duas leituras emparelhava o endereço antigo com a credencial nova. Agora o store entrega um único snapshot de dial — entrada, URL, token, headers e o login vinculado à URL, tudo de uma leitura do registro. O modo token disca a URL do snapshot; o ensure_access_token do OAuth devolve o token junto com o endereço que o emitiu, e o ticket do socket só é cunhado pelo endereço que o socket realmente disca.

Dois: os logins não estavam amarrados à URL que os emitiu. Os conjuntos de token eram indexados por id de conexão, e ids são slugs de rótulo reciclados. Troque uma URL, ou remova e recrie com o mesmo rótulo, e o relay podia mandar o bearer do host A para o host B e dar POST no refresh token do host A no /auth/native/refresh do host B. Agora cada conjunto guardado carrega o baseUrl que o emitiu; um conjunto cujo baseUrl difere da URL atual da entrada é lido como deslogado nos dois gêmeos, e refresh só é enviado para a URL do próprio conjunto. Qualquer escrita no registro que remova uma entrada ou mude seu url ou authMode descarta o conjunto dos dois lados.

Três: uma página de outro site podia pegar seu relay emprestado. O cookie de sessão do Webapp é SameSite=Lax, então uma navegação de topo vinda de outro site para /api/relay/<id>/<path> o carregava, e o relay fazia aquele GET no gateway salvo com a credencial salva. A resposta vinha em sandbox e ilegível, mas um GET remoto com efeitos colaterais ainda rodava. Agora uma requisição encaminhada cujo Sec-Fetch-Site existe e não é same-origin recebe 403 antes de qualquer coisa ser enviada; os fetches da própria página, e clientes que não mandam Fetch Metadata, seguem como antes.

Quatro: um callback colado podia resgatar na conexão errada. A conclusão resgatava o código e gravava os tokens primeiro, e só depois comparava a conexão do flight com o id no caminho. Agora o flight é conferido sob o lock de flights antes do resgate: um redirect colado para outra conexão recebe 400 sem uma única requisição de token, e o flight da própria conexão continua utilizável.

Cinco: clonar e exportar levavam tokens em texto plano para fora. hermes profile create --clone-all copiava os dois stores da máquina para o clone, e o hermes profile export então embarcava session tokens em texto plano, porque o scrubber da exportação não reconhecia o envelope {"encoding":"plain","value":…}. Os dois stores entraram em PROFILE_CREDENTIAL_PATHS; o clone-all os ignora junto com o diretório .lock deles; o scrub da exportação mascara todo envelope no JSON preparado.

Aproveitando: por que esses segredos ficam em texto plano no disco e não no keychain do sistema? Porque o servidor do Webapp precisa lê-los, e keychain não existe para um processo de servidor. A proteção são as permissões de arquivo, mais uma fronteira — o renderer e os plugins nunca veem bytes de token (o host.connections() do SDK de plugins devolve apenas rótulos, tipos e o id primário). Um segredo que um build antigo criptografou com safeStorage é decriptado uma vez durante o import; o que não decripta não é descartado: fica como está e aparece no importNotices do arquivo até o keychain do Desktop responder e convertê-lo.

Como usar

Desktop e Webapp compartilham o caminho porque compartilham a página: Settings → Gateways. Role até Registered gateways e clique em Add connection:

  • Local — o runtime que este app gerencia (gerenciado pelo app, não pode ser removido)
  • Remote gateway — um hermes serve rodando; informe a URL e escolha session token ou OAuth
  • SSH — um campo composto user@host:22, mais um caminho completo opcional para o executável hermes remoto
  • Hermes Cloud — vem do fluxo de login e descoberta do Portal, sem URL digitada à mão

Depois clique em Test. Ele sonda as duas pernas da conexão, HTTP e WebSocket, então “Reachable” significa que o chat vai de fato funcionar, e não só que a porta responde. No Webapp, o Test numa linha SSH abre o mesmo túnel gerenciado que o gateway usa, iniciando (ou reaproveitando) o hermes serve no remoto; esse túnel não é limpo pelas suas costas — ele para quando você remove a conexão ou para o gateway, ou sozinho depois do idle timeout remoto dashboard.ssh_isolated_idle_grace_s (15 minutos por padrão) sem cliente e sem trabalho.

Duplicatas são recusadas na hora de salvar: uma entrada local, sempre uma só; entradas remote e cloud deduplicam pela URL normalizada (entre os dois tipos, então uma entrada cloud e uma remote não podem apontar para a mesma URL); entradas SSH deduplicam por user@host:port mais o profile remoto.

Quando você consegue isso de fato

Sinceramente: ainda não, se você usa releases oficiais. Esses commits entraram em 7 de novembro, e a v0.23.0 saiu em 5 de novembro — eles estão na main e em nenhuma tag. hermes update entrega releases, então é esperar a próxima ou acompanhar a main.

Atualização (10/11/2026): essas mudanças saíram na v0.23.1 (9 de novembro): basta um hermes update. O « não está na v0.23.0 » acima continua correto; a v0.23.1 fecha a lacuna.

Até lá, as conexões salvas do Desktop já funcionam há um tempo (veja o guia de desktop multi-gateway). O que mudou é que a metade do navegador deixa de ser cidadã de segunda classe.

E se o login do seu gateway remoto vem brigando com você por causa de redirects de loopback e jump hosts, as três rotas de concluir o OAuth em um servidor remoto continuam valendo. A novidade é que agora o servidor executa o fluxo nativo inteiro por você e deixa colar o endereço de volta quando o callback cai na máquina errada.

A versão curta

As conexões de gateway salvas deixaram de ser assunto privado de um app desktop e viraram infraestrutura compartilhada da máquina: um arquivo JSON 0600, dois hosts escrevendo nele, o navegador falando só com o gateway que o serve, credenciais amarradas a um endereço antes de serem encaminhadas. A capacidade em si é simples. As cinco correções são a parte valiosa — elas mostram que “a quem pertence esta credencial” é uma armadilha em todo lugar quando edições e escritas concorrentes de vários hosts entram em cena.

Para a superfície de comandos, veja a referência de hermes gateway do site; para o lado desktop, o guia do modo interface cobre como o app apresenta backends locais e remotos.