Como instalar o Hermes Agent numa VPS: guia passo a passo

Prepare a VPS antes da instalação

Comece com uma VPS Linux com acesso por SSH funcional. Ubuntu aparece como a distribuição mais usada nesse tipo de cenário. No modo mais enxuto, sem ferramentas de navegador, o Hermes Agent roda com 1 GB de RAM; ao ativar automação de navegador, a recomendação sobe para 2 GB ou mais. Em setups com Docker, há quem prefira uma margem mais larga, como 2 vCPUs e 8 GB de RAM, mesmo com o contêiner consumindo em torno de 1 GB na base. Antes de seguir, atualize os pacotes e instale as dependências mínimas.

1. Conecte-se à VPS por SSH.
2. Atualize o sistema com sudo apt update && sudo apt upgrade -y.
3. Instale os pacotes básicos com sudo apt install -y git curl xz-utils ca-certificates.
4. Confirme se o Git está disponível com git --version.

Escolha entre instalação nativa ou Docker

O Hermes Agent entra na VPS por dois caminhos. A instalação nativa acelera o processo para quem quer deixar o agente rodando direto no terminal. O modo via Docker isola o ambiente e facilita recriar o contêiner ou migrar para outra máquina. Nos dois formatos, o estado do Hermes fica concentrado em um diretório de dados, que guarda configuração, chaves, perfis, memória, sessões e logs. Em uma VPS pequena com uso pessoal, a rota nativa tende a ser a mais curta. Em infraestrutura já orientada a contêiner, o Docker se encaixa melhor.

Instale o Hermes Agent pelo script oficial

Na instalação nativa, o Hermes Agent baixa e prepara o ambiente por conta própria. O script oficial provisiona Python 3.11, Node.js v22, ripgrep e ffmpeg, dispensando configuração manual dessas linguagens e ferramentas. Em VPS headless, o processo também segue sem o componente de browser, quando chamado com a flag adequada. Depois da instalação, o comando hermes precisa aparecer no shell atual.

1. No terminal da VPS, rode curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash.
2. Em servidor sem interface gráfica, adicione --skip-browser para pular o módulo de navegador.
3. Ao finalizar, recarregue o shell com source ~/.bashrc. Se estiver usando Zsh, use source ~/.zshrc.
4. Confirme a instalação com hermes --version.

Se o comando falhar durante a execução do script, o motivo recorrente é ausência de curl ou xz-utils, já que o instalador baixa o Node.js em um arquivo .tar.xz.

Instale o Hermes Agent com Docker

Para rodar o Hermes Agent em contêiner, crie um diretório persistente e use a imagem oficial nousresearch/hermes-agent. O fluxo se divide em dois comandos principais: um para iniciar o assistente de configuração e outro para manter o gateway rodando em background. O detalhe crítico é o volume mapeado para /opt/data, que concentra todos os arquivos do agente. Sem esse volume, qualquer recriação de contêiner zera configuração e memória.

1. Crie a pasta de dados com mkdir -p ~/.hermes.
2. Entre nela com cd ~/.hermes.
3. Para abrir o setup, rode docker run -it --rm -v ~/.hermes:/opt/data nousresearch/hermes-agent setup.
4. Depois, para manter o gateway ativo, use docker run -d --name hermes --restart unless-stopped -v ~/.hermes:/opt/data nousresearch/hermes-agent gateway run.

Verifique se as dependências e a configuração estão corretas

Antes de partir para gateway, Telegram ou outra automação, faça a checagem básica. O comando central é o hermes doctor, que lista dependências quebradas, versão do Python, status de conectividade e até incompatibilidade do modelo escolhido. Essa etapa reduz o tempo gasto caçando falhas de inicialização que parecem erro de rede, mas na verdade envolvem pacote ausente ou configuração incompleta.

1. Rode hermes doctor.
2. Confira a versão com hermes --version.
3. Para testar o chat direto no terminal, rode hermes.

Se o Hermes Agent abrir e devolver erro de autenticação ou conexão, retorne ao setup de configuração. Em problemas que surgem depois de uma atualização, há comandos específicos para revisar o arquivo de configuração: hermes config check, hermes config migrate e, em seguida, hermes doctor.

Configure o provedor de modelo e escolha um modelo compatível

O Hermes Agent depende de um provedor de LLM para responder às solicitações. A configuração passa por um assistente próprio, acessado por duas rotas: hermes setup ou hermes setup --portal. O modo com portal usa OAuth e, em ambiente sem navegador, a URL de autorização aparece diretamente no terminal ou nos logs. Entre os provedores listados estão OpenRouter, Anthropic, OpenAI, Nous Portal, Ollama, Kimi/Moonshot e endpoint personalizado compatível.

1. Rode hermes setup para o assistente completo ou hermes setup --portal para autenticar via Nous Portal.
2. Selecione o provedor de modelo.
3. Cole a chave de API ou finalize o login OAuth.
4. Escolha um modelo.

Atenção ao tamanho de contexto: o modelo configurado precisa suportar pelo menos 64.000 tokens. Com uma janela menor, o Hermes Agent tende a recusar o modelo na inicialização.

Teste o Hermes Agent no terminal antes de ativar o gateway

Com o modelo configurado, faça um teste rápido via CLI. O objetivo é checar se o Hermes Agent se conecta ao provedor e se as ferramentas básicas funcionam sem erro. Essa validação evita levar uma configuração quebrada para integrações como Telegram, Discord, Slack ou WhatsApp.

1. Abra uma sessão com hermes.
2. Envie uma pergunta curta e confirme se o modelo responde.
3. Para testar ferramenta, peça, por exemplo, para listar ou verificar o diretório atual.
4. Saia com /exit.
5. Para retomar a mesma sessão depois, use hermes --continue.

Se o Hermes Agent responder em branco ou travar ao chamar o modelo, os vilões prováveis são chave de API incorreta, provedor configurado fora do padrão ou modelo incompatível. Nessa situação, execute hermes setup novamente ou ajuste o modelo com hermes model, de acordo com o fluxo disponível na sua instalação.

Registre o gateway como serviço para o Hermes voltar no boot

É aqui que a instalação passa a operar em regime constante, sem depender da sua sessão de SSH. Em VPS e servidores headless, a orientação é registrar o gateway como serviço de sistema, e não como serviço de usuário. Assim, o Hermes Agent retorna após reinicialização sem depender de sessão ativa nem de lingering. Em distribuições Linux atuais, o serviço roda em cima de systemd.

1. Instale o gateway como serviço do sistema com sudo hermes gateway install --system.
2. Inicie o serviço com sudo hermes gateway start --system.
3. Cheque o estado com sudo hermes gateway status --system.
4. Para acompanhar logs em tempo real, use journalctl -u hermes-gateway -f.

Também existe a opção de serviço de usuário, mais adequada a notebook ou máquina de desenvolvimento. Em servidor, esse tipo de serviço pode ser encerrado ao final da sessão caso o lingering não esteja habilitado.

Conecte uma plataforma de mensagens, se quiser falar com o agente fora do terminal

Com a CLI operando e o gateway ativo, entra a etapa de integração com mensageria. As plataformas citadas incluem Telegram, Discord, Slack, WhatsApp, Signal e e-mail. O comando central é o assistente do gateway, que conduz a configuração do canal. Quem preferir pode adiar essa etapa até ter o teste básico no terminal resolvido.

1. Rode hermes gateway setup para iniciar a configuração.
2. Selecione a plataforma que deseja conectar.
3. Informe os dados que o assistente solicitar, como token ou credenciais do canal.
4. Confirme o funcionamento com hermes gateway status, quando esse fluxo estiver disponível na sua instalação.

Alguns fluxos trazem comandos específicos para cada plataforma, como hermes gateway enable telegram. O ponto é conectar o mensageiro só depois de garantir que o Hermes Agent responde direito pela CLI.