Como manter o Hermes Agent a funcionar num servidor permanentemente

Depois de instalar o Hermes Agent num portátil, surge uma pergunta: quem vai responder no Telegram e preparar os resumos da manhã quando o portátil estiver fechado? Na sua secretária, o agente só funciona enquanto o computador estiver ligado. Para manter o bot sempre online e fazer com que as tarefas agendadas sejam executadas automaticamente, tem de transferir o agente para um servidor.

A seguir, explicamos como instalar o Hermes num servidor Linux normal, transformar o gateway num serviço em execução contínua que arranca automaticamente após uma reinicialização e restringir o acesso para impedir que estranhos acedam ao terminal. Este guia baseia-se na documentação oficial.

Se ainda não instalou o Hermes, comece pela visão geral separada sobre o que é este agente e como o instalar. Este guia pressupõe que já o tem a funcionar na sua própria máquina e aborda apenas a transferência para um servidor.

Pode encontrar informações sobre como trabalhar com o Ailoot na documentação.

Porquê transferir o Hermes Agent de um portátil para um servidor?#

Num portátil, o Hermes só funciona enquanto a tampa estiver aberta e estiver por perto. Feche-o e o bot fica em silêncio; o resumo da manhã nunca chega. Isso não serve para uma tarefa como «responder às pessoas num serviço de mensagens e tratar de coisas segundo um horário».

É isso que distingue um servidor: nunca dorme e não depende de mais nada. Instala exatamente o mesmo Hermes nele, e este funciona sem si: responde no Telegram às três da manhã, reúne notícias sobre os seus temas todas as manhãs e mantém as sessões entre execuções.

A transferência faz sentido quando tem uma tarefa contínua para o agente: um bot para si ou para a sua equipa, resumos matinais, respostas automáticas ou trabalho regular com documentos. Se está apenas a experimentar o Hermes para um projeto específico e está por perto, ainda não precisa de um servidor; é um passo adicional.

O que deve preparar antes de instalar o Hermes num VPS?#

Reúna três coisas antes de instalar.

O servidor. Um VPS Linux normal serve. A documentação indica suporte de primeira linha para Linux e WSL2, e os testes são feitos na versão mais recente do Ubuntu. Se o sistema tiver glibc, systemd e uma estrutura de diretórios habitual, o Hermes será instalado corretamente. Isto é importante num servidor porque todos os passos de arranque automático abaixo dependem do systemd, que vem incluído no Ubuntu e no Debian.

Acesso SSH. Liga-se ao servidor através de um terminal por SSH; não vai usar um rato. Todos os comandos abaixo são executados nesta sessão SSH. Se programa com vibe coding e ainda não se sente à vontade com o terminal, não se preocupe: são apenas alguns comandos e pode copiar cada um na íntegra.

Um modelo escolhido. O agente não pensa por si; chama um modelo. Num servidor que funciona sem si, é importante que o acesso ao modelo não expire. A opção mais simples é uma subscrição do Nous Portal através de hermes setup --portal: a autenticação utiliza OAuth e o token é renovado automaticamente. Também pode usar as suas próprias chaves API, mas confirme que há saldo na conta — um agente sem interface gráfica e com saldo zero simplesmente fica em silêncio. O modelo tem de ter uma janela de contexto de, pelo menos, 64 000 tokens, caso contrário o Hermes recusar-se-á a arrancar com ele. Todos os modelos na nuvem da lista cumprem este requisito.

Como instalar o Hermes Agent num servidor com um único comando?#

A instalação num servidor é quase igual à de um portátil, com uma diferença: normalmente, o agente não precisa de um browser. A automatização do browser também inclui o pesado Chromium. É por isso que se usa a opção --skip-browser.

1. Ligue-se ao servidor por SSH

   ssh root@your-server-address
   

   Execute todos os comandos seguintes nesta sessão, no próprio servidor.

2. Execute o instalador sem o browser

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

   O script descarrega o ambiente necessário e instala o comando hermes. A opção --skip-browser ignora a instalação da automatização do browser; num servidor sem interface gráfica, esta apenas ocuparia espaço. Se precisar de um browser mais tarde, pode instalá-lo separadamente.

3. Reinicie a shell e escolha um modelo

   source ~/.bashrc
   hermes setup --portal
   

   A primeira linha carrega o novo PATH para que o comando hermes possa ser encontrado. A segunda abre a autenticação do Nous Portal: confirme o início de sessão e o agente obtém um modelo e serviços sem precisar de chaves separadas para cada um.

4. Verifique a instalação

   hermes doctor
   

   O comando mostra o que está instalado, o que falta e como corrigir. As marcas verdes indicam que está tudo pronto.

Antes de adicionar um bot e um horário, confirme primeiro que consegue ter uma conversa normal diretamente no servidor: execute hermes e dê-lhe uma tarefa simples com uma resposta verificável. A documentação recomenda expressamente que não se acrescentem funcionalidades antes de uma conversa normal funcionar — uma recomendação sensata.

Como manter o Hermes a funcionar permanentemente?#

O gateway é um único processo Hermes em segundo plano que mantém as ligações a todos os serviços de mensagens, gere sessões e executa tarefas agendadas. Todo o funcionamento permanente depende dele. O objetivo é fazer com que este processo arranque sozinho e continue em execução.

Configure primeiro o gateway e ligue um serviço de mensagens:

hermes gateway setup

O assistente de configuração orienta-o pelas plataformas e ajuda-o a introduzir o token do bot e a lista de acesso. Os passos para ligar o Telegram (criar um bot com o BotFather, descobrir o seu ID e introduzir o token) são abordados no guia de instalação principal; não os vou repetir aqui.

A seguir vem a armadilha de que as pessoas mais frequentemente se esquecem. Se executar simplesmente hermes gateway, o processo só funcionará enquanto a sessão SSH estiver aberta. Feche o terminal e o gateway para. Para o manter sempre em execução, tem de o colocar sob o controlo do sistema. Há um comando para isso:

hermes gateway install

Instala o gateway como um serviço: no Linux, como um serviço systemd de utilizador; no macOS, através do launchd. O sistema monitoriza o processo e volta a iniciá-lo se falhar.

Num servidor, é mais provável que precise da segunda opção: um serviço do sistema que arranca quando a máquina inicia, antes de qualquer utilizador iniciar sessão:

sudo hermes gateway install --system

É exatamente disso que precisa para um VPS: o servidor reinicia, o serviço arranca sozinho e o bot volta a ficar online. Faça a gestão com estes comandos simples:

hermes gateway start     # iniciar
hermes gateway stop      # parar
hermes gateway status    # verificar estado

Para um serviço do sistema, adicione sudo e a opção --system a estes comandos. Sem eles, os comandos serão aplicados ao serviço de utilizador, em vez de ao serviço que arranca com o sistema:

sudo hermes gateway start --system
sudo hermes gateway stop --system
sudo hermes gateway status --system

Porque é necessário o linger e o que falha sem ele?#

Este é o obstáculo mais comum: instalou o serviço, mas o bot continua a ficar em silêncio durante a noite. A razão está na forma como funcionam os serviços de utilizador do Linux.

Por predefinição, um serviço systemd de utilizador está associado à sua sessão. Liga-se por SSH e o seu gestor de utilizador inicia; o serviço funciona. Termina a sessão e o sistema considera o utilizador inativo, pelo que encerra os serviços desse utilizador, incluindo o gateway. Num servidor em que inicia e termina sessão, isto é um problema: o bot só está online enquanto estiver na sessão SSH.

Pode corrigir isto com o modo linger, que permite ao sistema manter o gestor de utilizador em execução mesmo quando esse utilizador não tem sessão iniciada:

sudo loginctl enable-linger username

Depois deste comando, o serviço de utilizador funciona por si só e arranca quando o servidor inicia, sem esperar que inicie sessão. Sem linger, regressa o comportamento original: o gateway para quando termina a sessão SSH e não arranca durante o arranque. A documentação afirma-o explicitamente.

Como executar o Hermes num servidor com Docker e reinícios automáticos?#

O Docker é outra forma eficaz de manter o agente num servidor, especialmente se já estiver habituado a contentores ou quiser isolar o agente do sistema principal. Configure-o uma vez com docker run ... setup e, depois, inicie o contentor em segundo plano:

docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  -p 8642:8642 \
  nousresearch/hermes-agent gateway run

Eis o que fazem as linhas responsáveis pelo funcionamento permanente:

• -d — o contentor funciona em segundo plano e não mantém o terminal aberto.
• --restart unless-stopped — o Docker volta a iniciar o contentor após o reinício do servidor ou uma falha. Só não o reinicia se o tiver parado manualmente.
• -v ~/.hermes:/opt/data — as definições, chaves, sessões e memória ficam no servidor, fora do contentor, e sobrevivem à sua recriação.

A imagem acrescenta mais uma proteção: o processo do gateway funciona sob o supervisor s6. Se o gateway falhar, é reiniciado em poucos segundos sem que o próprio contentor se perca. É uma proteção dupla: o Docker mantém o contentor em execução a partir do exterior, enquanto o s6 monitoriza o processo no interior.

Lembre-se de uma diferença da abordagem com Docker: estas instalações não são atualizadas com o comando hermes update. Para atualizar no Docker, substitua a imagem por uma nova — descarregue a mais recente e recrie o contentor.

Como verificar se tudo funciona e se resiste a um reinício?#

Verifique o estado e os registos de um serviço de utilizador assim:

hermes gateway status
journalctl --user -u hermes-gateway -f

Para o serviço de sistema recomendado num VPS, use o âmbito de sistema:

sudo hermes gateway status --system
sudo journalctl -u hermes-gateway -f

O primeiro comando verifica o serviço escolhido; o segundo acompanha os registos desse âmbito. Estes nomes de unidades aplicam-se à instalação predefinida em ~/.hermes. Outras pastas Hermes podem ter unidades com sufixo: examine a saída de estado e use essa unidade exata. Não acompanhe uma unidade de utilizador ao testar uma instalação de sistema. Os registos do Hermes estão em ~/.hermes/logs/ e os segredos são automaticamente ocultados, pelo que é seguro enviá-los ao suporte.

Agora reinicie o servidor e confirme que o agente volta a arrancar sozinho. Este é o principal teste ao servidor e costuma ser aquele de que as pessoas se esquecem:

sudo reboot

Quando o servidor voltar a estar acessível, ligue-se por SSH. Para a instalação de sistema, consulte sudo hermes gateway status --system e o journal de sistema; para a instalação de utilizador com linger, consulte hermes gateway status e o journal do utilizador. Envie depois uma mensagem ao bot no Telegram. Se responder sem a sua intervenção, o arranque automático está configurado corretamente. Era esse o objetivo.

Não precisa de se preocupar com a perda da conversa. O Hermes grava as sessões no disco e estas sobrevivem ao reinício do gateway. Além disso, se o gateway falhar precisamente quando está a enviar uma resposta, entregá-la-á após a recuperação em vez de voltar a executar a tarefa. Isto é importante para um bot que funciona permanentemente: um reinício inesperado não interrompe a conversa.

Como proteger um agente com acesso ao terminal num servidor?#

Um agente num servidor é um programa com acesso ao terminal que funciona sem a sua supervisão. Verifique primeiro estas três definições.

Acesso fechado ao bot. Por predefinição, o gateway só responde às pessoas da lista de acesso ou a quem concluiu a associação por código numa mensagem direta. Esse é o comportamento adequado para um bot com acesso ao terminal: uma pessoa qualquer que envie uma mensagem ao bot não consegue fazer nada. A lista é definida através de IDs numéricos, por exemplo, para o Telegram:

TELEGRAM_ALLOWED_USERS=123456789,987654321

Confirmação de comandos perigosos. Antes de fazer qualquer coisa destrutiva, o agente pede a sua autorização. Existe um modo YOLO que desativa as confirmações; é melhor não o ativar num servidor que funciona sem a sua supervisão. As confirmações existem precisamente para impedir que aconteça algo irreversível sem o seu conhecimento.

Um sandbox para isolamento total. Se quiser impedir fisicamente que o agente veja o sistema principal do servidor, execute os seus comandos num contentor Docker:

hermes config set terminal.backend docker

Assim, tudo o que o agente faz no terminal acontece dentro de um sandbox isolado e não consegue aceder ao servidor em produção. É uma medida sensata quando dá liberdade ao agente para agir por conta própria.

O que fazer se o bot estiver em silêncio ou o gateway falhar?#

Quando o bot deixa de responder, siga esta ordem. Verifique primeiro o âmbito instalado: sudo hermes gateway status --system e o journal de sistema para um serviço de sistema, ou hermes gateway status e o journal de utilizador para um serviço de utilizador. Se o gateway estiver em execução, mas as mensagens não chegarem, quase sempre se trata de um problema de configuração da plataforma: o token do bot está errado ou a pessoa não consta da lista de acesso. Execute novamente hermes gateway setup na mesma pasta Hermes e examine o serviço escolhido com hermes gateway status --system para sistema ou hermes gateway status para utilizador. Uma configuração bem-sucedida não prova que o gateway correto está em execução.

Se o modelo devolver respostas vazias ou estranhas, verifique-o com hermes model e confirme o fornecedor e a autenticação. A sequência geral de recuperação que o leva de «está tudo avariado» de volta ao funcionamento é: hermes doctor, hermes model, hermes setup, seguidos de hermes gateway status --system numa instalação de sistema ou hermes gateway status numa de utilizador.

Mais uma coisa para o caso raro, mas desagradável, em que todo o processo bloqueia sem chegar a falhar. Um serviço systemd tem um temporizador watchdog: acrescente esta linha a ~/.hermes/config.yaml e reinstale o serviço.

gateway:
  systemd_watchdog_seconds: 120

# Serviço de sistema no VPS (a mesma pasta Hermes da instalação original):
sudo hermes gateway install --system --force
sudo hermes gateway status --system

Para um serviço de utilizador, regenere apenas esse âmbito com hermes gateway install --force e consulte hermes gateway status. Escolha um âmbito; não instale ambos para reparar um único gateway.

Depois disso, o gateway sinaliza regularmente ao sistema: «Estou vivo» e, se os sinais pararem, o systemd reinicia o processo automaticamente. Isto só funciona no Linux com systemd e apenas quando o processo bloqueia. O temporizador watchdog não afeta uma interrupção normal da ligação de rede entre o servidor e o serviço de mensagens.

Que outras perguntas fazem sobre o Hermes Agent num servidor?#