Como migrar o Hermes Agent para outra máquina sem perder configuração, skills e memória?

Fala aí, beleza? Trocar de computador não deveria custar meses de memória, skills afiadas e um monte de chave de API pra reconfigurar na mão

A boa notícia é que o Hermes Agent, agente open source (licença MIT) da Nous Research que roda na sua própria máquina, guarda praticamente tudo em um lugar só: o home dele, que fica em ~/.hermes/ por padrão ou no caminho que você apontar na variável HERMES_HOME

Isso muda o jogo da migração

Se todo o estado (config, chaves, memórias, skills, sessões e perfis) vive num diretório único, migrar deixa de ser adivinhação e passa a ser uma sequência de passos previsível… desde que você faça na ordem certa 😀

O que você precisa ter em mãos antes de migrar

Antes de sair rodando comando, junte o kit básico:

• Acesso às duas máquinas, a antiga e a nova (parece obvio, mas é o item que mais quebra migração feita às pressas)
• Hermes instalado na máquina nova: no Linux, macOS e WSL2 dá pra usar o script único, e no Windows existe também o guia de instalação nativa
• O gateway parado na máquina nova no momento da importação, porque a documentação orienta parar o gateway antes do hermes import pra evitar conflito com processos em execução
• Consciência de que as chaves viajam junto: o backup nativo inclui as chaves de API, então o zip é arquivo sensível, não um anexo qualquer pra jogar no grupo do WhatsApp

Formação Recomendada

Formação Vibe Coding

Do Prompt ao Produto: Crie Software Real com IA

• 474 aulas
• 20 projetos
• 39h 27min

Conhecer formação

Esse último ponto merece atenção de verdade

Um agente que tem acesso às suas contas concentra poder, e vale a mesma régua que já discuti sobre segurança do Hermes Agent na hora de decidir onde esse arquivo vai ficar guardado

O script único de instalação é este:

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

Ele instala as dependências, clona o repo, cria o venv e configura o comando global hermes

Como migrar o Hermes Agent passo a passo

Bora ver na prática? A ordem abaixo é a que evita retrabalho

1. Inventarie o que vive no home do Hermes

Antes de empacotar, olhe o que você tem: o config.yaml (configuração não sensível), o .env (chaves de API, tokens e segredos, nunca expostos ao modelo), a pasta ~/.hermes/skills/ (fonte da verdade das suas skills), a pasta ~/.hermes/memories/, o banco ~/.hermes/state.db e os perfis

O erro comum deste passo: achar que skill mora no repo do projeto. A pasta ~/.hermes/skills/ é a fonte da verdade, e é ela que precisa viajar

2. Rode o backup nativo na máquina antiga

    hermes backup

Ele gera um ~/hermes-backup-<timestamp>.zip com config, chaves de API, memórias, skills, sessões e perfis. O snapshot é consistente mesmo com o agente em execução, e ele exclui arquivos locais de runtime como gateway.pid e cron.pid

O erro comum deste passo: esperar que o zip traga o codebase. Ele NÃO inclui o código-fonte do hermes-agent, só configuração, skills, sessões e dados

3. Transfira o zip com segurança

Copie por um canal que você controla. Lembre que ali dentro tem .env com chave de API, e chave vazada é chave queimada

O erro comum deste passo: deixar o zip parado na pasta de Downloads da máquina nova depois da migração, sem apagar nem mover pra um lugar protegido

4. Instale o Hermes na máquina nova

Aqui você usa o script único (Linux, macOS ou WSL2) ou o guia de instalação nativa do Windows. O import restaura seus dados, não a instalação, então o Hermes precisa existir do outro lado antes

O erro comum deste passo: tentar importar num ambiente onde o comando hermes ainda não está configurado globalmente

5. Pare o gateway e importe o backup

    hermes import ~/hermes-backup-20260423.zip

Ele pede confirmação, e você pode usar --force pra pular o prompt. Tome cuidado: os arquivos do arquivo compactado SOBRESCREVEM os existentes, então importar em cima de um home já povoado é decisão consciente, não acidente

O erro comum deste passo: importar com o gateway no ar, e no Windows nativo confundir o caminho do home (falo dele mais embaixo)

Como validar que o agente voltou a fazer o mesmo do outro lado

Migrou, importou, e agora? Migração sem validação é fé, não processo 😛

Rode este checklist na máquina nova:

1. hermes setup: a documentação orienta rodar o setup na máquina nova pra verificar se as API keys e a config de provedor estão funcionando

Se você usa o Nous Portal, existe a variação por assistente interativo com OAuth:

    hermes setup --portal

Um OAuth cobre um modelo mais as quatro ferramentas do Tool Gateway (busca web, geração de imagem, TTS e navegador)

2. hermes doctor: é o comando de diagnóstico, ele aponta o que está faltando e como corrigir. A verificação pós-instalação é justamente ele rodar limpo

3. hermes config show: confere o config.yaml que veio no backup, pra ver se a configuração é a mesma que você tinha

4. Cheque sessões e histórico: o ~/.hermes/state.db é o banco SQLite único compartilhado por CLI e gateway, com metadados de sessão, histórico completo de mensagens, config de modelo e índice de busca full-text FTS5. Se a sessão antiga aparece na busca, o histórico chegou

E a faxina final: arquivos *.jsonl legados em ~/.hermes/sessions/ não são mais lidos nem escritos pelo Hermes, e podem ser apagados depois que você confirmar a sessão no state.db

Erros que estragam a migração (e como prevenir)

Sintoma: o import se comporta de forma estranha ou conflita com algo em execução

Causa: o gateway estava no ar durante o hermes import

Solução: pare o gateway ANTES de importar, como a documentação orienta

Sintoma: no Windows nativo você "limpa a instalação" e perde tudo

Causa: o instalador define HERMES_HOME=%LOCALAPPDATA%\hermes, e ali instalação e dados dividem a mesma raiz: as subpastas hermes-agent\, git\, node\ e bin\ são a instalação, e os dados ficam direto na raiz

Solução: nunca use Remove-Item -Recurse em %LOCALAPPDATA%\hermes (os rm -rf da vida também valem no PowerShell). Apague só a subpasta hermes-agent\

Sintoma: você jura que o agente lembrava de algo e ele não lembra na sessão em curso

Causa: as memórias de ~/.hermes/memories/ são injetadas no system prompt e o snapshot é congelado no início da sessão

Solução: abra uma sessão nova depois do import, em vez de julgar a migração por uma conversa que começou antes

Sintoma: o agente sobe, mas nada que depende de provedor funciona

Causa: alguém copiou pasta a pasta e deixou o .env pra trás, porque ele é arquivo separado justamente pra não expor segredo ao modelo

Solução: use o backup nativo em vez de arrastar pastas no explorador de arquivos

Variações: um perfil só, compartilhar o agente, Windows e quem vem do OpenClaw

Nem toda migração é "levo tudo". Se liga nos quatro cenários:

Levar só um perfil:

Cada perfil tem diretório próprio com config.yaml, .env, SOUL.md, memórias, sessões, skills, cron jobs e banco de estado, e o perfil ativo é rastreado em ~/.hermes/active_profile

Pra backup e restore local de um perfil isolado existem comandos dedicados:

hermes profile export
hermes profile import

O export gera um tar.gz do perfil, e o import restaura a partir dele

Compartilhar o agente com outra pessoa:

Aqui o caminho não é backup, é distribuição por git. Ela empacota personalidade, skills, cron jobs, conexões MCP e config como repositório git, e deixa auth.json e .env de fora de propósito: o instalador preenche as próprias chaves, do .env.EXAMPLE pro .env

Ou seja, distribuição é pra dividir o agente, backup é pra mudar de máquina. Não troque um pelo outro

Windows nativo:

O HERMES_HOME fica em %LOCALAPPDATA%\hermes, e as chaves de API ficam em %LOCALAPPDATA%\hermes\.env, mesmo tipo de arquivo do Linux

Só que ali instalação e dados dividem a mesma raiz, e é justamente isso que confunde na hora de migrar

Se essa raiz compartilhada te incomoda (e incomoda mesmo), a saída é sobrescrever o HERMES_HOME apontando por exemplo pra %USERPROFILE%\.hermes

Com isso o layout fica alinhado com o do Linux: o caminho que você lê nos comandos é o mesmo que o backup empacota e o import restaura, e some aquele risco de apagar dado achando que está limpando instalação

Vale lembrar que o script único de instalação cobre Linux, macOS e WSL2, e o WSL2 é o caminho da documentação pro install de linha de comando padrão no Windows

Quem vem do OpenClaw:

Nesse caso não é migração de máquina, é migração de ferramenta, e existe comando dedicado:

hermes claw migrate

Ele lê de ~/.openclaw e escreve em ~/.hermes, cobrindo várias categorias: persona, memória, skills, provedores de modelo, plataformas de mensagem, sessões, servidores MCP, TTS e outras. Completão 🙂

O que aprendi mexendo no Hermes em máquina local e em VPS

Aqui vai o meu caso concreto, e ele é diferente do tutorial acima de propósito: eu NÃO migrei a instalação

O meu Hermes já estava configurado e rodando numa VPS, e o que eu fiz foi conectar o app de desktop do meu PC nessa instância, com o app funcionando como um gerenciador remoto

No setup inicial do app eu encontrei duas opções, local ou conexão remota, e escolhi a remota

E é a que eu recomendo: a máquina fica acessível a mais serviços e ligada o tempo todo, coisa que o notebook que você fecha às 19h não faz

Pra conectar eu precisei de dois dados, a URL do servidor (o IP da VPS com a porta configurada) e a chave de API. Preferi a chave de API por segurança

Antes de conseguir conectar eu entrei na VPS e editei o arquivo de configuração do Hermes pra habilitar o servidor de API, definir host, porta e uma chave forte

Gerei a chave por linha de comando na própria VPS, colei no lugar do placeholder, salvei, subi e reiniciei o serviço do gateway, checei o status e ainda testei a porta com uma requisição pra confirmar que a API respondia

Na primeira conversa pelo app o agente simplesmente não respondeu, por causa do modelo que estava configurado. Troquei o modelo pelo próprio Hermes, autentiquei a conta do provedor por URL e código, e aí o chat passou a funcionar

Depois de conectado eu conseguia ver o painel dos agentes, os agendamentos e as configurações direto do app, sem abrir a VPS

Um aviso honesto: nem todos os recursos do Hermes estão expostos via API, então parte das coisas ainda não dá pra fazer pelo app

A leitura que fica pra quem está decidindo pra onde migrar: se o destino é uma VPS, você ganha um agente ligado full time, e o seu PC vira só a interface. Se o destino é um desktop novo, o backup mais import resolve

E se o seu dia se divide entre agente autônomo e terminal, vale ver Hermes Agent e Claude Code no fluxo antes de escolher onde cada coisa vai morar

Esse conteúdo aqui é nível dois, viu? Se você ainda não tem o Hermes instalado e configurado, comece pelo vídeo anterior meu sobre isso

No vídeo abaixo eu mostro esse caminho inteiro: o setup do app, a escolha entre local e remoto, a liberação da API na VPS e o chat voltando a funcionar depois da troca de modelo

Conclusão

Migrar o Hermes Agent é previsível porque o estado dele é concentrado: um home só, com config.yaml, .env, skills/, memories/, state.db e perfis

A ordem segura, na sequência: hermes backup na máquina antiga, instalar o Hermes na nova, parar o gateway, hermes import, hermes setup pra conferir chaves e provedor, e hermes doctor rodando limpo

E um hábito que eu deixo como próximo passo: rode um hermes backup hoje, mesmo sem plano de trocar de máquina

Disco morre, notebook cai, sistema corrompe… e um zip guardado num lugar seguro (seguro mesmo, porque ele carrega as suas chaves dentro) é a diferença entre reinstalar em dez minutos e recomeçar do zero

Até o próximo post! 😀