Seu agente inteiro num arquivo só: backup no desktop e migração para a nuvem com botão de desfazer


Quando você troca de notebook, a última coisa que quer migrar é o próprio agente: dezenas de profiles, um monte de skills, arquivos de memória, um banco de cron e aquele .env que ninguém ousa apagar. A abordagem habitual é tar seguido da esperança de que todo caminho ainda resolva do outro lado. Migrar para a nuvem é pior, porque agora você também precisa descobrir qual metade pertence a “o agente” e qual metade pertence a “a máquina em que ele roda”.

Isso agora é uma página em Settings: Settings ▸ Backup & Transfer. Dois cartões — backup e transferência — e os dois embrulham comandos que você mesmo pode rodar.

Backup: um zip só, incluindo as partes que você sempre esquece

O primeiro cartão é Back up this agent. Ele roda hermes backup e entrega o zip produzido pelo backend que escreveu. O que está dentro é explícito: todos os profiles, settings, memória, skills, agendamentos, chats, .env e auth.json.

“Todos” é a palavra importante. Scripts de backup escritos à mão erram três coisas com uma regularidade impressionante:

  • Memória e skills, porque moram nos próprios diretórios de dados, não na pasta de configuração;
  • Jobs de cron, porque as definições ficam num banco de dados, não num arquivo JSON que você lembrou de copiar;
  • Credenciais, porque auth.json e .env estão tão acostumados a ir para o gitignore que a primeira chamada de modelo na máquina nova é onde você descobre que eles nunca vieram.

A CLI faz a mesma operação, com algumas flags que vale conhecer:

hermes backup                                 # backup completo em ~/hermes-backup-<timestamp>.zip
hermes backup -o ~/backups/agent.zip
hermes backup --quick --label pre-upgrade     # só o estado crítico
hermes backup -k 5                            # manter apenas os 5 backups completos mais novos

--quick é um snapshot de estado crítico: config, state.db, .env, auth, cron. Antes de uma atualização, ou quando tudo o que você quer é preservar “a identidade desta máquina”, é bem mais rápido que um backup completo. -k cuida da retenção: os 3 backups completos mais novos são mantidos por padrão, e 0 mantém tudo.

Uma transferência não é um formato novo

O segundo cartão é Transfer to Hermes Cloud. O detalhe de implementação importa, porque ele decide se essa funcionalidade te prende: não existe um formato de migração separado. Uma transferência é um hermes backup comum, restaurado no agente na nuvem com hermes import --keep-host.

Então a mesma coisa está disponível num terminal, ou no CI:

# 1. na máquina de origem
hermes backup -o ~/agent-move.zip

# 2. na máquina de destino
hermes import ~/agent-move.zip --keep-host

--keep-host é a metade interessante. Um import puro deita o backup como está, o que sobrescreveria a identidade do destino junto com todo o resto. --keep-host diz: substitua este agente pelo backup, mas mantenha o que o host configurou para ele:

  • o login no Nous Portal;
  • a seleção de modelo e provider;
  • as configurações de tool-gateway, dashboard e scheduler;
  • as variáveis de ambiente NOUS_* / HERMES_* injetadas pelo host.

Dito de outro jeito: o backup carrega quem o agente é, o que ele lembra e o que ele sabe fazer; o host mantém onde ele roda e com qual identidade ele fala. É isso que torna seguro sobrescrever um agente na nuvem cuja configuração a plataforma gerencia.

O ponto de desfazer: primeiro backup, depois sobrescrever

O desfecho perigoso de uma migração não é a falha. É a meia falha: alguns arquivos substituídos, um profile criado mas incompleto, um serviço que sobe e não funciona. Você não consegue voltar e não consegue dizer em que estado está.

Três decisões de projeto existem nesse fluxo para evitar isso.

Primeiro, ele leva o próprio paraquedas. Antes de qualquer coisa ser substituída, o agente de destino é totalmente copiado. Esse backup é o ponto de desfazer, e todo desfazer posterior volta para ele — sem recursão, sem deriva.

Segundo, você precisa marcar uma caixa. O painel de confirmação lista o que será substituído e o que o agente mantém, e você tem que marcar “I understand this replaces <agent>” antes de o botão funcionar. Parece atrito; também elimina o “eu achei que isso era um sync”.

Terceiro, a falha nomeia arquivos. Se a restauração falha no meio, a tela de erro lista os arquivos que não puderam ser restaurados e oferece Undo (voltar ao estado anterior à transferência) e Retry. O desfazer sempre usa o primeiro ponto de desfazer, não importa quantos retries tenham acontecido no meio.

Mais um detalhe: o progresso tem três estágios — backup, porcentagem de upload, restauração — e Cancel só existe durante o backup e o upload. Uma vez iniciada a restauração, ela não pode ser parada, e o botão desaparece em vez de ficar sem fazer nada silenciosamente. Uma restauração interrompida é mais perigosa que uma concluída.

Por que os bots chegam desligados

Se a máquina de origem roda bots de Telegram, Discord ou parecidos, depois da transferência você vai encontrá-los desligados na máquina nova — token e configurações intactos, só não iniciados.

Isso é de propósito. A transferência pelo desktop passa --messaging-off, então todo bot de mensageria no backup chega desligado e a máquina de onde ele veio continua respondendo. Caso contrário, duas máquinas brigam por um único token de bot, e o comportamento fica imprevisível: respostas duplicadas, disputa de lock, cada uma derrubando a conexão da outra.

A ordem sensata é: transferir → confirmar que o agente na nuvem está certo → ligar cada bot na página Messaging → desligar o bot correspondente na máquina antiga. O app de desktop só sugere desligar os bots locais depois que a transferência terminou, nunca antes.

Detalhes que você vai notar

  • A seção fica em Settings ▸ Backup & Transfer, logo depois de Sessions. É nativa, não é plugin; o deep link é /settings?tab=backup.
  • ⌘K tem duas entradas — Back up this agent e Transfer to Hermes Cloud — e as duas abrem a seção.
  • A rota antiga /move-to-cloud?agent=X (hermes://open/move-to-cloud?agent=X) agora redireciona para cá e já seleciona aquele agente.
  • Num Webapp servido pelo Hermes Cloud a seção mostra só o cartão de Backup, porque “mover para a nuvem” não faz sentido ali.
  • Um agente na nuvem anterior a essa funcionalidade é pego antes do upload: “This cloud agent needs a Hermes update before it can receive a transfer”, em vez de uma falha no meio do caminho.

A transferência em si tolera interrupções: os uploads são enviados em pedaços, um pedaço reenviado tarde não consegue truncar bytes mais novos, e iniciar um upload recupera os abandonados. Um desfazer remove o profile que a transferência criou, mas não apaga o workspace próprio do agente na nuvem nem os dotfiles do HOME — esses não foram produzidos pela transferência.

Quando usar

  • Máquina nova: migrar o agente inteiro vence copiar diretórios um por um; tire um snapshot de identidade com --quick primeiro e depois um backup completo.
  • Local para nuvem: mantenha o agente sempre no ar, com a cópia local como backup.
  • Nuvem para local: funciona no sentido inverso também, mas lembre que as configurações de provider do host são preservadas, então não espere que as credenciais da nuvem voltem junto.
  • Antes de uma atualização: hermes backup --quick --label pre-upgrade é seguro barato.

Se você se importa com como as credenciais são guardadas dentro de um backup, leia keychain e criptografia de segredos. Outras flags de hermes import estão na referência de comandos, e o comando de backup em hermes backup.

A versão curta

O valor aqui não é “um botão novo”. É que três coisas fáceis de errar viraram padrão: o backup inclui as partes que você sempre esquece, a migração tem um ponto de desfazer que nada consegue sobrescrever, e duas máquinas não conseguem brigar por um token de bot. Se você prefere fazer na mão, são dois comandos — hermes backup e hermes import --keep-host.

Lançado na janela da v0.23.2.