Como atualizar o Hermes Agent sem quebrar o que já estava funcionando

Atualizar um agente que já está redondo dá um frio na barriga, né?

Você ajustou a config, plugou as integrações, deixou as skills do jeito que funciona no seu fluxo… e aí sai versão nova

O medo é sempre o mesmo: rodar um comando e acordar com metade das coisas fora do lugar

A parte boa é que o Hermes Agent, desenvolvido e mantido pela Nous Research, já traz rede de proteção dentro do próprio comando de atualização: ele salva um snapshot do seu estado antes de mexer, reverte sozinho se o código vier quebrado e ainda tenta reiniciar os gateways pra pegarem o código novo

A versão estável mais recente publicada no repositório oficial é a v0.20.1 (tag v2026.8.13), de 13 de agosto de 2026

Aqui eu te mostro a ordem de checagem antes, durante e depois, e o caminho de volta se algo sair torto…

Antes de atualizar: o que checar para não quebrar nada

Antes de qualquer coisa, vale entender o que o hermes update faz de verdade: ele puxa o código mais recente, reinstala as dependências no venv gerenciado e re-executa os hooks pós-instalação (servidores MCP, sincronização de skills, instalação do autocompletar)

É um comando seguro de rodar em uma instalação viva, mas isso não te dispensa de olhar o estado inicial

Tem alguma coisa nova pra puxar?

Existe um modo de verificação que não tem efeito colateral nenhum: ele só compara commits contra origin/main

hermes update --check

Esse modo não modifica arquivos e não reinicia o gateway, o que faz dele o cara certo pra colocar em script ou cron e ser avisado quando sair versão nova

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 114 aulas
• 4 projetos
• 9h 18min

Conhecer formação

Qual nível de backup faz sentido pro seu caso?

Por padrão o update já salva um snapshot leve de estado antes de atualizar

Esse snapshot cobre dados de pareamento, cron jobs, config.yaml, .env, auth.json e outros arquivos de estado modificados em runtime

Tome cuidado com um detalhe: arquivos individuais acima de 1 GiB são pulados

O comportamento é controlado por uma opção de configuração com três modos:

Na config, a chave é updates.pre_update_backup

E quando o objetivo é sair da máquina?

Aí muda o jogo

A documentação recomenda os comandos próprios de backup (e não o snapshot de update) quando você quer levar a instalação pra outro hardware

hermes backup
hermes backup --quick
hermes backup -o /caminho/do/seu/backup.zip
hermes import

O hermes backup gera um zip em ~/hermes-backup-*.zip, o --quick salva só o estado e o hermes import traz tudo de volta do outro lado

Se é isso que tu quer fazer, dá uma olhada em migrar o Hermes pra outra máquina, que é um assunto por si só

Está no Windows? Feche as coisas antes

Esse aqui pega muita gente de surpresa

No Windows o update se recusa a rodar se detectar outro processo hermes.exe segurando o executável do venv

Isso inclui o backend do Hermes Desktop, um REPL hermes aberto em outro terminal ou um gateway rodando

Então, antes de atualizar: feche o Hermes Desktop, saia dos REPLs e derrube o gateway

hermes gateway stop

Guarda esse detalhe pro final, porque ele muda o passo 6: o Hermes só tenta reiniciar sozinho os perfis de gateway que estavam EM EXECUÇÃO quando o update rodou

Como aqui você parou tudo na mão, não vai ter gateway rodando pra ser reiniciado, e quem sobe de volta depois é você mesmo

Como atualizar o Hermes Agent passo a passo

Com o terreno limpo, a sequência é curta

1. Cheque se existe atualização com o modo que não mexe em nada:

   hermes update --check

O erro comum deste passo: usar esse modo achando que ele já atualiza. Ele só compara commits contra origin/main, não toca em arquivo e não reinicia gateway

2. Rode o update de verdade:

   hermes update
   hermes update --branch <nome>

Por padrão ele acompanha a branch origin/main, e o --branch serve quando tu quer apontar pra outra

O erro comum deste passo: achar que precisa rodar um update por perfil. Não precisa. O update roda uma única vez por máquina: puxa o código, reinstala as dependências uma vez e depois sincroniza as skills atualizadas pra todos os perfis

3. Saiba o que acontece com as suas mudanças locais não commitadas na árvore de código, que é o checkout git em ~/.hermes/hermes-agent

No terminal interativo o Hermes faz stash, puxa e te pergunta se restaura

Em update não interativo quem manda é a config:

   updates:
     non_interactive_local_changes: stash

O modo stash é o padrão e restaura por cima depois do pull, e o discard dropa o stash após o pull

No app desktop, essa mesma decisão fica em Settings > Advanced > In-App Update Local Changes

O erro comum deste passo: rodar update não interativo com discard sem lembrar que tinha ajuste local não commitado

4. Deixe terminar

O update ignora SIGHUP, e os processos filhos de pip e git herdam essa proteção

Ou seja: fechar a sessão SSH ou a janela do terminal não mata a atualização no meio, o que evita aquele pesadelo de ambiente Python meio instalado

Mesmo assim, o hábito saudável é esperar o comando voltar antes de sair mexendo

5. Valide a configuração depois

O update detecta automaticamente opções de configuração novas e oferece adicioná-las

Se você pulou o prompt (acontece), dá pra resolver depois:

   hermes config check
   hermes config migrate

Antes de seguir, uma parada pra definir o config check, porque ele aparece duas vezes neste post e as pessoas confundem: o comando compara o seu config.yaml com o que a versão instalada espera e aponta a divergência nos DOIS sentidos, o que está faltando e o que a versão não reconhece

Aqui, logo depois de atualizar, o caso é o primeiro: falta opção nova. Aí quem adiciona de forma interativa, varrendo as skills habilitadas, é o config migrate

O erro comum deste passo: passar batido no prompt e depois culpar a versão nova por um comportamento que é só opção não gravada

6. Confirme que os gateways pegaram o código novo

Após um update bem-sucedido o Hermes tenta reiniciar automaticamente todos os perfis de gateway em execução

Repara na palavra "em execução": se você parou o gateway antes de atualizar (o roteiro do Windows, lembra?), não tem o que reiniciar, e o restart automático simplesmente não entra em cena. Nesse caso é você que sobe o gateway de novo

O erro comum deste passo: confiar cegamente no automático. Um gateway rodando mantém o código antigo em memória até ser reiniciado, então se o comportamento não mudou, é aí que você olha primeiro

Mais um que vale marcar: se você fixou a instalação em uma tag, esse pin NÃO sobrevive ao próximo update

Com o HEAD em estado detached, o comando emite um aviso e roda git checkout main

Deu problema depois do update? Ordem de checagem e como voltar

A ordem aqui importa muito, porque a maioria dos "quebrou tudo" é na verdade a coisa mais boba da lista 🙂

O agente continua se comportando como na versão antiga

Causa: gateway não reiniciado, segurando o código velho em memória

Duas situações levam pro mesmo lugar: ou o restart automático não deu conta do perfil, ou o gateway nem estava rodando na hora do update (quem seguiu o passo do Windows caiu aqui) e por isso não havia nada pra reiniciar

Solução: suba ou reinicie o gateway você mesmo e teste de novo

Como prevenir: trate a confirmação do gateway como parte do update, não como bônus, principalmente se foi você que derrubou ele antes

Erro de configuração logo depois de atualizar

Causa: opções novas de config que a versão espera e ainda não foram gravadas no seu config.yaml

Solução:

hermes config check
hermes config migrate

Nesse cenário o config check está listando o que FALTA, e o config migrate grava. Mais abaixo, no rollback, o mesmo comando vai apontar o contrário: opção a MAIS que a versão antiga não reconhece

Como prevenir: não pular o prompt de opções novas que o próprio update oferece

Problemas de schema ou de permissão de arquivo

Causa: migração de schema pendente e permissões fora do lugar, aquele tipo de coisa que não aparece no log bonitinho

Solução: existe um comando de diagnóstico com modo de reparo automático pra problemas comuns

hermes doctor
hermes doctor --fix

Como prevenir: rodar o hermes doctor logo após atualizar, antes de voltar a trabalhar

A instalação parece corrompida no meio do pull

Essa é a parte que me deixa mais tranquilo pra rodar update sem drama

Causa: marcador de conflito órfão, arquivo truncado, esse tipo de sujeira no código puxado

Solução: o Hermes já resolve sozinho. Depois do git pull ele compila os arquivos críticos que importa na inicialização, e se algum falhar no parse ele reverte a instalação automaticamente com git reset --hard pro commit anterior ao pull

Como prevenir: não é bem prevenção, é saber que existe. Se o update reclamou e voltou, você está no estado de antes, não num meio termo, e pode tentar de novo com calma

Preciso voltar pra uma release anterior

Causa: a versão nova mudou algo que o seu fluxo dependia

Solução: checkout manual da tag desejada dentro do diretório do código, aquele mesmo ~/.hermes/hermes-agent do passo 3

cd ~/.hermes/hermes-agent && git checkout <tag>

Depois disso, atenção: voltar de versão pode gerar incompatibilidade de configuração, porque opções novas já podem ter sido gravadas no seu config.yaml

A orientação da documentação é rodar a checagem de config depois do rollback e remover as opções não reconhecidas

hermes config check

É o mesmo comando do passo 5, lido no outro sentido: agora o que interessa é o que ele apontar como não reconhecido pela versão antiga, e essas linhas você tira do config.yaml na mão, porque aqui não é caso de config migrate

Como prevenir: lembrar que esse pin em tag é temporário. No próximo hermes update ele avisa e roda git checkout main

E os arquivos do projeto que o agente mexeu?

Aqui é outro sistema, não confunda com update

O Hermes tem checkpoints de projeto: um repositório git sombra compartilhado, em ~/.hermes/checkpoints/store/, que guarda o estado dos arquivos

Ao restaurar, ele tira um snapshot pré-rollback (então dá pra desfazer o desfazer) e também desfaz o último turno da conversa, pra que o contexto do agente bata com os arquivos restaurados

Ou seja: update é uma coisa, checkpoint de projeto é outra, e cada um resolve um tipo de estrago diferente

Atualizando em Docker, em vários perfis e pelo app desktop

Nem todo mundo roda o Hermes do mesmo jeito, e o procedimento muda bastante conforme o cenário

Rodando em Docker

Se liga nisso: dentro de um container o hermes update simplesmente não se aplica

O motivo é direto: o Hermes ali roda a partir de uma imagem publicada, não de um checkout git, então não existe working tree pra fazer pull

O caminho é puxar a imagem nova e recriar o container

docker pull nousresearch/hermes-agent:latest
docker compose up -d --force-recreate hermes-agent

Se você não usa compose, é rodar o docker run de novo

Um detalhe que engana: se o seu container está fixado em uma tag específica, a latest não move a instalação. Ou você puxa a tag desejada, ou troca pra latest/main

A imagem é stateless e o diretório de dados é preservado na atualização, e o container roda migrações não interativas do schema de configuração contra a config montada antes de subir o gateway

Rodando vários perfis

Um hermes update cobre todos os perfis da máquina, sem repetição

O que vale ter na cabeça é o isolamento: cada perfil do Hermes tem seu próprio armazenamento de memória, banco de sessões e diretório de skills, completamente separados entre si

Então o código é compartilhado, mas o estado não é

Usando o app desktop

O app verifica atualizações em segundo plano e oferece atualização em um clique quando tem versão nova

É o caminho mais confortável, mas as mesmas regras de mudanças locais valem, e a opção fica em Settings > Advanced > In-App Update Local Changes

O que aprendi mexendo no meu Hermes Agent no dia a dia

O que me fez levar a sério essa ordem de checagem não foi um update dando errado, foi o oposto: foi perceber quanta coisa mora numa instalação já ajustada

No vídeo abaixo eu mostro a instalação de uma skill open source que dá visão de internet pro Hermes, e o processo inteiro passou por coisas que eu não quero perder num update qualquer

Eu pedi pro próprio Hermes instalar a skill, passando o repositório e um prompt curto, em vez de fazer na mão

E deixei explícito no prompt em qual pasta de skills a instalação deveria acontecer, porque é esse tipo de detalhe que garante sucesso logo no começo

A instalação demora, viu? O agente ainda baixa e instala pacotes antes de a skill ficar utilizável

Depois de instalar, rodei o comando de diagnóstico da própria skill pra conferir se estava tudo certo antes de sair usando

O diagnóstico mostrou um serviço funcionando e outros dois ainda pedindo login pra resolver a questão dos cookies

Eu tratei isso como não bloqueante: dá pra autenticar depois, sem impedir o uso do que já estava funcionando. E a autenticação eu fiz num passo separado da instalação, pedindo o login por fluxo de autorização

Pra gravar, aliás, eu reaproveitei uma instalação que já tinha feito antes, em vez de refazer tudo do zero

E é exatamente aí que a ficha cai: skill instalada, serviços autenticados, memória acumulada, pasta certa… esse é o estado que você não quer descobrir que sumiu

Outra coisa que reparei: a skill troca de método quando uma das ferramentas configuradas é bloqueada, então uma fonte indisponível não derruba a busca inteira. Comportamento resiliente assim é fácil de valorizar depois que você viu funcionar

Depois de validar o setup, testei casos de uso reais: resumo de vídeo do YouTube em tópicos, busca por repositórios populares no GitHub e leitura de README mais issues abertas de um projeto

Essa das issues abertas eu recomendo demais: é o jeito mais rápido de entender os problemas reais de uma ferramenta antes de adotar ela

E dá pra jogar o que o agente descobre na memória do Hermes, pra ele ir acumulando conhecimento com o tempo

Ah, e eu rodo o meu Hermes em VPS, por ser ambiente isolado. Recomendo

Conclusão: atualize com rede de proteção

A ordem segura cabe em uma linha: checar, definir o backup, atualizar, validar a config, confirmar o gateway

Se algo sair torto, a escada de volta também é curta: hermes doctor, hermes config check, e no limite o checkout manual da tag anterior seguido da limpeza das opções não reconhecidas do config.yaml

O próximo passo é bem simples: roda o hermes update --check hoje só pra ver onde tu está

E aproveita pra decidir qual modo de updates.pre_update_backup faz sentido pra sua instalação, porque o padrão quick é ótimo pro dia a dia, mas se o seu Hermes carrega muita coisa, o full dorme melhor à noite 😀

até o próximo post!