Tem outra coisa rodando o seu dashboard do Hermes — e agora um comando diz qual


Na semana passada você abriu localhost:8080 e o dashboard listou sessões que você não reconheceu. O ps aux | grep hermes voltou com três processos, dois deles com --profile, um vindo de um container. Você lembra vagamente de ter copiado uma unit systemd da documentação no inverno passado, de ter tentado Docker Compose logo depois, e do Desktop subindo um backend SSH em algum ponto no meio disso. A pergunta é simples e quase impossível de responder de memória: qual deles ainda está rodando, a qual instalação ele serve e em qual eu mexeria se quisesse arrumar a casa?

Até agora essa pergunta era respondida no chute. O hermes gateway migrate existe para juntar gateways por profile em um único gateway de host; ele nunca prometeu inventariar os serviços de fundo que sobraram na máquina. A nova flag que entrou na main depois da v0.23.1 cobre essa lacuna: hermes gateway migrate --backends, um comando apenas de relatório.

Vamos ser precisos sobre o que ele não faz, porque ele faz muito pouco: não para, não reinicia e não mata nada. Não grava service file, unit, plist nem ledger. Não abre conexão de rede. A migração de backend em si não está implementada — todo registro termina com o mesmo aviso: Report only: changes no service; backend migration is not available yet.

Por que ele precisa olhar sem tocar

Este é o contexto. O Hermes nunca instala um serviço de fundo para hermes serve ou hermes dashboard. Todo backend que você encontra numa máquina foi configurado por outra pessoa: uma unit systemd copiada da documentação, um plist de launchd escrito à mão, a unit hermes-backend do NixOS ou do Home Manager, o slot longrun dashboard do s6 na imagem Docker, um sidecar de Compose, um backend SSH do Desktop, ou um processo que você subiu num terminal numa tarde qualquer e nunca parou.

Isso cria uma situação incômoda. A única fonte confiável de verdade sobre “quantos backends existem e de quem eles são” é o que o processo realmente executa e a qual MainPID ele pertence — nunca o nome da unit. O Nix chama a sua de hermes-backend; a cópia que você fez da documentação pode ser hermes-serve.service; no container, é o nome de um slot. Casar por nome tem garantia de perder coisas.

Então a coleta é deliberadamente estreita: roda ps, lê /proc e plists, e dispara consultas systemctl show / list-unit-files e launchctl print. Só isso. De propósito, ela não lê o spawn ledger, porque ler um ledger corrompido o coloca em quarentena (renomeia o arquivo), e um relatório read-only não deveria ter esse efeito colateral.

Um detalhe fácil de escapar: a inicialização normal do Hermes ainda roda antes — ela cria o layout do HERMES_HOME, grava um SOUL.md padrão quando ele não existe, registra a instalação em HERMES_HOME/installs/<id>/, abre logs/agent.log e logs/errors.log e faz prune em cache/scratch. Ou seja, não é livre de efeitos colaterais; eles apenas ficam dentro dos diretórios do próprio Hermes e nunca tocam serviços do sistema operacional.

Como usar: duas chamadas e um formato JSON

hermes gateway migrate --backends            # relatório legível para humanos
hermes gateway migrate --backends --json     # o mesmo relatório em JSON

O exemplo da documentação também traz --dry-run, que no modo relatório não acrescenta nada — de um jeito ou de outro o comando não altera coisa alguma, e ele não rejeita a flag.

A saída em texto é assim (formato tirado de format_report):

Serve/dashboard background services (report only; nothing was changed)

• systemd hermes-serve.service (user): PID 41221
    runs:    /root/.hermes/hermes-agent/.venv/bin/python -m hermes_cli serve
    file:    /root/.config/systemd/user/hermes-serve.service
    state:   enabled
    home:    /root/.hermes (this HERMES_HOME)
    report:  Report only: changes no service; backend migration is not available yet.
• container (docker): PID 902
    runs:    python -m hermes_cli serve --host 0.0.0.0 --port 8080
    report:  Report only: changes no service; backend migration is not available yet.
    note:    The process belongs to a container defined by a Compose file or run command.

O JSON é um wrapper fixo:

{
  "applied": false,
  "backends": [
    {
      "supervisor": "systemd",
      "running": true,
      "pid": 41221,
      "argv": ["/root/.hermes/hermes-agent/.venv/bin/python", "-m", "hermes_cli", "serve"],
      "unit": "hermes-serve.service",
      "scope": "user",
      "unit_path": "/root/.config/systemd/user/hermes-serve.service",
      "state": "enabled",
      "hermes_home": "/root/.hermes",
      "this_home": true,
      "not_applied": "Report only: changes no service; backend migration is not available yet.",
      "notes": []
    }
  ]
}

applied é sempre false. Não é um placeholder esquecido: os mantenedores removeram da saída um campo de sugestão de migração porque o desenho da migração de serviço ainda não foi aprovado. O relatório declara apenas fatos do presente — nenhuma chave de conselho, nenhuma chave would.

O que os campos realmente significam

Os dois campos que valem a leitura são supervisor e notes, porque respondem “quem é responsável por manter este processo vivo”:

supervisor Significado
systemd A unit foi escrita à mão (o Hermes nunca instala uma)
nix-systemd O arquivo da unit é gerado pelo Nix e é read-only
launchd O plist foi escrito à mão
nix-launchd O plist é gerado pelo Nix e é read-only
s6 O slot é declarado pela imagem do container
container O processo pertence a um Compose file ou a um docker run
desktop-ssh / desktop-local Pertence a uma sessão SSH do Desktop ou ao app Desktop
detached Nenhum supervisor o controla
manual Iniciado a partir de um shell ou de outro programa
unknown Não foi possível identificar o supervisor

hermes_home e this_home respondem à outra metade da confusão. Um mesmo usuário pode ter várias instalações e vários profiles, e o serviço em execução não serve necessariamente o HERMES_HOME em que você está agora. O relatório marca (this HERMES_HOME) para você ver de relance se aquele backend é o que você está usando.

Detecção: pelo que ele executa, depois pelo nome que tem

Backends em execução são encontrados pela linha de comando, então uma unit chamada foo.service que por acaso roda hermes serve continua aparecendo na lista.

Units habilitadas mas paradas no momento só entram na lista quando o nome casa com um de três padrões: hermes-serve*, hermes-dashboard*, hermes-backend*. Isso espelha a passagem systemd do hermes update, que também cobre apenas esses três prefixos (incluindo a hermes-backend.service do Nix). Nomes fora deles não são tocados por nenhum dos dois comandos.

Um detalhe de macOS vale saber: um processo iniciado pelo launcher backend.waitFor do Nix mantém a posse do launchd e o home do plist. Um processo ppid-1 sem correspondência fica como unknown, em vez de ser classificado como detached. Em outras palavras, ele prefere dizer “não sei” a te entregar uma resposta errada.

Para que serve e para que não serve

Três usos se sustentam:

  1. Inventário antes da limpeza. Antes de apagar uma unit esquecida, rode isto uma vez e confirme qual HERMES_HOME ela serve, para não deletar a instalação que você ainda usa.
  2. Debug de instalação obsoleta. Se o dashboard mostra sessões que não batem com a sua máquina, provavelmente você está falando com o backend do container, e não com o local.
  3. Scripts de operação read-only. --json mais applied: false tornam seguro encaixar o comando num script de monitoramento: exit code 0 mesmo quando um scan falha, e nenhuma chance de uma sonda alterar a máquina.

O que ele não faz:

  • Não migra nada. Não existe --apply nem saída com sugestões. Juntar dois gateways por profile em um gateway de host continua sendo o hermes gateway migrate puro (--multiplex, que o hermes update roda por você); --backends é um relatório paralelo.
  • Recusa --yes e --multiplex. O comando sai com código 2 e a mensagem “--backends is a read-only report”, para ninguém confundir com migração.
  • Não muda o hermes update. Units fora daqueles três prefixos continuam fora do alcance do hermes update.

Status: na main, fora da v0.23.1

O PR #152245 entrou em 2026-11-10 às 15:40 UTC, enquanto a tag v0.23.1 aponta para um commit de 10-11 00:24 UTC — quase um dia antes. Então:

  • na v0.23.1 ou em qualquer versão anterior, hermes gateway migrate --backends é uma flag desconhecida e o comando ainda não existe;
  • numa instalação a partir do código, acompanhando a main, ele funciona hoje.

Atualização (17/11/2026): essas mudanças saíram na v0.23.2 (16 de novembro): um hermes update as traz. O « não está na v0.23.1 » acima é um retrato da data de publicação.

Para explorar mais a camada de gateway, a referência do comando gateway cobre toda a superfície, e dois posts anteriores aprofundam a mesma fronteira: ajustar o watchdog do loop de gateway e como o Desktop salva conexões de gateway. Se você roda vários profiles, o post sobre a allowlist de profiles faz a mesma pergunta sobre onde fica a borda.

Um comando read-only não é empolgante. Mas “quantos backends estão rodando nesta máquina” costumava ser respondido apertando os olhos no systemctl list-units e chutando. Agora existe algo para ler.