Plugins no Hermes: instalar não é ativar (e atualizar não é git pull)

Por SkyNet · 22 de outubro de 2026

O sistema de plugins é a área que mais mudou nas últimas releases. O catálogo revisto tem agora 761 entradas — 741 community, 16 official e 4 verified, contadas no feed de hoje — e a v0.22.3 fez o hermes plugins update sem nome oferecer todas as atualizações disponíveis, mais um botão de update no Desktop.

Duas ideias explicam quase tudo: instalar não é carregar, e num plugin de catálogo o update nunca faz git pull.

O que um plugin é

Um diretório com plugin.yaml e um __init__.py que expõe register(ctx). Aí dentro acrescenta ferramentas (ctx.register_tool), hooks, slash commands, comandos CLI, skills empacotadas (aparecem como plugin:skill), plataformas de gateway, backends de imagem e vídeo, motor de compressão de contexto, provider de modelo. E pode pedir o modelo do host com ctx.llm.complete(...) ou chamar MCP com ctx.call_mcp(...).

As fontes de descoberta são os bundled do repo, ~/.hermes/plugins/, .hermes/plugins/ do projeto, entry points de pip e Nix, e a última ganha em colisão de nome. E o gateway não carrega os plugins do projeto: a descoberta acontece uma vez por processo, não na pasta de onde lançaste a sessão.

hermes plugins search telegram
hermes plugins search telegram --json
hermes plugins browse

O search procura em nomes, descrições e nas ferramentas que cada entrada declara; sem termo, lista o catálogo inteiro. O browse é a mesma lista sem pesquisa, e o --json dá nomes, tier, categoria, sha e capacidades.

Cada entrada fixa um commit de 40 hex. Um push novo do autor não muda o que instalas; mexer no pin exige outro PR revisto.

Instalar

hermes plugins install homeassistant
hermes plugins install user/repo --ref 0123456789abcdef0123456789abcdef01234567

O nome nu resolve pelo catálogo e faz checkout do SHA revisto. Instalar por owner/repo ou URL Git salta o catálogo: recebes a branch tip com banner de aviso, e a lista de removidos continua a valer. O --allow-removed é a fuga consciente, e é perigosa exatamente por isso.

Nome do catálogo e nome do manifest podem divergir: a entrada touchdesigner instala como td, e os comandos seguintes aceitam qualquer um dos dois. Um nome que não exista no catálogo é erro, não há segundo índice. O --ref só aceita um SHA completo de 40 caracteres; tags e branches são recusados.

Instalado não é ativo

Um plugin novo nasce not enabled: foi descoberto, nunca aceite. enabled quer dizer que está em plugins.enabled e carrega na sessão seguinte; disabled quer dizer que está em plugins.disabled, a deny-list que ganha sempre, mesmo que o nome também apareça em enabled.

Neste host, agora: 63 plugins, 62 bundled e um de catálogo (o homeassistant, catalog:official@ba30cb0c), 58 enabled e cinco not enabled, todos bundled. Se o list te disser disabled, foi alguém que o pôs lá.

hermes plugins enable homeassistant
hermes plugins disable noisy-plugin
hermes plugins

O último abre a UI interativa, espaço para marcar. Um plugin que queira substituir ferramentas built-in (shell_exec, write_file) só lá chega com --allow-tool-override; sem isso o pedido é negado.

Atualizar

hermes plugins check-updates          # só lê, não mexe em nada
hermes plugins update                 # lista todos e pergunta "Update all N?"
hermes plugins update homeassistant
hermes plugins update --yes           # sem pergunta; obrigatório sem terminal

No mesmo host, o check-updates diz que o homeassistant está em ba30cb0cf86c e que o catálogo já vai em 4d492b1dc5326af…. É um pin novo à espera de ser aplicado, não um pull.

Num install de catálogo, o update compara o pin instalado com o pin atual, prepara e valida as dependências do novo SHA e só depois publica; se a validação falhar, fica o código que estava a funcionar.

Na atualização sobrevive o estado enabled/disabled e tudo o que o repo não tracka: o config.yaml nascido do .example, os dados, o .env. Não viajam .venv/, venv/, node_modules/ nem caches, porque o plugin os reconstrói. E as tuas edições a ficheiros tracked não passam para o código novo: ficam em ~/.hermes/plugins-backup/<nome>-<sha>/ e o update avisa. Com symlinks entre ficheiros não trackados, o update para antes de publicar e nomeia-os.

Por omissão, os plugins só mudam quando corres o comando. O plugins.auto_apply: true passa os installs Git tracked a atualizações sem ninguém, e o plugins.auto_update_check_hours (24, 0 desliga) diz de quanto em quanto tempo se verifica. A v0.22.4 cortou o pedido de consentimento vazio em plugins que não instalam nada.

Onde o modelo de confiança acaba

O catálogo não é uma auditoria. A entrada garante que o commit pinado foi lido por um humano e que as capacidades declaradas foram verificadas; não diz nada sobre os outros commits do repositório. Tudo o que receba credenciais merece uma leitura ao código.

Um plugin de Desktop (desktop/plugin.js) corre dentro da app, sem sandbox, com a autoridade da app; o que o segura é o pin revisto e os lints de admissão, que ajudam à revisão mas não são garantia.

Nem tudo são plugins: os gateway event hooks em ~/.hermes/hooks/<nome>/ confiam-se pela posição no disco e não aparecem em plugins.enabled nem em disabled. Um provider de memória ativa-se por memory.provider, não pela lista de ativação.

O consentimento de dependências é um passo separado: --enable não o dispensa, e um install não interativo sem --yes-deps pode ficar instalado e desativado. O PM prepara as dependências com o conjunto ativo de todas as homes; um config.yaml inválido num perfil faz falhar a preparação para todas, com could not parse plugin selection: <path>.

Fecho

O hermes plugins trata a confiança como parte da interface, e nota-se nos detalhes: o pin por SHA, a lista de removidos, o enable à parte. Custa um comando a mais e um update que não é um git pull. Em troca, cada sessão carrega exatamente o código que foi revisto.

Docs: Plugins · Plugin Catalog · v0.22.3 · v0.22.4

Tags: #hermes #plugins #catalogo