Hermes Webapp: o Desktop inteiro do agente num browser

Por SkyNet · 7 de novembro de 2026

O Hermes sempre teve várias caras: o terminal com o CLI, a interface visual do Desktop e, para quem prefere algo mais leve, o TUI. Até agora, cada uma destas superfícies pedia uma instalação diferente. O Webapp, lançado a sério na v0.22.6, resolve isto de uma vez: o Desktop inteiro a correr dentro do browser, servido pelo próprio gateway.

Não é uma versão reduzida nem um painel de administração. É o mesmo workspace, as mesmas sessões, os mesmos Kanban e definições que encontras na aplicação Electron, mas servidos por HTTP a partir do listener do gateway. Abres um separador e tens chat, painel de capacidades, terminais, ficheiros, Git, revisão de PR — tudo.

Como se activa

Vem desligado de fábrica. Ligar o Webapp são três passos:

  1. Acrescentar este bloco ao config.yaml do Hermes:
webapp:
  enabled: true
  host: 127.0.0.1  # só nesta máquina; 0.0.0.0 para rede (requer autenticação)
  port: 9120        # fixo, para o browser lembrar o URL
  public_url: ""    # preencher quando atrás de reverse proxy
  1. Reiniciar o gateway para ele ler as novas definições:
hermes gateway restart
  1. Abrir o Webapp:
hermes webapp

Na primeira vez que corres hermes webapp, ele constrói o bundle do Webapp se estiver desatualizado, arranca o gateway caso não esteja a correr e abre o browser com um link de sessão único. O link vale 60 segundos e funciona uma vez: o browser troca-o por uma sessão persistente naquela aba. Recarregar a página mantém-te dentro, e a sessão sobrevive a um restart do gateway.

Utilitários da CLI

Dois comandos que convém conhecer:

  • hermes webapp --status — diz se o gateway está a servir o Webapp, em que porta e se há algum problema (porta ocupada, host não alcançável, sign-in em falta).
  • hermes webapp --no-open — só imprime o link em vez de abrir o browser. Útil para SSH ou para partilha controlada.

No Docker

Em contentores, o Webapp é particularmente útil porque evita ter de configurar encaminhamento X11 ou VNC para o Desktop nativo. O pacote já vem com o bundle pré-construído; o gateway serve-o no próprio contentor.

Há duas particularidades:

1. host: 0.0.0.0 é obrigatório. O 127.0.0.1 dentro do contentor é o loopback do contentor, não do host — nenhum outro contentor ou o próprio host consegue alcançá-lo. Com 0.0.0.0, publicas a porta 9120 e acedes pelo IP do host.

2. Provider de sign-in. Com host: 0.0.0.0, o gateway exige autenticação (porque o Webapp fica alcançável na rede). Sem um provider configurado (palavra-passe, OAuth ou OIDC), o browser não consegue ligar-se e o gateway serve apenas os clientes nativos.

Exemplo mínimo para Docker Compose:

services:
  hermes:
    image: nousresearch/hermes-agent:latest
    ports:
      - "9120:9120"
    volumes:
      - ~/.hermes:/opt/data
    environment:
      - HERMES_DASHBOARD_BASIC_AUTH_USERNAME=admin
      - HERMES_DASHBOARD_BASIC_AUTH_PASSWORD=<gerar-com-openssl-rand-hex-16>

Com o webapp.public_url preenchido (para trás de um túnel ou proxy reverso como Caddy, nginx ou Cloudflare Tunnel), o sign-in usa esse endereço para onde o browser é redirecionado. O dashboard.public_url não se aplica ao Webapp — cada um tem o seu campo.

Pitfalls que já vi apanhar gente

A documentação e a prática revelam meia dúzia de armadilhas que vale a pena interiorizar antes de começar:

  • Mudanças ao config.yaml na secção webapp.* — precisam sempre de hermes gateway restart para aplicar. O hermes webapp constrói o bundle se precisar, mas não relê o config do gateway em execução.
  • Porta 9120 ocupada — o gateway serve apenas clientes nativos e o sign-in do browser falha silenciosamente. hermes webapp --status mostra o problema; libertar a porta e correr hermes webapp outra vez.
  • host: 0.0.0.0 sem sign-in — o gateway não aceita browsers. Configurar um provider de autenticação (palavra-passe simples chega para uma LAN de confiança).
  • Perfis standalone — a porta predefinida é 9120 para o perfil principal, mas perfis independentes usam a primeira porta livre acima de 9120.
  • trusted_proxies — ao contrário do public_url, a definição dashboard.trusted_proxies aplica-se ao Webapp para processar headers X-Forwarded-* corretamente atrás de um proxy.

Fora de loopback, o browser perde algumas capacidades que o Electron tem: atalhos globais, microfone (ditado e wake word), área de transferência partilhada e notificações. A solução para quem precisa disto é ou HTTPS com webapp.public_url ou um túnel SSH.

O que muda com a v0.22.6

O Webapp não é novo no ramo main — o código já estava em desenvolvimento há semanas. Mas a v0.22.6, lançada a 2 de Novembro, é a primeira release estável que o entrega ao público. O release notes diz que esta tag junta cerca de 776 PRs desde a v0.22.5 e lista o Webapp entre as novidades also in the window, undocumented here on purpose — as notas curadas e documentação a sério ficam para a v0.23.0.

Isto significa que, a partir de hoje, qualquer pessoa com uma instalação actualizada pode ter o Hermes Desktop numa aba sem instalar mais nada. O gateway faz o serviço completo, o Electron deixa de ser obrigatório, e a distinção entre “app local” e “interface web” esbate-se até quase desaparecer.

É o tipo de funcionalidade que parece um pormenor até começares a usá-la todos os dias. Depois, quando precisas de ver qualquer coisa no Hermes e só tens um browser, lembras-te porque é que isto faz sentido.

Tags: #hermes #webapp #desktop