Hermes Bot Mode e Peer: local, remoto e cross-machine

Como transformar o seu Mac e a VPS em uma frota coerente de agentes — sem confundir Desktop, hermes serve, gateway, API server e hermes peer.

O seu cenário é bom para o Hermes: Desktop no Mac como janela de controle, uma VPS sempre ligada como backend operacional e, quando fizer sentido, agentes especializados conversando entre as duas máquinas. O ganho real não vem de espalhar processos por esporte. Vem de colocar cada tipo de trabalho no lugar certo e preservar uma fronteira clara de dados, credenciais e execução.

A resposta curta para o seu caso

Você pode manter os dois mundos sem escolher um único “Hermes central” para tudo:

Por que a aba Bots alcança todos os gateways, mas o chat normal não

A diferença é arquitetural, não um defeito misterioso do seu VPS. A aba Bots trabalha com o roster unido das conexões registradas no Desktop. O Bot Chat canônico é a conversa persistente que o Bot Mode gerencia; nela, o backend injeta o protocolo de colegas e o tool message_agent. Quando o alvo está em outra fonte, o Desktop usa o relay pela conexão que já mantém autenticada.

Já um chat aberto na aba Sessions é uma sessão regular pertencente a um único par (gateway, profile). Ele não herda automaticamente o roster multi-connection, o protocolo de Bot Mode ou o tool de handoff. Portanto, estar no mesmo Desktop não transforma toda conversa em um roteador distribuído — ainda bem; seria uma forma criativa de perder o controle de onde uma mutação executou.

A documentação oficial usa a frase “em qualquer chat” para descrever a resolução da menção no composer. O código atual deixa a fronteira operacional mais precisa: resolução pode ocorrer em qualquer composer; entrega cross-gateway exige um Bot Chat canônico gerenciado pelo Bot Mode. O teste mention-identification.test.mjs confirma que o renderer não faz entrega por conta própria.

Primeiro: o que você está chamando de “Hermes Bot”

Há três nomes próximos, mas eles descrevem camadas diferentes. Na instalação atual, hermes bot não é um subcomando de topo. O recurso aparece na documentação como Bot Mode, enquanto o transporte de mensagens entre gateways aparece como hermes peer.

Essa separação resolve a principal armadilha do desenho: o endereço usado pelo Desktop não é automaticamente o endereço usado pelo peer. O Desktop fala com hermes serve; o peer fala com o API server do gateway. A superfície administrativa HTTP, quando habilitada, é outro contrato — não substitua esses endpoints por ela sem verificar o protocolo.

Como esta documentação foi verificada

A página combina três tipos de evidência e não mistura seus níveis de certeza:

• comportamento documentado: documentação oficial do Hermes sobre Bot Mode, Desktop, múltiplas conexões, API server, profiles e gateways;
• implementação confirmada: checkout local na revisão 68518c1f9bca11d9f5dbdf59ecf7e024cce057ba, incluindo o comando peer, o protocolo de Bot Chat, o relay e o plugin de Bots;
• estado desta VPS: CLI hermes 0.20.5 (2026.8.19), probes HTTP/sockets e status realizados em 26 de agosto de 2026; o checkout local informa commits disponíveis no upstream, portanto este snapshot é datado.

O Mac não foi inspecionado diretamente nesta sessão. Por isso, os passos de instalação local são o caminho oficial recomendado; a primeira verificação no Mac deve ser hermes --version e hermes doctor. A versão do Desktop importa: o roster cross-machine exige uma build com o registro de múltiplas conexões.

A arquitetura mental correta

Pense em fonte, não apenas em “perfil remoto”. Uma fonte é um backend completo. Dentro dela existem perfis; cada perfil pode aparecer como um Bot. O Desktop pode listar várias fontes ao mesmo tempo, mas cada sessão, memória, rotina e execução continua pertencendo à máquina que hospeda o perfil.

As camadas operacionais

1. Desktop exibe a experiência, guarda o registro de conexões e abre sockets para os backends conforme necessário.
2. hermes serve atende o Desktop com JSON-RPC/WebSocket. No cenário documentado, o URL remoto termina em :9119.
3. Perfil é a fronteira de estado do agente: config.yaml, .env, SOUL.md, sessões, memória, skills, logs e cron.
4. Bot Mode coloca esses perfis num roster e adiciona a semântica de Bot Chat, rotina, grupo e handoff.
5. Gateway mantém canais e automações. Ele não é sinônimo do backend que o Desktop usa.
6. API server expõe uma superfície HTTP autenticada. Como executa tools no host onde está, deve ser tratado como acesso operacional privilegiado.
7. hermes peer usa a superfície de sessões do API server para criar ou reutilizar o Bot Chat remoto e executar um turno.

O que está configurado agora na sua VPS

A inspeção desta instalação mostra um ponto de partida bem definido. O backend remoto do Desktop está vivo, mas o transporte de peer ainda não está habilitado nesta máquina.

Evidência resumida da probe

$ hermes --version
Hermes Agent v0.20.5 (2026.8.19)

$ curl http://<overlay-host>:9119/api/status
HTTP 200
version: 0.20.5
auth_required: true
auth_providers: ["basic"]
auth_flows: ["cookie", "native_pkce"]
gateway_platforms: ["telegram: connected"]
profiles: ["default", "chamados"]
gateway_mode: "single"

$ curl http://<overlay-host>:8642/health
connection refused

Bot Mode em profundidade

O Bot Mode é uma camada de produto sobre perfis existentes. Não é uma segunda espécie de agente, não cria um banco de dados paralelo e não torna o perfil magicamente seguro. O Bot é o perfil; o plugin organiza e torna visíveis as capacidades que já pertencem a ele. Na versão atual, o recurso vem embutido no Desktop e fica ligado por padrão; pode ser desligado em Settings → Plugins → Bots sem apagar perfis, sessões ou cron jobs.

O painel Bots mudou bastante

A aba Bots não é apenas uma lista de perfis. Ela agora funciona como uma central de presença e atenção da frota:

• Active now mostra Bots ocupados ou com atividade recente; clicar no chip abre o Bot correspondente sem reordenar o roster.
• Search filtra o roster conforme você digita.
• Hide Bot é uma ocultação visual: não remove menções, grupos, rotinas ou mensagens. Bots ocultos acumulam unread silenciosamente e podem ser reexibidos pelo toggle de olho.
• Falhas que exigem atenção — provider não configurado, autenticação, quota ou Bot bloqueado — aparecem como estado de atenção; timeout e rate limit transitórios não devem virar badge permanente.
• Edit Profile altera avatar, título, descrição, modelo, skills, toolsets, MCP e SOUL.md; Duplicate cria um profile clonado com aparência copiada, mas não copia o chat; Delete Profile exige confirmação e não permite remover o default.
• O Bot tem metadados e avatar próprios: rosto determinístico, formas geométricas, imagem enviada, retrato gerado ou pet. Isso é identidade de interface, não isolamento de segurança.

Um Bot é um perfil

Um perfil tem seu próprio HERMES_HOME. No perfil default, isso costuma ser ~/.hermes; num perfil nomeado, ~/.hermes/profiles/<nome>. O perfil possui, de forma independente:

• modelo, provider e configurações;
• configuração de credenciais do agente; o Bot Mode pode compartilhar o pool OAuth/token principal, enquanto .env e tokens de plataformas precisam ser tratados por perfil;
• memória, sessões e histórico;
• SOUL.md, skills, toolsets e MCPs;
• cron jobs e logs;
• diretório de trabalho e acesso ao filesystem do host.

O Bot Chat canônico

Cada Bot possui um Bot Chat persistente. Esse é o ponto de contato estável usado por mensagens entre agentes, pelo Desktop e pelo hermes peer. A intenção é que você converse com “o Bot” sem criar uma sessão nova a cada clique.

• o chat canônico é criado e fixado quando o Bot nasce;
• o Bot Mode mantém essa conversa fora da lista global de sessões quando o backend suporta a flag de ocultação;
• /new e /reset no chat canônico são tratados como compactação para preservar a relação e a sessão, enquanto chats regulares continuam podendo criar sessões novas;
• o hermes peer dm procura uma sessão com título exato Bot Chat, cria uma se não existir e executa um turno nela.

Rotinas, grupos e menções

• Rotinas são cron jobs normais, nomeados com o padrão [bot:<nome>] <rotina>. O tile Routines fica ao lado do chat enquanto a aba Bots está ativa, usa um picker de agenda e mostra o resultado no chat do Bot.
• Grupos têm de 2 a 6 Bots. Uma mensagem pode gerar até três rodadas seriais, com limite de dez mensagens por envio.
• Menções escolhem quem deve responder. Sem menção específica, cada membro decide se tem algo novo a acrescentar; um membro pode passar.
• @user devolve uma decisão ao humano. A sala marca needs you quando um Bot pede intervenção.
• Cada membro mantém uma sessão persistente Group: <nome>; a sala não é um chat descartável nem um arquivo compartilhado.
• Cross-machine funciona quando o Desktop tem as fontes registradas. Um membro remoto executa na máquina dona dele e a sala exibe o dispositivo.
• Quando há nomes iguais, o handle exato usa @name-device, por exemplo @research-vps.
• Se um membro ficar bloqueado numa pergunta de esclarecimento ou aprovação de comando, a sala pode espelhar um card de decisão e manter a rodada aberta até você responder.

Os grupos agora também têm identidade durável e metadados compartilhados entre gateways conectados. O plugin espelha transcript recente, membros, nome, imagem e perguntas pendentes na metadata compartilhada do profile, usando revisões por gateway e merge para evitar que dois Desktops se sobrescrevam. O log completo de orquestração continua no armazenamento local do Desktop; o espelho é uma projeção limitada. Se um gateway cair, outro Desktop mantém a sala e pode re-semeá-la quando a conexão voltar. Renomear ou dissolver uma sala converge em todos os clientes; recriar um grupo com o mesmo nome começa uma sala nova. Se uma conexão for removida, membros órfãos permanecem marcados como Gateway removed, em vez de desaparecerem silenciosamente. Nada disso sincroniza filesystem, memória geral ou credenciais dos Bots.

O protocolo de mensagens que o Bot aprende

Quando o Desktop gerencia os perfis como Bots, o backend injeta no sistema do Bot Chat canônico uma seção de protocolo. Ela ensina o Bot a distinguir uma mensagem de outro agente, responder com atribuição e fazer handoff. A configuração central é:

agent:
  bot_mode_protocol: true

O padrão é ligado. A implementação atual não precisa editar o seu SOUL.md para cada mudança. O backend inclui um “capability epoch” e refaz o prompt do Bot Chat quando muda a superfície de skills, tools, MCP, roster ou peers. Isso é uma exceção controlada para uma mudança iniciada pelo usuário; não é uma desculpa para recriar o prompt em toda rodada e destruir prompt caching.

O protocolo inclui a lista de colegas, seus papéis e, quando configurado, os peers remotos. No Bot Chat canônico, o agente pode usar message_agent para enviar uma DM atribuída; o texto do usuário não é encaminhado cegamente, o Bot destinatário compõe sua própria resposta. Esse tool não aparece em chats regulares, sessões de grupo dos membros ou sessões CLI comuns.

Clone, Fresh profile e Create empty

A escolha feita em New Agent controla a base de capacidades do Bot. Clone from copia o diretório de skills instalado no perfil de origem; isso inclui bundled, Hub e skills criadas pelo usuário que estejam dentro daquele skills/. Fresh profile recebe o catálogo bundled, mas não suas skills personalizadas. Create empty cria sem bundled skills e mantém o opt-out para que hermes update não as reintroduza.

Na build atual, o formulário começa com cloneFrom = default. Se a intenção é um Bot realmente fresco, escolha explicitamente Fresh profile; não confie em simplesmente não abrir as opções avançadas.

Em nenhum desses casos existe herança viva. Depois de criado, o Bot administra suas skills no próprio profile: a UI de capacidades grava enablement por perfil, e uma skill instalada ou editada em outro Bot não aparece magicamente aqui. Para a mecânica completa de clonagem, enablement, manifestos e atualização, consulte Hermes Profiles: clonagem, skills e isolamento por agente.

Mac + VPS no mesmo Hermes Desktop

A forma mais simples de melhorar seu workflow é usar o registro de conexões do Desktop. A ideia atual é backend-first: primeiro você registra as máquinas; depois o Desktop enumera os perfis/Bots de cada fonte.

Como o registro de conexões funciona

Em builds atuais, abra Settings → Gateways. Builds mais antigas podem mostrar Gateway e Connections separados. O registro suporta Local, Remote gateway, SSH e Hermes Cloud.

1. Confirme que o Desktop no Mac está atualizado o suficiente para mostrar o registro de múltiplas conexões.
2. Mantenha a entrada Local gerenciada pelo app.
3. Adicione uma conexão Remote gateway com o URL do hermes serve da VPS, normalmente https://<host>:9119 ou o endereço privado equivalente.
4. Escolha a autenticação anunciada pela VPS. No estado observado, o backend informa basic; para internet aberta, prefira OAuth ou coloque o backend atrás de VPN.
5. Clique em Test. A validação correta precisa cobrir HTTP e WebSocket; um /api/status respondendo sozinho não prova que o chat vai transmitir.
6. Salve a conexão. O Desktop pode manter fontes registradas sem trocar a janela para a máquina remota.

Cada conexão recebe um device name único. Com várias fontes, uma é marcada como Primary para chamadas que não especificam gateway, mas isso não troca automaticamente o workspace atual. A preferência At startup, return to Sessions on the last-used gateway controla apenas o gateway restaurado após reiniciar o Desktop.

O roster é enumerado por REST e os sockets são abertos sob demanda; no tipo SSH, a conexão também é estabelecida quando necessária. A página Capabilities tem escopo (gateway, profile): instalar uma skill, toolset ou MCP para o draft remoto grava no backend remoto, sem trocar a sessão que está em primeiro plano.

A conexão remota é uma conexão com a máquina. O perfil é selecionado depois. Um perfil chamado default no Mac e outro chamado default na VPS são entidades diferentes. Não use o nome como se fosse identidade global.

Criar um Bot na máquina correta

Na aba Bots, use New Agent. Com mais de uma conexão, o diálogo apresenta Create on. Escolha explicitamente Mac ou VPS. O Desktop não precisa trocar o backend ativo para criar o perfil remoto.

• O clone vem de um perfil da máquina-alvo, não dos perfis locais do Mac.
• As capacidades exibidas para um draft remoto vêm do catálogo da máquina-alvo.
• O Bot aparece no roster com o dispositivo de origem depois que o backend-alvo o cria e o roster é atualizado.
• Um Connections Bot é uma entrada do roster; clicar nele não deve transformar silenciosamente todo o workspace em chats da VPS. Use o Bot Chat, uma menção ou a rota explícita (gateway, profile). Criar o profile também não garante, sozinho, que gateway, API server, porta ou WebSocket estejam prontos.

Exemplo de roster mental

Mac
  @mac-dev
  @reviewer

VPS
  @ops-vps
  @monitor-vps
  @deploy-vps

Atualizar a frota pelo Desktop

Com mais de uma conexão, Settings → Gateways → Update all instances despacha hermes update para cada backend elegível em paralelo. A conexão local usa o pipeline do app; remota e SSH atualizam a própria máquina; Hermes Cloud é reportado como gerenciado pela plataforma. O resultado é independente por conexão: uma VPS indisponível não deve esconder o estado das outras.

O mesmo fan-out aparece nas ações normais de update do Desktop quando há mais de um destino. Ainda assim, Docker, Nix e outros supervisores podem recusar a atualização automática; trate a mensagem por conexão como autoridade e valide a versão em cada host.

Usar menções no Desktop

No chat do Bot ativo, escreva algo como @ops-vps verifique o estado do workload X e me devolva só os fatos. O autocomplete ajuda a selecionar o Bot; a menção é resolvida contra o roster atual e o Bot ativo decide como fazer o handoff por message_agent. O Desktop encaminha a chamada para a conexão correta e a resposta volta como uma conclusão em background — não é uma espera síncrona que bloqueia seu chat até o Bot remoto terminar.

Se dois profiles têm o mesmo nome, use o handle source-qualified exato, como @research-homelab ou o formato exibido pelo Desktop. Renomear um Bot também atualiza a tag amigável; o nome antigo continua resolvendo para preservar conversas existentes. E-mails ou tokens @ que não correspondem a um Bot conhecido passam intactos, sem um handoff inventado.

Essa é a melhor opção quando você está coordenando o trabalho. Não exige que cada gateway conheça todos os outros via bot_peers; o Desktop já possui a identidade e o canal autenticado de cada conexão.

Falhas, limites e atenção

O Bot Mode mostra estados de atenção para falhas persistentes, como provider não configurado, autenticação, quota, modelo indisponível ou Bot bloqueado. O badge usa o motivo tipado quando disponível; timeout, rate limit e erro transitório de servidor podem ser resolvidos pelo retry e não devem virar alerta permanente sem necessidade.

message_agent continua sendo fire-and-forget: o Bot recebe um acknowledgement e a resposta pode voltar depois como notificação de conclusão. Depois que o turno de entrega é iniciado, uma falha tenta novamente no máximo uma vez, e somente quando isso pode ajudar: runtime offline, timeout de entrega, rate limit, erro de servidor e overflow de contexto. Os quatro primeiros retomam a mesma sessão; overflow compacta o contexto e retoma a mesma sessão. Auth, quota e configuração não são repetidos automaticamente. Nenhuma tentativa cria uma sessão nova.

Falhas carregam um reason estruturado junto do texto humano. A superfície atual inclui provider_auth_or_access, provider_quota_limit, provider_rate_limit, provider_server_error, context_overflow, missing_config, model_unavailable, runtime_offline, queued_expired, delivery_timeout, target_busy e unknown. A notificação pode exibir [reason: ...], permitindo distinguir “corrija autenticação” de “tente depois” sem analisar prosa de provider.

No relay, um roster fresco que prova que o destino está offline recusa a fila com runtime_offline; nada é enfileirado. Um envelope que espera além do TTL configurado (padrão de implementação: 900 segundos) expira com queued_expired e não é entregue tarde. Roster ausente ou antigo deixa a disponibilidade desconhecida e mantém o comportamento fail-open; portanto isso é uma proteção contra evidência positiva de indisponibilidade, não uma garantia de entrega.

A rota hermes peer dm é diferente: executa uma chamada síncrona para o Bot Chat remoto, tem timeout de até 600 segundos, faz uma tentativa e retorna exit codes 0, 1 ou 2. O chamador deve tratar falhas, repetir conscientemente quando fizer sentido e não assumir que um peer registrado está online.

Grupos cross-machine

Crie um grupo com, por exemplo, mac-dev, ops-vps e reviewer. Cada membro continua executando no próprio host. O transcript completo não é um arquivo único compartilhado: o plugin mantém uma sessão Group: <nome> em cada perfil participante, enquanto a metadata de gateway carrega apenas uma projeção recente e limitada para reidratar a sala e coordenar as rodadas.

Como deixar o Hermes local útil no Mac

Você disse que o Hermes local está quase sem configuração. Isso não é um problema; é melhor do que um Frankenstein com credenciais antigas, três providers meio quebrados e uma falsa sensação de isolamento. Faça um bootstrap mínimo e verificável.

Passo 1 — verificar a instalação

hermes --version
hermes doctor
hermes status --all

Se o Desktop foi instalado por pacote, ele pode preparar o runtime local durante o primeiro boot. Você não precisa duplicar a configuração da VPS para começar. O Desktop local é um backend próprio e usa o HERMES_HOME do Mac.

Passo 2 — configurar somente o necessário

1. Configure o provider/modelo no onboarding do Desktop ou com hermes setup.
2. Faça login no Mac pelo fluxo oficial. Não copie automaticamente auth.json, .env ou pools de credencial da VPS.
3. Escolha um diretório de trabalho local explícito para o perfil que edita código.
4. Mantenha approvals em modo smart ou manual; não transforme o Mac em --yolo por preguiça.
5. Habilite somente os toolsets que o Bot local realmente precisa.

Perfil local de desenvolvimento — exemplo

hermes profile create mac-dev \
  --description "Desenvolvimento local no Mac; edita projetos e executa testes." \
  --clone

hermes -p mac-dev setup
hermes -p mac-dev config set terminal.cwd /Users/<voce>/src
hermes -p mac-dev doctor

O exemplo usa --clone apenas como atalho para reaproveitar configuração. Se o perfil default estiver sujo ou incompleto, prefira hermes profile create mac-dev e configure conscientemente. O objetivo é separar o Bot de desenvolvimento do seu chat pessoal, não perpetuar lixo histórico.

Quando o Mac precisa de gateway próprio

Para conversar pelo Desktop local, o app gerencia ou inicia o backend local conforme a instalação. Para Telegram, Slack, cron e rotinas que precisam continuar com o app fechado, você precisa de um gateway persistente no host escolhido. Como o Mac dorme, ele não é o lugar padrão para rotinas críticas.

# Use apenas se este perfil realmente for hospedar um gateway local.
hermes -p mac-dev gateway install
hermes -p mac-dev gateway start
hermes -p mac-dev gateway status

Para o seu caso, a regra mais saudável é: Desktop local não implica gateway local. Deixe o gateway e os cron jobs de produção na VPS; ligue gateway no Mac apenas para um canal ou automação que pertença de fato ao Mac.

Divisão de trabalho que faz sentido

Uma boa convenção é colocar o host no nome visível e no description do Bot: ops-vps, “opera workloads em estrela; nunca assume que o filesystem é o Mac”. Isso reduz o risco de você pedir “rode isso aqui” e esquecer onde “aqui” fica.

Bot-to-bot por CLI: hermes peer

O hermes peer dm resolve o caso em que um agente na máquina A chama um Bot na máquina B sem uma janela do Desktop no meio: entrega no Bot Chat remoto, executa um turno e imprime a resposta. Depois que um peer é registrado, o protocolo do Bot Chat também inclui esse roster e o tool message_agent aceita alvos como vps ou vps/researcher. A alteração aparece no próximo turno por meio do capability epoch.

Quando usar e quando não usar

Pré-requisitos

1. O gateway destino precisa ter o adaptador api_server ligado.
2. O destino precisa ter uma chave forte API_SERVER_KEY.
3. A origem precisa alcançar o endereço pela LAN, Tailscale, ZeroTier, VPN ou HTTPS controlado.
4. O perfil que executa hermes peer precisa guardar a chave do peer em seu próprio escopo de credencial.
5. O Bot destino deve ser um perfil conhecido no gateway. Para o alvo sem sufixo, a implementação usa o perfil principal; para <peer>/<agent>, usa a rota multiplexada do perfil.

Habilitar o API server no gateway destino

No destino, configure o API server com os comandos suportados pelo Hermes. O comando config set roteia a chave secreta para o armazenamento de segredo; não coloque uma chave real no config.yaml manualmente.

hermes config set API_SERVER_ENABLED true
hermes config set API_SERVER_HOST <TAILSCALE_OU_OVERLAY_IP>
hermes config set API_SERVER_PORT 8642
hermes config set API_SERVER_KEY '<chave-forte-gerada-fora-do-chat>'
hermes gateway restart

O host padrão do API server é 127.0.0.1, mas ainda assim configure API_SERVER_KEY; loopback não transforma a API em um endpoint sem autenticação. Para outro host alcançar a porta, use o endereço privado específico, não 0.0.0.0 por reflexo. Mantenha firewall permitindo apenas a origem necessária. API_SERVER_CORS_ORIGINS fica desativado por padrão e não é necessário para uma chamada servidor-a-servidor; CORS só entra quando um browser chama diretamente a API.

Verificar antes de registrar o peer

curl -sS http://<TAILSCALE_OU_OVERLAY_IP>:8642/health

curl -sS \
  -H "Authorization: Bearer <API_SERVER_KEY>" \
  http://<TAILSCALE_OU_OVERLAY_IP>:8642/v1/models

curl -sS \
  -H "Authorization: Bearer <API_SERVER_KEY>" \
  http://<TAILSCALE_OU_OVERLAY_IP>:8642/v1/capabilities

O /health é apenas liveness — confirma que há um processo respondendo, não que o perfil, modelo ou gateway estão prontos. Use o /health/detailed autenticado quando precisar de readiness; o /v1/models confirma Bearer e o /v1/capabilities revela a superfície disponível. Como o peer usa /api/sessions, a prova final é um hermes peer dm real contra um Bot de teste, não apenas o healthcheck.

Registrar o peer na origem

No perfil que enviará a mensagem, registre o gateway remoto. Use um nome curto e estável; o nome é o identificador usado pelos Bots no protocolo.

# Perfil default da origem
hermes peer add vps \
  --url http://<VPS-OVERLAY-IP>:8642 \
  --key '<API_SERVER_KEY_DA_VPS>' \
  --note 'Gateway da VPS para operações'

hermes peer list

hermes peer dm vps \
  'Message from 🤖 mac (@mac): responda com hostname e estado do serviço principal.'

O corpo de peer dm é a mensagem fornecida pelo chamador. O transporte não acrescenta automaticamente o remetente; por isso os exemplos usam explicitamente Message from 🤖 .... Isso é diferente de message_agent, cujo protocolo Bot Mode identifica o remetente no contexto canônico.

Para não deixar a chave no histórico do shell, leia-a de um gerenciador de segredos ou use uma variável transitória e faça unset ao terminar. O comando armazena a credencial como HERMES_PEER_VPS_KEY no .env do perfil local; os nomes e URLs ficam no registro bot_peers da configuração. Registrar o peer não verifica que o destino está online: faça a probe HTTP e um peer dm de teste.

Para comunicação bidirecional

O registro é feito na origem. Se Bots dos dois lados precisam iniciar DMs, cada lado deve registrar o outro:

Mac  → registra vps
VPS  → registra mac

Não compartilhe a mesma configuração de peer entre máquinas por cópia de arquivos. Registre cada direção com a chave do destino e mantenha a chave no perfil que a utiliza.

Alvos, stdin e JSON

# Perfil principal do gateway remoto
hermes peer dm vps 'Message from 🤖 mac (@mac): status?'

# Perfil nomeado numa instalação multiplexada
hermes peer dm vps/researcher 'Message from 🤖 ops (@ops): compare os dados.'

# Mensagem via stdin, útil para scripts
printf '%s' 'Message from 🤖 monitor (@monitor): alerta resumido.' \
  | hermes peer dm vps --json

O comando retorna 0 em sucesso, 1 em falha de entrega/peer e 2 em erro de uso. --json inclui peer, perfil, session_id e resposta, o que permite encadear o resultado num script sem raspar texto humano.

O timeout de um DM pode chegar a dez minutos porque um turno do agente pode executar tools. Para um cron, prefira a invocação em background com a política do seu supervisor e capture stdout/stderr; não bloqueie o scheduler indefinidamente esperando uma resposta que já virou um incidente.

A diferença crítica: serve :9119 versus API server :8642

O API server executa o agente no host remoto. Se um Bot chamado pelo peer rodar pwd, ler um arquivo ou reiniciar um serviço, isso acontece na máquina do peer. O cliente que enviou a mensagem não empresta seu filesystem ao agente remoto.

Perfis nomeados e multiplexação

O alvo simples vps representa o perfil principal do gateway. O alvo vps/researcher usa a rota /p/researcher/ de um gateway com gateway.multiplex_profiles ligado.

hermes config set gateway.multiplex_profiles true
hermes gateway restart

Multiplexação é uma escolha operacional: um gateway default atende vários perfis e roteia por credencial ou prefixo. Ela é útil na VPS quando há vários Bots e um único supervisor é mais simples, mas reduz a separação de processo e de domínio de falha. Se um Bot precisa reiniciar independentemente dos demais, processos separados continuam sendo uma opção melhor.

Existe uma nuance de segurança importante: no API server multiplexado, a autenticação é ligada ao perfil do prefixo. A chave do perfil default não deve ser aceita no prefixo de um perfil nomeado; cada perfil nomeado pode precisar da própria API_SERVER_KEY. A versão atual documenta essa mudança como fail-closed.

Workflow recomendado para você

Fase 0 — manter a topologia simples

1. Deixe a VPS continuar sendo o backend remoto do Desktop na 9119.
2. Atualize o Desktop do Mac para uma build que mostre Settings → Gateways e o registro de conexões.
3. Configure o Hermes local default no Mac, sem criar uma frota de perfis antes de testar o básico.
4. Registre Mac e VPS no Desktop e confirme que cada fonte abre um chat na máquina correta.

Fase 1 — dois Bots com ownership claro

1. Crie mac-dev no Mac para projetos e testes locais.
2. Crie ops-vps na VPS para workloads, Docker, Caddy, logs e deploys.
3. Defina descrições que mencionem host, escopo e limites.
4. Use o Desktop para um handoff manual: @ops-vps confira o preflight, não altere nada.
5. Observe o hostname real e o cwd nos resultados de terminal. Não aceite “estou na VPS” como prova só porque o Bot disse isso.

Fase 2 — rotinas na máquina que nunca dorme

1. Coloque rotinas de monitoramento e digest no Bot da VPS.
2. Mantenha o gateway e o supervisor no mesmo host que possui os arquivos e canais.
3. Use saídas determinísticas para coleta e uma etapa de agente para resumir, evitando que cada cron vire um prompt gigante.
4. Defina alertas silenciosos quando não houver novidade.
5. Teste um clone one-shot ou execução manual sem alterar o schedule de produção.

Fase 3 — grupos cross-machine

1. Crie um grupo pequeno, por exemplo release, com mac-dev, reviewer e ops-vps.
2. Peça ao revisor para produzir riscos e ao Ops para apenas validar o ambiente.
3. Faça o deploy fora do grupo, num passo explicitamente autorizado e verificável.
4. Evite membros redundantes que apenas repetem a mesma resposta e consomem três rodadas de contexto.

Fase 4 — habilitar peer somente se houver um consumidor real

Só habilite a porta 8642 quando uma rotina ou Bot realmente precisar iniciar uma conversa em outra máquina sem passar pelo Desktop. Até lá, o registro de conexões e os grupos já entregam a maior parte do benefício sem criar outro endpoint privilegiado.

Topologia final sugerida

Mac
├── Hermes Desktop
├── conexão Local
│   └── mac-dev, reviewer
└── conexão VPS
    └── ops-vps, monitor-vps

VPS
├── hermes serve :9119       # Desktop
├── hermes gateway            # Telegram, cron, canais
├── api_server :8642         # opcional: peer DMs
└── perfis e arquivos de produção

Receitas operacionais

Identificar o host sem confiar na narrativa do Bot

Ao abrir um Bot de outra fonte, peça uma verificação operacional curta e leia o output da tool, não apenas o texto final:

hostname
pwd
printf 'profile=%s\n' "${HERMES_HOME:-default}"

Isso não substitui controles de segurança, mas ajuda a detectar um erro de roteamento cedo. A autoridade continua sendo o backend que recebeu a chamada e os logs do supervisor.

Handoff manual pelo Desktop

1. Abra o chat de mac-dev.
2. Mencione o handle desambiguado da VPS, por exemplo @ops-vps.
3. Especifique objetivo, contexto mínimo, resultado esperado e se a ação é leitura ou mutação.
4. Diga explicitamente “não altere nada” quando for investigação.
5. Se o retorno vier atribuído ao Bot errado, pare e verifique a conexão antes de continuar.

Handoff por script com resposta JSON

set -eu

MESSAGE='Message from 🤖 monitor (@monitor): verifique saúde e retorne JSON curto.'

printf '%s' "$MESSAGE" \
  | hermes peer dm vps --json \
  > /tmp/hermes-peer-result.json

# O arquivo deve ser tratado como dado de trabalho, não como autorização automática.
# Valide reply, peer, profile e session_id antes de tomar uma decisão.

Se o script transformar a resposta em ação, coloque uma etapa de validação e limites. Um Bot remoto pode devolver uma resposta plausível mesmo quando uma tool falhou; observabilidade e códigos de saída continuam necessários.

Verificar que o Bot Chat foi reutilizado

DMs sucessivos para o mesmo alvo devem reutilizar o Bot Chat canônico. Com --json, guarde o session_id e compare execuções. Se cada mensagem criar uma sessão diferente, você provavelmente está usando outro endpoint, outro título ou uma versão incompatível do gateway.

Segurança: onde o desenho pode dar errado

Superfície de rede

• Não exponha 9119 ou 8642 diretamente na internet só porque a porta respondeu.
• Prefira Tailscale, ZeroTier, VPN ou reverse proxy HTTPS com política restritiva.
• Para hermes serve, basic auth é aceitável para rede realmente confiável; para host público, prefira OAuth.
• hermes serve --insecure é deprecated/no-op nas builds atuais: não use essa flag esperando desabilitar autenticação. Bind público continua exigindo provider de auth.
• Para API server, use chave forte, bind privado e firewall por origem. A chave não é substituta de segmentação.
• Não habilite CORS globalmente. Se um browser precisar chamar a API, use allowlist explícita.

Segredos e perfis

• Configurações comportamentais ficam em config.yaml; credenciais ficam em .env ou no armazenamento suportado.
• O Desktop armazena tokens de conexão no keychain do sistema quando possível.
• API_SERVER_KEY fica no host destino; a origem guarda uma cópia de acesso como credencial do peer.
• hermes peer remove remove o registro, mas deixa a variável do segredo no .env; remova a credencial antiga manualmente quando não for mais necessária.
• Não copie auth.json, pools Codex, tokens de Telegram ou o .env inteiro da VPS para o Mac.

Permissões e ações perigosas

Um Bot de operações deve ter uma função clara. Se ele possui terminal e acesso ao Docker, trate-o como operador de produção. Use approvals, preflight, logs e confirmação para mutações. Não transforme o Bot Mode em um bypass de governança só porque o avatar é simpático.

Observabilidade e manutenção

O melhor workflow cross-machine é aquele que permite responder rapidamente a quatro perguntas: qual máquina recebeu a mensagem, qual perfil executou, qual sessão foi usada e qual processo estava saudável.

Há uma nuance observada nesta VPS: hermes serve --status não encontrou processos no escopo em que o comando foi executado, enquanto a probe HTTP e o socket mostraram o backend vivo. Isso é compatível com gerenciamento por Docker ou outro namespace de processo. Para serviços remotos, combine sempre supervisor, readiness HTTP e uma operação real; um único comando local não é oráculo universal.

Troubleshooting

O que não fazer

• Não use hermes peer contra a porta 9119 por tentativa. Primeiro identifique o contrato do endpoint.
• Não habilite 0.0.0.0 para “resolver rede” antes de configurar VPN, firewall e auth.
• Não copie todo o ~/.hermes da VPS para o Mac. Isso mistura sessões, segredos, cron e identidade.
• Não crie perfis demais no primeiro dia. Comece com um Bot local e um Bot remoto; adicione especialização quando houver uma fronteira real.
• Não deixe dois Bots editarem o mesmo checkout simultaneamente sem worktree, lock ou ownership claro.
• Não trate resposta de agente como prova de execução. Valide tool output, estado do serviço, diff, logs e código de saída.
• Não confunda Bot Mode com sandbox. Perfis isolam estado Hermes, não necessariamente o filesystem do usuário.
• Não use --yolo como configuração operacional padrão. A VPS merece sobreviver ao entusiasmo.

Plano de implantação proporcional

A sequência abaixo melhora o workflow sem introduzir duas novas superfícies de rede no mesmo dia:

1. Atualizar e verificar o Desktop no Mac. Confirmar registro de conexões e Bot Mode.
2. Configurar o default local. Provider, model, terminal.cwd, approvals e um primeiro chat real.
3. Registrar a VPS como Remote gateway. Testar HTTP, WebSocket, login e execução no host remoto.
4. Criar mac-dev e ops-vps nos backends corretos. Não clonar credenciais cegamente.
5. Usar menções e um grupo pequeno. Validar atribuição e desambiguação.
6. Mover rotinas contínuas para a VPS. Confirmar que cron e gateway estão sob supervisor.
7. Somente então habilitar o API server de peer. Fazer preflight de rede, auth, firewall e Docker.
8. Testar um DM read-only. Registrar session_id, resposta, logs e códigos de saída.
9. Adicionar a direção inversa apenas quando um caso de uso real exigir que um Bot da VPS inicie trabalho no Mac.

Fontes, comandos e arquivos consultados

Para manter a página auditável, estes são os materiais usados. A documentação oficial define o comportamento público; os arquivos de código confirmam detalhes de implementação; as probes definem apenas o estado desta instalação.

Documentação oficial

• Bot Mode — Bots, Bot Chat, rotinas, grupos, menções e peers.
• Profiles — isolamento, criação e clonagem de perfis.
• Skills System — seed, enablement, progressive disclosure e updates por perfil.
• Connecting Desktop to Many Hermes Instances — registro de conexões e roster de múltiplas fontes.
• Hermes Desktop — backend remoto, hermes serve, autenticação e limites do Desktop.
• API Server — endpoints, sessões REST, Bearer auth, multiplexação e segurança.
• Multi-profile gateways — multiplexação, prefixos /p/<profile> e isolamento.
• CLI commands — hermes peer, profiles, gateway e status.
• Environment variables — API_SERVER_* e auth do Desktop.

Código local confirmado

• website/docs/user-guide/bot-mode.md — texto oficial de Bot Mode nesta revisão.
• hermes_cli/subcommands/peer.py — registro de peers, segredo, endpoints, timeout, --json e exit codes.
• tools/bot_mode_probe.py — protocolo injetado no Bot Chat, roster de peers e capability epoch.
• apps/desktop/src/plugins/hermes-bots/plugin.js — roster, criação, Clone from, Fresh profile, Create empty, menções, grupos e roteamento por conexão.
• tools/bot_relay.py e tui_gateway/methods_bot_relay.py — roster, outbox/replies, TTL, fail-fast offline, locks e relay cross-connection.
• tools/bot_mode_dm.py — gate do message_agent, fire-and-forget, transporte local/peer/relay e retry condicionado.
• tools/bot_failure_reasons.py — vocabulário de motivos tipados e política de retry.
• agent/turn_context.py — injeção do tool somente no Bot Chat canônico.
• apps/desktop/src/plugins/hermes-bots/tests/mention-identification.test.mjs — menção como identificação, sem entrega pelo renderer.
• tests/tools/test_bot_failure_reasons.py, test_bot_relay.py e test_bot_mode_dm.py — retry, motivos, TTL, locks e contenção do tool.
• hermes_cli/profiles.py — clonagem, perfis, seed e isolamento de estado.
• tools/skills_sync.py — manifest bundled, hashes e proteção de skills editadas.
• tui_gateway/methods_profiles.py — criação e enablement de capabilities por perfil.
• apps/desktop/src/plugins/hermes-bots/tests/cross-connection-bots.test.mjs — contratos de roteamento e handles cross-machine.
• gateway/platforms/api_server.py — API REST, auth Bearer e listener do API server.
• website/docs/user-guide/features/api-server.md — contrato de sessões usado pelo peer.

Comandos executados nesta VPS

hermes --version
hermes --help
hermes peer --help
hermes profile create --help
hermes profile list
hermes serve --help
hermes gateway --help
hermes status --all
hermes serve --status
hermes sync status
hermes config path
hermes config get gateway.multiplex_profiles
hermes config get agent.bot_mode_protocol
hermes config get bot_mode.envelope_ttl_seconds
curl .../api/status
ss -ltnp

A página não contém chaves, tokens, nomes de credenciais ou conteúdo de .env. Os endereços e valores usados nos exemplos são placeholders; substitua-os somente no ambiente local e por canais seguros.