Hermes Desktop

O aplicativo desktop do Hermes é um app nativo construído em volta do mesmo agente que você usa na CLI e no gateway — mesma configuração, mesmas chaves de API, mesmas sessões, mesmas skills, mesma memória. Não é um produto separado nem um clone leve; ele usa o mesmo núcleo e as mesmas configurações do Hermes Agent, e conduz tudo por uma interface moderna e bem pensada. Se você já usou hermes no terminal, tudo o que configurou lá já está aqui, e tudo o que fizer aqui aparece lá.

Ele roda em macOS, Windows e Linux.

Qual interface é qual?

O Hermes tem várias interfaces que conversam com o mesmo agente:

• Aplicativo Desktop (esta página) — um aplicativo nativo com uma interface feita sob medida para conversa, configuração e gerenciamento.
• CLI (hermes) e TUI (hermes --tui) — interfaces de terminal.
• Painel Web (hermes dashboard) — um painel de administração no navegador; a aba opcional Chat embute a TUI por um pseudoterminal.

Escolha a que servir melhor ao momento. Elas compartilham estado, então você pode começar uma sessão em uma e retomar em outra.

Instalação

Baixe o aplicativo na página do produto Hermes Desktop ou siga as instruções de instalação do Hermes Desktop.

Se você já tem o Hermes instalado, basta rodar

hermes desktop

Isso usa sua configuração, suas chaves, suas sessões e suas skills atuais.

O que tem no aplicativo

O aplicativo desktop é organizado como uma janela centrada na conversa, com uma barra lateral esquerda de navegação. Ele foi feito para permitir gerenciar várias conversas simultâneas com agentes, configurar provedores de mensagens, criar artefatos, navegar pela estrutura de pastas dos projetos e trabalhar em vários projetos ao mesmo tempo.

Chat

O centro do aplicativo. Você tem:

• Respostas em streaming com atividade de ferramentas ao vivo e resumos estruturados das chamadas de ferramenta enquanto o agente trabalha.
• O mesmo histórico de conversa de qualquer outra interface do Hermes — sessões iniciadas aqui são retomadas na CLI/TUI e vice-versa.
• Arrastar e soltar arquivos em qualquer ponto da área de conversa para anexá-los à sua próxima mensagem.
• Um painel de pré-visualização à direita — renderize páginas web, arquivos e saídas de ferramentas lado a lado enquanto continua conversando.
• Histórico do compositor e edição da fila — aperte as setas para cima/baixo com o compositor vazio para recuperar e reaproveitar prompts anteriores, e edite mensagens que você enfileirou antes de serem enviadas. Apertar Stop (ou Esc) com turnos na fila pausa a fila e a expande acima do compositor; retome dali, ou envie, edite e exclua entradas individuais.
• Uma régua de linha do tempo da conversa — conversas longas ganham uma régua fina de marcadores na borda da transcrição, um por prompt. Passe o mouse para abrir a lista de prompts e clique em um para pular direto àquele ponto da conversa. (Ela aparece quando a conversa acumula alguns turnos.)
• Buscar na página — aperte Cmd/Ctrl+F para abrir uma barra de busca que procura na transcrição renderizada. Enter / Shift+Enter (ou Cmd/Ctrl+G / Cmd/Ctrl+Shift+G com a barra aberta) percorrem os resultados; Esc fecha.

Barra de status

A barra na parte de baixo da conversa mostra o estado da sessão ao vivo e expõe controles rápidos sem abrir as Configurações:

• Alternador de YOLO por sessão — liga ou desliga o YOLO só nesta sessão (igual à TUI). O YOLO pula os pedidos de aprovação de comandos perigosos, então saiba o que você está desligando — veja Segurança → Modo YOLO.
• Medidor de uso de contexto — um medidor ao vivo de "% cheio" da janela de contexto da sessão. Clique nele para abrir o popover Uso de Contexto, com a divisão de tokens por categoria (prompt de sistema, definições de ferramentas, skills, memória, regras, MCP, definições de subagentes e a própria conversa), para você ver exatamente o que está consumindo a janela antes de a compressão entrar em ação.
• Itens personalizáveis — clique com o botão direito na barra de status (Show in status bar) para escolher o que aparece: o medidor de contexto, o espaço de trabalho, o modelo, as aprovações, os cronômetros de turno/sessão, o terminal, o Command Center, a versão do backend e mais — ou esconda a barra por completo (Cmd/Ctrl+Shift+S alterna).

Está conversando com uma instância do Hermes em outra máquina em vez do backend local embutido? Veja Conectar a um backend remoto mais abaixo — e, para o quadro completo de como funciona a conexão com o painel hospedado remotamente (o portão de autenticação, o socket de conversa /api/ws e a triagem de códigos de fechamento de WebSocket), veja Painel Web → Conectar o Hermes Desktop a um backend remoto.

Descoberta de repositórios

O Hermes Desktop descobre repositórios Git locais para a barra lateral de Projetos varrendo seu diretório pessoal até uma profundidade limitada. Você pode mudar isso por perfil em Settings → Workspace, ou no config.yaml:

desktop:
  repo_scan_enabled: true
  repo_scan_roots: []
  repo_scan_exclude_paths: []

• Use repo_scan_enabled: false para parar completamente a varredura do sistema de arquivos. As linhas de cache de descoberta em disco daquele perfil são apagadas; projetos explícitos e repositórios inferidos de sessões intencionais do Hermes continuam disponíveis.
• Use repo_scan_roots com uma lista de pastas para restringir a varredura. Uma lista vazia preserva a varredura padrão do diretório pessoal.
• Use repo_scan_exclude_paths com as pastas cujas subárvores inteiras devem ser puladas.

Mudar qualquer um desses valores invalida apenas o cache de descoberta em disco daquele perfil e inicia uma atualização que respeita a política. Hide from sidebar continua sendo uma ação de curadoria separada, item a item.

Escolher um modelo

O seletor de modelo fica no compositor, logo à esquerda do microfone. Clique nele para trocar o modelo, o esforço de raciocínio e o modo rápido em um único menu.

• O seletor do compositor é estado de interface fixo e nunca mexe no seu padrão. Ele é lembrado localmente (por dispositivo) e acompanha você em conversas novas e reinícios, em vez de voltar ao padrão — escolha um modelo uma vez e o próximo Cmd/Ctrl+N já abre nele. Com uma conversa em andamento, trocar de modelo limita a mudança àquela conversa atual; de todo jeito a seleção viaja junto quando a sessão é criada/trocada e nunca é gravada como padrão do perfil. (Trocar de perfil faz o seletor voltar ao padrão daquele perfil.)
• Defina o padrão em Settings → Model. Esse modelo "main" é o seu padrão global por perfil — é dele que partem conversas novas, crons, subagentes e tarefas auxiliares, e é o único lugar que o grava. Cada perfil mantém o seu próprio padrão.
• Presets de esforço/modo rápido por modelo. No aplicativo desktop, cada modelo lembra o seu próprio esforço de raciocínio e a sua escolha de modo rápido, reaplicados à sessão sempre que você seleciona aquele modelo. Esses presets são uma conveniência do desktop e não mudam crons nem subagentes.
• Trocar de modelo no meio da conversa zera o cache de prompt. Trocar o modelo dentro de uma conversa viva significa que a próxima mensagem relê a conversa inteira pelo preço cheio de entrada (os caches de prompt dos provedores são indexados por modelo). Tudo bem de vez em quando; numa conversa longa, começar uma conversa nova no modelo novo costuma sair mais barato do que ficar indo e voltando.

Navegador de arquivos

Explore e pré-visualize o diretório de trabalho sem sair do aplicativo — útil para acompanhar enquanto o agente lê, escreve e edita arquivos. Defina o diretório inicial do projeto com hermes desktop --cwd <caminho> (ou com a variável de ambiente HERMES_DESKTOP_CWD).

Artefatos

A visão Artifacts reúne o que suas sessões geram — imagens, arquivos e links — em uma galeria única, pesquisável e navegável. Abra pela barra lateral, pela paleta de comandos (Artifacts — Browse generated outputs) ou por um atalho nav.artifacts que você mesmo defina. Ela indexa automaticamente as saídas recentes das sessões; cada artefato mostra qual sessão o produziu, com um atalho de volta para aquela conversa, e imagens e arquivos abrem em uma pré-visualização com ações de baixar / abrir no navegador / copiar.

Janelas, abas e painéis

O aplicativo foi feito para trabalhar em várias coisas ao mesmo tempo:

• Abas — Cmd/Ctrl+T abre uma nova aba de sessão; Ctrl+Tab / Ctrl+Shift+Tab circulam entre sessões, e Ctrl+1…9 pulam para uma sessão recente pela posição. Cmd/Ctrl+W fecha a aba em foco e Cmd/Ctrl+Shift+T reabre a última fechada.
• Várias janelas — Cmd/Ctrl+Shift+N abre uma janela nova, e qualquer sessão pode ser destacada pelo menu de contexto (New window) ou pela paleta de comandos. Uma janela destacada renderiza aquela conversa sozinha, sem a barra lateral global — ótimo para deixar uma sessão longa rodando em outro monitor. A saída do agente ao vivo é transmitida para todas as janelas que mostram a sessão.
• Painéis — Cmd/Ctrl+B alterna a barra lateral esquerda, Cmd/Ctrl+J a direita, e Cmd/Ctrl+\ troca de lado as barras laterais.

Terminal

Um terminal de verdade mora na barra lateral direita, ao lado do navegador de arquivos:

• Ctrl+** mostra o terminal (abrindo um se não houver nenhum); **Ctrl+Shift+ cria mais um. Vários terminais se empilham numa régua de abas — Ctrl+Shift+↓/↑ navegam entre eles, Ctrl+Shift+W fecha o ativo.
• Os shells continuam vivos enquanto escondidos. Fechar ou esconder o painel não mata o seu shell — todo terminal aberto continua montado, com o histórico de rolagem e os processos em execução intactos, até você fechá-lo explicitamente.
• Add to chat — selecione a saída do terminal e mande para o compositor como contexto da sua próxima mensagem.

Revisão de Git e worktrees

Para sessões rodando dentro de um repositório Git, o aplicativo tem uma superfície de controle de versão embutida:

• Painel de revisão — Cmd/Ctrl+G alterna o painel de revisão da árvore de trabalho: branch e situação de commits à frente/atrás, arquivos alterados (em lista ou em árvore) e diffs limitados a Uncommitted, Branch ou Last turn (só o que o agente mudou no turno mais recente). Adicione ou tire arquivos do stage, reverta mudanças, escreva uma mensagem de commit (ou use Generate commit message) e então Commit ou Commit & Push — e Create PR pela CLI do GitHub (gh), ou entregue tudo ao agente com Ask Hermes to open PR. Daqui você também cria e troca de branch.
• Worktrees — Cmd/Ctrl+Shift+B (ou New worktree em um projeto na barra lateral) cria um worktree do Git em um branch novo, para que um agente possa trabalhar em uma cópia paralela do repositório sem tocar no seu checkout. Worktrees aparecem como faixas próprias sob o projeto; ao remover um, você escolhe apagar o diretório do worktree (o branch fica) ou apenas esconder a faixa e deixá-lo no disco, com uma opção de forçar quando há mudanças não commitadas.

Grafo de Memória

O Memory Graph (paleta de comandos → Memory Graph, ou o item na barra de status) é um mapa interativo do que o Hermes aprendeu para você — skills e memórias dispostas como um grafo de nós com zoom e uma linha do tempo, filtrável por All / Used / Learned. Um controle de compartilhamento exporta o layout do mapa como um código compacto que você pode colar para outra pessoa (só o layout — nenhum texto da sua memória ou das suas skills vai junto) e importa códigos do mesmo jeito.

Quick Entry

O Quick Entry é um pequeno compositor sempre disponível, chamado por uma tecla de atalho global de qualquer lugar do sistema — dispare um prompt sem trocar para a janela principal (nem mesmo abri-la). Ative em Settings → Advanced → Quick Entry; o atalho padrão é Ctrl/Cmd+Shift+Space e você pode definir o seu (precisa de pelo menos um modificador). Se outro aplicativo já usa a combinação, a linha das configurações avisa para você escolher outra.

Voz

Fale com o Hermes e ouça a resposta, o mesmo modo de voz disponível nas outras interfaces. No macOS o sistema pede acesso ao microfone uma vez.

Modo HUD

⌘/Ctrl+Shift+H (ou o botão na barra de título) desprende a conversa em uma barra flutuante sem moldura e sempre no topo, que fica por cima daquilo em que você está trabalhando. A janela do aplicativo sai de cena; o HUD mantém sua conversa viva e um compositor. Onde você estaciona a barra é contexto — a posição dela diz ao Hermes sobre qual aplicativo e qual tela você está perguntando, então "isto", "aqui" e "essa página" resolvem para o que está embaixo dela.

• Mover a barra — no macOS e no Windows, pressione e segure em qualquer ponto do compositor por um instante e então arraste. No Linux/X11, segure Ctrl e arraste com o botão principal do mouse para pegar na hora (inclusive sobre texto selecionado); pressionar e segurar também continua funcionando. Mantenha a pegada enquanto aciona o atalho de troca de área de trabalho para levar o HUD para outra área de trabalho virtual. No Wayland nativo, a barra do compositor é uma alça de arrasto do compositor gráfico (a única forma de movê-la, porque um aplicativo não pode posicionar a própria janela).
• Redimensionar — arraste qualquer borda ou canto da barra; a borda oposta fica ancorada. O Wayland nativo expõe as bordas direita e inferior, porque o compositor não deixa aplicativos posicionarem janelas de topo por conta própria.
• Resetar o layout — o controle de descarte na barra restaura o tamanho padrão e (no X11 / macOS / Windows) a posição. Use isto se um tamanho persistido deixar o HUD inutilizável.
• Ir até o ponteiro — ⌘/Ctrl+Shift+G (uma tecla de atalho global, funciona de qualquer aplicativo) leva o HUD para onde estiver o seu cursor. No Wayland nativo isso não faz nada — o posicionamento é do compositor.
• Sair — clique no botão de sair na barra, ou aperte ⌘/Ctrl+Shift+H de novo. A janela do aplicativo volta com sua sessão intacta.

Linux / Wayland

O Electron 20+ já roda como cliente Wayland nativo em uma sessão Wayland. Arrastar, clicar através e redimensionar funcionam nesse caminho.

No Hyprland (incluindo o Omarchy) o HUD é flutuado e fixado pelo IPC do compositor depois que é mapeado — caso contrário o Hyprland o encaixa como qualquer outra janela, always-on-top é ignorado e o arrasto pelo compositor não faz nada. Nenhuma regra extra de janela é necessária.

Alguns compositores (o COSMIC em especial) ignoram always-on-top para janelas Wayland nativas. Para recuperar a fixação neles, rode o aplicativo sob XWayland:

desktop:
  ozone_platform_hint: x11

Isso vira ELECTRON_OZONE_PLATFORM_HINT na inicialização (uma variável de ambiente explícita ainda tem prioridade). O preço: o X11 não consegue restaurar uma janela que ignorou o mouse, então o HUD fica uma janela sólida em vez de clicável através. Algumas configurações de KDE também relatam problemas de teclado com o backend ozone X11 — deixe a dica em auto a menos que você precise do sempre-no-topo.

Configurações e primeiros passos

Gerencie provedores, modelos, ferramentas e credenciais por uma interface de verdade em vez de editar YAML. A introdução da primeira execução leva você à primeira mensagem em segundos. Os painéis de configuração cobrem provedores/chaves, seleção de modelo, configuração de conjuntos de ferramentas, servidores MCP, o gateway e o gerenciamento de sessões.

• Painel de configurações de provedores — um lugar dedicado a gerenciar provedores de inferência, com uma experiência de Contas / chaves de API para entrar e guardar credenciais por provedor.
• Todo provedor e todo modelo nos menus — a interface gráfica mostra a lista completa de provedores e todos os modelos que o hermes model conhece, então você escolhe do mesmo catálogo que a CLI vê, e não de um subconjunto curado.
• xAI Grok OAuth — o Grok é um provedor OAuth de primeira classe no lançador; entre pelo fluxo do navegador como nos outros provedores OAuth.
• Instalação de backends de ferramenta pela interface gráfica — rode os passos de instalação pós-configuração de um backend de ferramenta direto do aplicativo, sem cair no terminal.
• Seletor de fonte do terminal — escolha uma fonte instalada em Settings → Appearance. Nerd Fonts como a MesloLGS NF renderizam os separadores e ícones do Powerlevel10k tanto nos terminais interativos quanto nos do agente; a configuração é salva por perfil.
• Aviso de modelo auxiliar — se você trocar o modelo principal para um provedor novo enquanto tarefas auxiliares (títulos, sumarização e ajudantes parecidos) continuam presas a outro provedor, o aplicativo avisa, para você não dividir o trabalho entre dois provedores sem perceber.
• Temas do VS Code Marketplace — além dos temas embutidos, as configurações de aparência trazem uma busca ao vivo no VS Code Marketplace: escolha qualquer tema de cores e o aplicativo baixa, converte e instala como tema do desktop. O mesmo importador está na paleta de comandos (Install theme), e temas importados podem ser removidos de novo pelas configurações de aparência.
• Manter o computador acordado — Settings → Advanced → Keep computer awake impede a máquina de dormir, para que execuções longas ou noturnas do agente continuem (a tela ainda pode escurecer). É uma configuração por computador.

A introdução da primeira execução foi redesenhada sobre um sistema de design unificado em overlay, e você pode escolher Choose provider later para pular a configuração de provedor e entrar no aplicativo primeiro.

Configurações por perfil: o escopo "Applies to"

Quando você tem dois ou mais perfis, as páginas de configuração ligadas ao arquivo de config — Model, Workspace, Safety, Memory & Context, Voice, Chat, Advanced e Tools & Keys — e o overlay de Messaging mostram no topo uma faixa compartilhada de chips Applies to. Ela seleciona qual perfil suas edições afetam:

• A seleção padrão acompanha o perfil ativo, que se comporta exatamente como antes — você edita o perfil que está usando.
• Escolha outro perfil para ver e editar as configurações dele sem trocar o aplicativo inteiro; a seleção persiste enquanto você navega entre as páginas de configuração.
• Trocar o perfil ativo do aplicativo reseta o seletor, para que as edições não continuem caindo silenciosamente em um perfil selecionado antes.
• Com menos de dois perfis, a faixa de chips fica escondida por completo.

(A página Gateways trata perfis de outro jeito — pela subseção Per-profile overrides — e as visões Capabilities e Scheduled Jobs têm seus próprios seletores de escopo.)

Painéis de gerenciamento

O aplicativo também expõe a superfície mais ampla de gerenciamento do Hermes, para você não precisar cair no terminal:

• Skills — navegue, instale e gerencie skills.
• Grafo de memória (Star Map) — digite /journey (aliases /learning, /memory-graph) na conversa para abrir uma constelação interativa de skills e memórias aprendidas ao longo do tempo, com um controle de reprodução. Os nós podem ser editados ou apagados direto do painel (skills são arquivadas, memórias removidas). Veja Jornada de Aprendizado.
• Cron — veja e gerencie as tarefas agendadas.
• Profiles — troque entre perfis do Hermes (config/skills/sessões isolados).
• Messaging — configure os canais do gateway.
• Agents e Command Center — superfícies de orquestração para trabalho com vários agentes.

Bot Mode (embutido)

O Bot Mode vem com o aplicativo e está ligado por padrão: um elenco de "uma conversa por agente" em que cada perfil do Hermes aparece como um bot com avatar próprio (rosto geométrico, imagem enviada, retrato gerado por IA ou um pet em pixel art), sua conversa canônica de Bot Chat e suas Routines (tarefas recorrentes apoiadas no cron do Hermes). O elenco mora na barra lateral esquerda como uma aba ao lado das suas conversas — uma faixa de abas Sessions | Bots — em vez de um segundo painel empilhado abaixo da lista de sessões. Instalações que pegaram o layout empilhado antigo são migradas para a faixa de abas automaticamente, uma vez; se você posicionou painéis à mão, seu layout fica como está. O painel Cronjobs (Routines) encosta ao lado da conversa só enquanto a aba Bots está ativa e some quando você volta para Sessions (versões mais antigas do desktop o deixam sempre visível).

Crie agentes novos a partir do elenco — Nome / Título / Descrição mais uma seção Advanced com toda a superfície de capacidades (modelo, SOUL, skills, conjuntos de ferramentas, servidores MCP) —, agrupe-os em seções e abra conversas em grupo onde vários bots deliberam. Conversas em grupo aparecem como linhas independentes no estilo do Discord no elenco — avatares de membros empilhados, contagem de membros, uma prévia da última fala da sala e o selo "needs you" — intercaladas com as linhas dos bots na mesma ordenação por fixação e recência. Clicar na linha de um grupo abre a sala como uma aba que toma conta da janela principal de conversa (versões mais antigas do desktop caem para abri-la dentro do painel lateral de bots).

Os bots mandam mensagem uns para os outros: digite @researcher have a look at this em qualquer conversa e o bot ativo repassa a mensagem e volta com a resposta, e os bots alcançam diretamente os Bot Chats uns dos outros (hermes -p <bot> chat). O backend ensina o protocolo de mensagens à sessão canônica de Bot Chat de cada bot automaticamente (config agent.bot_mode_protocol, ligada por padrão) — inclusive quando um bot colega a abre sem interface a partir da CLI — para que respostas e repasses entre bots funcionem sem mexer no seu SOUL.md, e suas sessões normais fiquem intocadas.

As sessões do Bot Mode — o Bot Chat canônico de cada bot e cada sessão de membro de conversa em grupo — ficam sempre escondidas da barra lateral global de Sessions. Elas vivem no painel Bots (linhas do elenco, visões de sala e o navegador de sessões de cada bot) em vez de se misturar às suas conversas.

Bots que você não usa podem ser guardados: clique com o botão direito na linha do bot → Hide Bot. Bots escondidos saem do elenco mas continuam funcionando — as @menções ainda resolvem e a participação em conversas em grupo fica intocada. Um alternador em forma de olho aparece no cabeçalho de Bots sempre que ao menos um bot está escondido; clique nele para revelar os bots escondidos, esmaecidos no lugar (botão direito → Unhide Bot traz um de volta), e o olho mostra um ponto quando um bot escondido tem atividade não lida. O estado de escondido fica guardado no perfil do bot, então acompanha o bot entre máquinas.

Não quer isso? Desligue em Settings → Plugins → Bots — o elenco, o painel de rotinas e o middleware do compositor se desregistram ao vivo, sem reiniciar nada.

Guia completo — criar agentes (incluindo o seletor Create on para várias máquinas), o elenco entre conexões, menções entre bots e como as conversas em grupo decidem quem responde: Bot Mode: Um Elenco de Agentes.

Teclado e navegação

• Paleta de comandos — aperte Cmd+K ou Cmd+P (Ctrl+K / Ctrl+P no Windows/Linux) para chegar a ações e navegar pelo aplicativo direto do teclado: abrir qualquer página ou seção de configuração, pular para uma sessão pelo título ou id, trocar modelo/tema/modo de cor, abrir um terminal, reiniciar o gateway, atualizar o Hermes e mais.
• Atalhos remapeáveis — Settings → Keyboard Shortcuts (ou Cmd/Ctrl+/) abre o painel de atalhos, onde você pode remapear quase toda combinação — troca de perfil, navegação de sessões, alternadores de visão e quaisquer atalhos contribuídos por plugins do desktop. Atribuições duplicadas são marcadas como conflito. Alguns padrões que vale conhecer: Cmd/Ctrl+N nova sessão, Cmd/Ctrl+. Command Center, Cmd/Ctrl+, Configurações, Cmd/Ctrl+Shift+F buscar sessões, Cmd/Ctrl+1–9 trocar de perfil, Shift+X alternar claro/escuro.
• Atalhos de zoom personalizados — dê zoom na interface em incrementos de meio passo, para controlar melhor o tamanho do texto.
• Seletor de idioma da interface — mude o idioma da interface dentro do próprio aplicativo, incluindo chinês simplificado (zh-Hans).

Sessões e perfis

• Reforma da lista de sessões — uma lista de sessões reformulada, com arquivamento e higiene geral para manter a lista sob controle conforme ela cresce.
• Buscar sessões por id — encontre uma sessão específica direto pelo id.
• Sessões simultâneas em vários perfis — rode sessões em vários perfis ao mesmo tempo, e referencie uma sessão de outro perfil com links @session entre perfis.
• Exportar / importar um perfil — compartilhe uma configuração inteira como um único arquivo. ⌘K → Export profile… (ou o botão direito em um quadrado de perfil na régua) escreve um .tar.gz com skills, memória, persona, crons, plugins e configurações; as chaves de API são removidas. Exportar pelo desktop também empacota sua aparência e sua interface — skin, modo claro/escuro, temas personalizados, a cor do perfil na régua e o layout das janelas — para que um perfil importado chegue com a cara que o remetente tinha. Importe por ⌘K → Import profile… ou pelo botão ao lado do + da régua; ele aplica o overlay e joga você no perfil novo. O mesmo arquivo funciona com /export / /import na conversa e com hermes profile export / import no shell. Veja Exportar e importar um arquivo de perfil.

Atualização

O aplicativo checa atualizações em segundo plano e oferece atualizar com um clique quando alguma está pronta.

O aplicativo desktop e o backend do Hermes com o qual ele conversa atualizam em relógios separados — o pacote do aplicativo na sua máquina, o backend onde quer que ele rode. Quando existe mais de um alvo de atualização (um gateway remoto, ou vários gateways registrados), os controles de atualização (Update now no painel About, a linha Update Hermes do ⌘K e o aviso de atualização pronta) atualizam tudo: primeiro o backend conectado, depois todos os outros gateways registrados elegíveis (entradas do Hermes Cloud são gerenciadas pela plataforma e ficam de fora) e, por último, o próprio aplicativo desktop, já que aplicar a atualização do cliente relança o aplicativo. Instalações de máquina única mantêm a experiência de um botão só.

Depois de qualquer atualização de backend, o aplicativo também recheca a própria versão e avisa com uma ação de um clique Update desktop app se a interface gráfica ainda estiver atrasada — assim atualizar um backend remoto nunca deixa você silenciosamente em uma versão velha do desktop.

O processo manual de atualização também funciona com a interface gráfica.

Desinstalação

Abra Settings → About → Danger zone e escolha quanto remover:

• Uninstall Chat GUI only — remove o aplicativo desktop e os dados dele; o agente Hermes, sua configuração e suas conversas ficam. (Igual a hermes uninstall --gui.)
• Uninstall GUI + agent, keep my data — remove o aplicativo e o agente, mas guarda configuração, conversas e segredos para uma reinstalação futura. (Igual a hermes uninstall.)
• Uninstall everything — remove o aplicativo, o agente e todos os dados de usuário. (Igual a hermes uninstall --full.)

O aplicativo fecha para terminar o serviço (a limpeza roda depois que ele sai, para poder remover o pacote do aplicativo em execução e o próprio venv). As opções que removem o agente ficam escondidas automaticamente quando não há agente local instalado (por exemplo, um cliente "lite" só de interface conectado a um backend remoto).

Dá para fazer o mesmo pelo terminal — hermes uninstall --gui só para a interface gráfica, ou hermes uninstall / hermes uninstall --full para o agente também.

observação

Rodar hermes uninstall --gui a partir de um checkout do código-fonte (uma versão de desenvolvimento do hermes desktop) também remove o node_modules do espaço de trabalho e a saída de build em apps/desktop/{dist,release}, já que esses são artefatos de build da interface gráfica. Eles voltam com hermes desktop (ou npm install mais um rebuild) — mas, se você está mexendo ativamente no aplicativo desktop, conte com reinstalar as dependências depois.

Referência da CLI: hermes desktop

Para iniciar pela CLI, basta rodar hermes desktop. Por padrão ele instala as dependências Node do espaço de trabalho, compila o aplicativo Electron desempacotado do sistema atual e então inicia esse artefato empacotado.

Opção	Descrição
--skip-build	Pula o npm install/package e inicia o aplicativo desempacotado que já existe em apps/desktop/release
--force-build	Força um rebuild completo mesmo que o carimbo de conteúdo bata
--build-only	Compila o aplicativo desktop mas não o inicia (usado pelo hermes update)
--source	Inicia via electron . contra apps/desktop/dist em vez do aplicativo empacotado
--cwd PATH	Diretório inicial de projeto para as sessões de conversa do desktop (define HERMES_DESKTOP_CWD)
--hermes-root PATH	Sobrescreve a raiz do código-fonte do Hermes que o aplicativo usa (define HERMES_DESKTOP_HERMES_ROOT)
--ignore-existing	Força o aplicativo a ignorar qualquer CLI hermes já presente no PATH durante a resolução do backend
--fake-boot	Ativa atrasos determinísticos de inicialização para validar a interface de partida

Como funciona

O aplicativo empacotado traz a casca Electron e uma superfície nativa de conversa em React. Na primeira execução ele pode instalar o runtime do Hermes Agent em HERMES_HOME (~/.hermes, ou %LOCALAPPDATA%\hermes no Windows) — o mesmo layout que uma instalação por CLI usa, e é por isso que as duas são intercambiáveis. A resolução do backend respeita primeiro HERMES_DESKTOP_HERMES_ROOT, depois uma instalação gerenciada concluída, depois um hermes sondado no PATH (a menos que --ignore-existing / HERMES_DESKTOP_IGNORE_EXISTING=1 esteja definido) e, por fim, uma sobrescrita explícita de comando em HERMES_DESKTOP_HERMES para empacotadores como o Nix. O renderizador React conversa com um backend sem interface que o aplicativo inicia para você — um processo hermes serve que serve a API JSON-RPC/WebSocket do tui_gateway — e reaproveita o runtime do agente em vez de embutir hermes --tui. O aplicativo desktop é autossuficiente: ele roda o próprio backend hermes serve e nunca abre nem exige o painel web. (Runtimes mais antigos que o comando serve caem automaticamente para um dashboard --no-open sem interface, então uma atualização do aplicativo nunca ultrapassa o backend.) A lógica de instalação, resolução de backend e autoatualização mora no processo principal do Electron.

Conectar a um backend remoto

Por padrão o aplicativo inicia e gerencia o próprio backend local. Em vez disso, você pode apontá-lo para um backend Hermes rodando em outra máquina — um VPS, um servidor doméstico ou um Mini atrás do Tailscale.

Tudo relacionado a conexão fica em uma única página de configuração: Settings → Gateways. (Versões mais antigas dividiam isso entre páginas separadas de Gateway e Connections — agora elas estão unificadas, e links profundos antigos com ?tab=connections redirecionam para a página unificada.)

Settings → Gateways → Connection mode oferece as alternativas ao gateway local:

• Remote gateway — informe a URL de um backend hermes serve que você mesmo mantém e faça login. É este o modo que o resto desta seção percorre.
• Hermes Cloud — entre uma vez no Hermes Cloud e escolha entre os agentes da sua conta; nenhuma URL para colar. O aplicativo descobre seus agentes (com um seletor de organização se a sua conta abrange várias) e, ao conectar em um, a sessão troca automaticamente. A barra de status mostra a conexão de nuvem enquanto ela está ativa.

Conexões de gateway são de nível de máquina: a página Gateways gerencia a quais backends de gateway este desktop pode se conectar, e os perfis são descobertos a partir dos gateways que você conecta. As sessões selecionam um gateway por vez, enquanto a régua de perfis ao lado seleciona um perfil descoberto naquele gateway.

O registro de várias conexões

Mais abaixo na mesma página Settings → Gateways, Registered gateways gerencia uma lista nomeada de todo gateway Hermes que o aplicativo conhece — o runtime local, qualquer número de gateways remotos (LAN, Tailscale, internet), instâncias do Hermes Cloud e hosts SSH — tudo persistido junto em um só lugar. Você chega lá pelo botão de tomada na ponta direita da régua de perfis da barra lateral (Connect another Hermes gateway…) ou por ⌘K → Gateways. O guia completo, incluindo o elenco unificado de agentes, os identificadores @nome-dispositivo, as atualizações de frota inteira e a superfície do SDK de plugins, está em Conectar o Desktop a Várias Instâncias do Hermes.

• Toda conexão precisa de um nome único (um nome de dispositivo como "Homelab" ou "Notebook do trabalho"). Quando o mesmo nome de perfil existe em vários gateways registrados, as interfaces desambiguam como @perfil-dispositivo (por exemplo, @pesquisa-homelab).
• Troque de gateway pela barra lateral de Sessions. Um seletor nomeado de gateway aparece quando há mais de um gateway registrado e dá conta de qualquer tamanho de registro sem fazer gateways parecerem perfis. A régua de perfis ao lado mostra então só os agentes daquele gateway e lembra o último perfil usado ali; conjuntos grandes de perfis se condensam de forma independente.
• Escolha o que abre depois de um reinício. Open on launch mantém o padrão retrocompatível de Primary gateway, ou pode retomar o gateway Last used depois que ele conectar com sucesso. Essa preferência é guardada fora do pacote do aplicativo e sobrevive às atualizações do Desktop.
• Adicione / edite / remova / teste conexões pelo painel. O fluxo de Add oferece os quatro tipos — Local, Hermes Cloud, Remote gateway e SSH (o botão Local fica desabilitado enquanto existe a entrada local gerenciada pelo aplicativo, e uma dica aponta as adições de nuvem para o fluxo de login/descoberta acima). A entrada local é gerenciada pelo aplicativo e não pode ser removida. Test sonda diretamente as pernas HTTP e WebSocket da própria conexão.
• Duplicatas são rejeitadas na hora de salvar: só existe uma entrada local; entradas remotas e de nuvem são deduplicadas pela URL normalizada (aparada, sem barras finais, em minúsculas — entre os dois tipos); entradas SSH, pelo user@host:port normalizado mais o perfil remoto.
• As configurações existentes são importadas automaticamente na primeira vez que você roda uma versão com o registro: sua conexão global atual e quaisquer sobrescritas legadas por perfil viram entradas nomeadas. O arquivo de configuração legado fica intocado, então versões antigas continuam funcionando.
• Entradas de nuvem vêm do fluxo de login/descoberta do Hermes Cloud acima, não de uma URL digitada à mão.
• Os tokens são guardados criptografados no chaveiro do sistema operacional (com uma escolha explícita por texto puro em Linux sem chaveiro).

O roteamento lado a lado está ativo: cada gateway registrado disca os próprios backends e sockets sob demanda (indexados por conexão + perfil), o SDK de plugins expõe o elenco unificado de agentes (host.agents() / host.ensureAgent()), e Update all instances na página Gateways dispara hermes update para todo gateway elegível de uma vez — entradas do Hermes Cloud são puladas (a plataforma as atualiza) e cada instância relata o próprio resultado.

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

"Backend remoto" quer dizer um servidor hermes serve rodando na máquina remota — é a esse processo que o aplicativo desktop se conecta. Nada nesta seção funciona sem que esse backend esteja de fato no ar e acessível. O aplicativo desktop não o inicia para você; você (ou um serviço systemd) mantém o hermes serve rodando no host remoto, e o aplicativo se conecta a ele. Se você também usa canais de mensagens (Telegram, Discord etc.), o gateway é um processo de longa duração separado, que você inicia por conta própria — veja a nota depois dos passos de configuração.

A conexão tem duas metades: no backend você a protege com um provedor de autenticação, e no aplicativo você informa a URL do backend e faz login. Vincular o backend a um endereço que não seja de loopback aciona automaticamente o portão de autenticação, e o provedor que você configurar é o que deixa o aplicativo desktop passar.

Escolha um provedor conforme o lugar onde o backend está:

• OAuth (Nous Portal) — preferido para qualquer coisa alcançável além da sua própria máquina. Os logins são verificados contra a sua conta Nous, então esta é a opção adequada para um VPS, um host público ou qualquer backend remoto. Registre o painel com hermes dashboard register (ou pela página /local-dashboards do Portal) para provisionar o cliente OAuth dele, e então faça login pelo aplicativo com Sign in with Nous Research. Um provedor OIDC auto-hospedado funciona do mesmo jeito, se você mantém o seu próprio provedor de identidade.
• Usuário/senha — só para uso local ou em rede confiável. A opção mais simples quando o backend está na mesma LAN confiável ou só é acessível por VPN (por exemplo, Tailscale). Ela protege uma única credencial compartilhada, sem provedor de identidade externo, então não use isso em um painel exposto à internet pública — recorra ao OAuth nesse caso.

O resto desta seção mostra o caminho usuário/senha porque é o mais rápido de montar em uma rede confiável; para o caminho OAuth veja Painel Web → Provedor padrão: Nous Research.

No backend (a máquina remota)

Defina um usuário e uma senha e então inicie o backend vinculado a um endereço acessível. As credenciais moram em ~/.hermes/.env (o arquivo de segredos, modo 0600):

# 1. Defina as credenciais de login do painel.
cat >> ~/.hermes/.env <<'EOF'
HERMES_DASHBOARD_BASIC_AUTH_USERNAME=admin
HERMES_DASHBOARD_BASIC_AUTH_PASSWORD=escolha-uma-senha-forte
# Recomendado: um segredo de assinatura estável para as sessões sobreviverem a reinícios.
# Sem ele, uma chave aleatória é gerada a cada boot e você será deslogado
# a cada reinício.
HERMES_DASHBOARD_BASIC_AUTH_SECRET=$(openssl rand -base64 32)
EOF
chmod 600 ~/.hermes/.env

# 2. Rode o backend vinculado a um endereço acessível. O vínculo fora do
#    loopback aciona o portão de autenticação; o provedor usuário/senha cuida do login.
hermes serve --host 0.0.0.0 --port 9119

Mantenha esse processo hermes serve rodando por todo o tempo em que você quiser que o aplicativo desktop consiga conectar — se ele parar, o aplicativo não alcança mais o backend. Rode-o sob systemd, tmux ou o gerenciador de processos que você preferir, para que sobreviva a logout e reinicializações.

Separadamente, garanta que o gateway esteja rodando no host remoto se você depende de canais de mensagens — o backend hermes serve é com quem o aplicativo desktop conversa, mas suas sessões de gateway do Telegram/Discord/Slack são um processo diferente, que você inicia e mantém por conta própria. Veja Mensagens para a configuração do gateway.

Prefere não manter uma senha em texto puro guardada? Defina HERMES_DASHBOARD_BASIC_AUTH_PASSWORD_HASH com um hash scrypt no lugar — calcule-o com python -c "from plugins.dashboard_auth.basic import hash_password; print(hash_password('PW'))". Superfície completa de configuração (chaves do config.yaml, todas as variáveis de ambiente, o limitador de taxa): Painel Web → Provedor usuário/senha.

Está rodando o backend como serviço systemd? Dê à unidade EnvironmentFile=%h/.hermes/.env para que as credenciais estejam no ambiente no boot.

aviso

O backend lê e escreve o seu .env (chaves de API, segredos) e pode rodar comandos do agente. A configuração de usuário/senha mostrada acima é para uma rede confiável — nunca exponha um backend protegido por senha diretamente à internet aberta; coloque-o atrás de uma VPN. O Tailscale é a opção limpa: vincule ao IP tailscale da máquina (--host <ip-tailscale>) e use http://<ip-tailscale>:9119 como Remote URL, para que só a sua tailnet o alcance. Para chegar a um backend pela internet pública, use o provedor OAuth (Nous Portal) no lugar.

No aplicativo

Settings → Gateways → Remote gateway:

1. Remote URL — http://<host-do-backend>:9119 (prefixos de caminho como /hermes funcionam se você o colocar atrás de um proxy reverso)
2. Sign in — o aplicativo detecta qual provedor o backend anuncia e adapta o botão. Para um backend usuário/senha ele mostra um botão Sign in que abre um formulário de credenciais (informe as credenciais do passo 1). Para um backend OAuth ele mostra Sign in with <provider> (por exemplo, Sign in with Nous Research), que executa o login pelo navegador do provedor. De qualquer forma o aplicativo termina com uma sessão autenticada contra o backend.
3. Save and reconnect — muda a casca do desktop para o backend remoto. A sessão é atualizada automaticamente; você continua logado entre reinícios quando HERMES_DASHBOARD_BASIC_AUTH_SECRET está definido.

Você também pode definir a URL do backend sem a interface, pela variável de ambiente HERMES_DESKTOP_REMOTE_URL, antes de iniciar o aplicativo (ela sobrepõe a configuração de dentro do app); o login continua sendo feito pelo painel de configurações de Gateways.

Hosts remotos por perfil

O host do gateway remoto é configurado por perfil, então cada perfil pode apontar para o próprio backend remoto (ou seguir no local). Trocar de perfil troca a qual host remoto o aplicativo se conecta.

Resolução de problemas

• O login falha com 401 / "Invalid credentials" — o usuário ou a senha não batem com HERMES_DASHBOARD_BASIC_AUTH_USERNAME / HERMES_DASHBOARD_BASIC_AUTH_PASSWORD do backend. O backend devolve o mesmo erro genérico para usuário desconhecido e senha errada (nenhum oráculo de enumeração), então confira os dois. Confirme que o portão está ligado com curl -s http://<host>:9119/api/status | jq '.auth_required, .auth_providers' — ele deve relatar true e incluir "basic".
• Nenhum botão "Sign in" — ele pede um token de sessão — o provedor usuário/senha do backend não está ativo. O /api/status não vai listar "basic" em auth_providers. Garanta que tanto o usuário quanto uma senha (ou hash de senha) estejam definidos em ~/.hermes/.env e que o processo do painel realmente os tenha carregado.
• Deslogado a cada reinício — defina HERMES_DASHBOARD_BASIC_AUTH_SECRET com um valor estável. Sem ele, a chave de assinatura de tokens é regerada a cada boot, invalidando todas as sessões.
• Conexão recusada / tempo esgotado — o backend vinculou a 127.0.0.1 (o padrão) ou um firewall/VPN está bloqueando a porta. Vincule a 0.0.0.0 ou ao IP tailscale e abra a porta para a sua rede confiável.

Para a mesma configuração pelo ângulo do painel web, veja Painel Web → Conectar o Hermes Desktop a um backend remoto; as variáveis de ambiente estão catalogadas em Variáveis de Ambiente → Painel Web e Hermes Desktop.

Estender o aplicativo desktop

O aplicativo desktop é movido a contribuições — painéis, páginas, navegação da barra lateral, itens da barra de status, comandos da paleta, atalhos e temas se registram todos por um SDK, e você pode adicionar os seus. Um plugin é um único arquivo ESM colocado em $HERMES_HOME/desktop-plugins/<id>/plugin.js; o aplicativo o carrega em segundos e recarrega a quente a cada gravação. Gerencie os plugins instalados ao vivo em Settings → Plugins.

Veja SDK de Plugins do Desktop para a referência completa. (Isso é separado do sistema de plugins do painel web.)

A seção Agent plugins na mesma página Settings → Plugins gerencia os plugins de backend (do lado do agente) que você instalou — instalações de usuário, git, projeto, pip e portáteis. Embutidos que vêm no repositório (adaptadores de plataforma, plugins de provedor e afins) não são listados ali: eles chegam habilitados por padrão e são configurados nas próprias superfícies, então a seção fica focada no que você mesmo adicionou. Com dois ou mais perfis, a seção também tem o próprio seletor Applies to, para você listar e alternar os plugins de agente de outro perfil sem trocar o aplicativo inteiro (o RPC de backend plugins.manage aceita um parâmetro opcional profile para isso).

Resolução de problemas

Turnos que falham dizem qual camada falhou

Quando um turno falha, a conversa renderiza um cartão de erro que diz qual camada falhou — provedor/modelo, endpoint personalizado, conexão de streaming, autenticação, cobrança, gateway, runtime local ou disco — em vez de um aviso genérico de erro. O cartão oferece ações de recuperação combinando com a falha:

• Retry — reexecuta o turno que falhou no lugar (fica escondido quando repetir reproduziria a falha de forma determinística, por exemplo uma rejeição por política de conteúdo).
• Switch provider — pula para Settings → Models nas falhas de provedor, endpoint, autenticação e cobrança.
• Open logs — abre HERMES_HOME/logs no seu gerenciador de arquivos. Em uma conexão remota ou de nuvem o botão vira Open Desktop logs: ele abre os logs locais do lado do Desktop (evidência de transporte), já que os logs de gateway/agente do turno que falhou ficam na máquina remota.
• Send diagnostics — envia um pacote de depuração censurado para o armazenamento interno da Nous, depois de um pedido explícito de consentimento (mesmo pipeline do hermes debug share --nous; segredos são sempre censurados, o pacote é visível apenas para a equipe da Nous e se apaga sozinho depois de 14 dias). Em caso de sucesso você recebe um link de visualização privado para colar na sua thread de suporte, mais atalhos para o GitHub Issues, o Suporte do Nous Portal e o Discord. Em uma conexão remota ou de nuvem o backend empacota os próprios logs de agente/gateway e o log local do Desktop vai anexado junto, para que o suporte veja as duas metades.
• Copy error details — copia um resumo compacto em texto puro (camada, código, provedor/modelo, mensagem de erro) que você pode colar em um relatório de bug ou no Discord.

A camada vem do mesmo classificador de erros que o laço de repetição do agente usa, então ela reflete a semântica real da falha, e não um palpite a partir do texto da mensagem. Backends antigos, anteriores ao descritor, ainda renderizam o cartão com um título genérico e as ações Retry / Open logs / Copy error details.

Os logs de inicialização caem em HERMES_HOME/logs/desktop.log (ele inclui a saída do backend e tracebacks recentes do Python) — olhe primeiro para ele se o aplicativo relatar uma falha de boot. Você também pode acompanhá-lo pela CLI:

hermes logs gui -f

Resets comuns:

# Força uma configuração limpa de primeira execução (macOS/Linux)
rm "$HOME/.hermes/hermes-agent/.hermes-bootstrap-complete"

# Reconstrói um venv Python quebrado (macOS/Linux)
rm -rf "$HOME/.hermes/hermes-agent/venv"

# Reseta um pedido de microfone travado no macOS
tccutil reset Microphone com.nousresearch.hermes

"The host key has CHANGED since you last connected" (SSH remoto)

Se o seu remoto SSH foi reinstalado ou a chave de host dele foi rotacionada, o SSH falha fechado e o Desktop trava uma sobreposição de erro em vez de tentar de novo (repetir nunca vai dar certo enquanto a chave velha não for apagada). Confirme que a mudança era esperada, então remova a entrada antiga e tente de novo pela sobreposição:

ssh-keygen -R <host>

Clique em Retry (ou reaplique a conexão em Settings → Gateway) depois de limpar a entrada — a trava reseta e o próximo boot disca do zero.

"Build desktop app" travado no download do Electron

O build baixa o runtime do Electron (~114 MB) de github.com/electron/electron/releases. Se o instalador travar no passo Build desktop app com a saída ao vivo repetindo retrying attempt=…, o GitHub está sendo bloqueado ou limitado na sua rede (firewall, proxy ou região).

O instalador se cura sozinho disso: em um build que falha ele (1) limpa um zip do Electron corrompido em cache e tenta de novo e, então, (2) se ainda falhar e você não tiver definido ELECTRON_MIRROR, tenta mais uma vez pelo npmmirror.com, o espelho de fato da comunidade Electron. O @electron/get confere o SHASUM do download, mas as somas vêm do mesmo espelho — isso pega um download corrompido ou parcial, não um espelho comprometido. Se você prefere não confiar em um host de terceiros, fixe o seu próprio ELECTRON_MIRROR (abaixo); o build nunca sobrepõe um que você tenha definido.

Para escolher o seu próprio espelho (por exemplo, um corporativo/confiável), defina ELECTRON_MIRROR antes de instalar ou reconstrua na mão — o build o respeita e não o sobrepõe:

ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ \
  bash -c 'cd "$HOME/.hermes/hermes-agent/apps/desktop" && CSC_IDENTITY_AUTO_DISCOVERY=false npm run pack'

Para limpar na mão um zip corrompido em cache:

rm -f "$HOME/Library/Caches/electron"/electron-*.zip   # macOS
rm -f "$HOME/.cache/electron"/electron-*.zip            # Linux

Compilar a partir do código-fonte

Se você quer mexer no próprio aplicativo, instale as dependências do espaço de trabalho a partir da raiz do repositório uma vez e então rode o servidor de desenvolvimento de apps/desktop:

npm install          # da raiz do repositório — liga apps/desktop, web, apps/shared
cd apps/desktop
npm run dev          # renderizador Vite + Electron, que sobe o backend Python

Aponte o aplicativo para um checkout específico, ou isole-o da sua configuração real:

HERMES_DESKTOP_HERMES_ROOT=/caminho/do/clone npm run dev
HERMES_HOME=/tmp/descartavel npm run dev
npm run dev:fake-boot   # exercita a sobreposição de partida com atrasos determinísticos

Gere os instaladores:

npm run dist:mac     # DMG + zip
npm run dist:win     # NSIS + MSI
npm run dist:linux   # AppImage + deb + rpm
npm run pack         # aplicativo desempacotado em release/ (sem instalador)

A assinatura e a notarização no macOS/Windows rodam automaticamente quando as credenciais relevantes estão presentes no ambiente (CSC_LINK / CSC_KEY_PASSWORD / APPLE_* para macOS, WIN_CSC_* para Windows).

Permissões do macOS e rebuilds locais (TCC)

Silencie todo pedido de pasta com um interruptor só. O macOS pergunta por categoria (Desktop, depois Downloads, depois Documentos, ...) conforme o Hermes toca cada pasta. Uma única concessão de Acesso Total ao Disco cobre todas elas, para sempre — e, com as identidades de assinatura estáveis do Hermes, ela sobrevive a toda atualização:

1. Ajustes do Sistema → Privacidade e Segurança → Acesso Total ao Disco (ou rode open "x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles")
2. Habilite o seu aplicativo de terminal — e o Hermes.app se você usa o Desktop.
3. Encerre completamente e relance os dois uma vez.

O hermes doctor informa se o contexto de terminal atual já tem a concessão, e o hermes setup mostra essa dica no macOS quando não tem.

O macOS lembra as concessões de permissão (Acesso Total ao Disco, Desktop/Downloads/Documentos, Acessibilidade, Automação, microfone) pela identidade de assinatura de código do aplicativo, não pelo caminho dele. Aplicativos compilados localmente e autoatualizados são assinados com uma assinatura ad-hoc estável, fixada por identificador, então as concessões persistem entre atualizações.

Nota de uma vez só: concessões feitas a builds anteriores à correção de assinatura fixada por identificador (PR #73681) carregam o antigo requisito fixado por cdhash. O macOS continua mostrando o alternador como LIGADO para essas concessões velhas mas mesmo assim pergunta de novo, porque a concessão guardada não bate mais com o binário reconstruído — e o pedido moderno não tem botão de Permitir, então parece que não há nada para reconferir. Se isso acontecer, resete a concessão velha uma vez e conceda de novo:

tccutil reset ScreenCapture com.nousresearch.hermes   # repita por serviço

e então ligue a entrada nova nos Ajustes do Sistema e encerre completamente e relance o Hermes. Dali em diante as concessões ficam estáveis.

Para a garantia mais forte — uma identidade ancorada em certificado, o mesmo mecanismo em que os usuários de yabai/skhd confiam — crie uma vez um certificado autoassinado de assinatura de código e diga ao Hermes para usá-lo. O comando de um passo faz tudo (cria o certificado no seu chaveiro de login, dá acesso ao codesign, escreve a configuração e reassina o aplicativo empacotado):

hermes desktop --setup-tcc-identity

Ou faça na mão:

1. Acesso às Chaves → Assistente de Certificados → Criar um Certificado…
2. Nome: Hermes Local Signing, Tipo de Identidade: Raiz Autoassinada, Tipo de Certificado: Code Signing.
3. No Acesso às Chaves, dê dois cliques no certificado novo → Confiar → coloque Code Signing em Sempre Confiar (um certificado autoassinado importado não é uma identidade de assinatura válida até ser confiado para assinatura de código — o security find-identity -v -p codesigning deve listá-lo depois disso).
4. hermes config set desktop.macos_signing_identity "Hermes Local Signing"

Use --identity <nome> com o comando para criar/usar um certificado com outro nome (padrão: Hermes Local Signing). O comando é idempotente — rode de novo depois de atualizações para reapontar a configuração e reassinar o aplicativo reconstruído.

A próxima atualização reassina o aplicativo reconstruído com aquele certificado; toda concessão TCC sobrevive. Nenhuma conta de Apple Developer é necessária. Builds de release notarizados são detectados e nunca reassinados.

Nota de uma vez só: mudar a identidade de assinatura (inclusive na primeira atualização depois desta correção) muda a identidade do aplicativo uma vez, então o macOS vai perguntar uma última vez. Dali em diante as concessões ficam estáveis. Se uma permissão travar, resete-a com tccutil reset All com.nousresearch.hermes e conceda de novo.

Veja também

• Guia da CLI — a interface de terminal
• TUI — a interface de terminal moderna usada pelo hermes --tui e pela aba de conversa do painel
• Painel Web — painel de administração no navegador com uma aba de conversa embutida
• Configuração — a configuração que o aplicativo desktop lê e escreve
• Windows (Nativo) — caminho de instalação nativo no Windows

---