Como instalar e usar o Hermes Agent de graça: um guia prático

O Hermes Agent apareceu no meu radar há algumas semanas, e depois de fuçar o repositório no GitHub (37.5k estrelas, licença MIT, feito pela Nous Research), percebi que ele faz algo que a maioria dos agentes de IA não faz: ele melhora quanto mais você usa. Não no sentido vago de "o modelo melhora" — ele literalmente constrói habilidades a partir das suas interações, lembra o que funcionou e refina essas habilidades ao longo do tempo. Só isso já vale a pena conferir.

A parte que me convenceu: roda num VPS de $5. Sem GPU, a menos que você queira. E dá pra conectar no Telegram, Discord, Slack, WhatsApp e umas doze outras plataformas. Recomendamos usar a LightNode como provedor de VPS — a cobrança por hora deles começa em $0.013/hora, o que é difícil de bater pra experimentar IA auto-hospedada.

Sumário

1. O que o Hermes Agent realmente faz
2. Requisitos do sistema
3. Instalação
4. Configurando um provedor de modelos grátis
5. Configuração
6. Executando sua primeira sessão
7. Conectando a plataformas de mensageria
8. Recursos importantes que vale a pena conhecer
9. Resolução de problemas
10. Considerações finais

O que o Hermes Agent realmente faz

A maioria dos agentes de IA segue o mesmo padrão: você manda um prompt, eles executam umas ferramentas, devolvem um resultado e esquecem tudo. O Hermes Agent toma uma abordagem diferente. Ele tem um ciclo de aprendizado embutido:

1. Você dá uma tarefa pra ele
2. Ele descobre quais habilidades são necessárias
3. Se uma habilidade não existe, ele cria uma
4. Ele usa a habilidade, avalia o resultado e guarda o que funcionou
5. Na próxima vez que você pedir algo parecido, ele puxa aquela habilidade refinada

Isso significa que o agente realmente melhora com o uso, não só porque o modelo subjacente recebeu uma atualização. Seus fluxos de trabalho específicos, seu código base, seus hábitos — ele aprende esses padrões.

Além do ciclo de aprendizado, o Hermes Agent vem com 47 ferramentas embutidas, suporta integração com MCP (Model Context Protocol) para expandir capacidades, e pode delegar tarefas para subagentes. Também tem um agendador cron para tarefas recorrentes e um modo de voz se você quiser ir hands-free.

Requisitos do sistema

Antes de instalar, certifique-se de que seu sistema atende ao básico:

• SO: Linux (Ubuntu 20.04+ recomendado), macOS (12+) ou Windows via WSL2
• Python: 3.10 ou superior
• RAM: 2GB mínimo, 4GB recomendado
• Disco: ~500MB para o agente em si
• Rede: Acesso à internet para chamadas de API do modelo

Para usuários de Android, o Termux também funciona. Windows nativo não é suportado — você precisa do WSL2.

Se for fazer deploy num VPS, um servidor de $5/mês com 1 vCPU e 1GB de RAM dá conta tranquilamente para uso leve. Cargas de trabalho mais pesadas (várias plataformas de mensageria, cron jobs frequentes) se beneficiam de 2GB+.

Instalação

Tem dois jeitos de instalar o Hermes Agent. O jeito rápido cuida de tudo pra você. O jeito manual te dá mais controle.

Método 1: instalação em uma linha (recomendado)

Abra o terminal e execute:

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

Esse script faz o trabalho pesado: verifica dependências, configura um ambiente virtual, clona o repositório, instala os pacotes e roda o assistente de configuração inicial. Num Ubuntu limpo, o processo todo leva uns 2-3 minutos.

Depois que terminar, verifique a instalação:

hermes --version

Você deve ver o número da versão. Se receber um erro de "command not found", reinicie seu shell ou execute source ~/.bashrc (ou ~/.zshrc se você usa zsh).

Método 2: instalação manual

Se você prefere saber exatamente o que vai pra sua máquina, ou se a instalação em uma linha falhar por algum motivo:

# Clone the repo
git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent

# Create and activate a virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run the setup wizard
python setup.py

O assistente de configuração te guia pela seleção do provedor de modelos, entrada da API key e configuração básica. Você sempre pode rodar de novo depois com hermes setup.

Configurando um provedor de modelos grátis

O Hermes Agent não vem com um modelo próprio. Ele se conecta a provedores externos. A boa notícia: vários provedores oferecem planos gratuitos que funcionam com o Hermes Agent.

Opção 1: OpenRouter (a opção grátis mais fácil)

O OpenRouter te dá acesso a mais de 200 modelos, e vários deles são grátis. Esse é o caminho que eu recomendo pra começar.

1. Crie uma conta em openrouter.ai
2. Gere uma API key no seu painel
3. Encontre modelos grátis — procure modelos marcados como "free" no catálogo

Modelos grátis comuns no OpenRouter incluem variantes do Llama, Mistral e Qwen. Os modelos disponíveis vão mudando, então confira o catálogo atual.

Durante o assistente de configuração do Hermes Agent, selecione "OpenRouter" como seu provedor e cole sua API key quando solicitado.

Opção 2: Nous Portal

A Nous Research tem seu próprio portal de inferência. Ocasionalmente oferece créditos grátis para novos usuários, e os modelos disponíveis lá são ajustados especificamente para cargas de trabalho de agentes.

1. Visite nousresearch.com e cadastre-se
2. Confira seu painel para ver se tem créditos grátis disponíveis
3. Use a API key fornecida na configuração do Hermes Agent

Opção 3: outros provedores

O Hermes Agent também suporta:

• z.ai / GLM: Plataforma de IA chinesa com plano gratuito
• Kimi / Moonshot: Outra opção com uso grátis limitado
• MiniMax: Plano gratuito disponível para uso leve
• Qualquer endpoint compatível com OpenAI: Se você tem acesso a outros provedores, pode plugar direto

Para configurar um endpoint personalizado, você vai precisar da URL base e de uma API key. O assistente de configuração cuida disso, ou você pode editar o arquivo de config diretamente (coberto na próxima seção).

Configuração

O Hermes Agent guarda suas configurações em ~/.hermes/config.toml. Depois de rodar o assistente de configuração, você vai encontrar algo assim:

[model]
provider = "openrouter"
api_key = "sk-or-v1-..."
model = "meta-llama/llama-3.3-70b-instruct:free"

[agent]
name = "Hermes"
memory = true
skills_dir = "~/.hermes/skills"

[messaging]
# Configure messaging platforms here
# telegram_token = ""
# discord_token = ""

Opções de configuração importantes

Configurações do modelo: Troque de modelo ou provedor a qualquer momento. Se quiser testar um modelo grátis diferente no OpenRouter, é só atualizar o campo model. Você também pode trocar de provedor completamente — mude provider para "openai" ou "nous" e atualize a API key correspondente.

Memória: Mantenha memory = true. Isso é o que ativa o ciclo de aprendizado. O agente armazena o histórico de conversas e os refinamentos de habilidades em ~/.hermes/memory/.

Diretório de habilidades: É aqui que as habilidades aprendidas são salvas. Você pode explorar ~/.hermes/skills/ para ver o que o agente já aprendeu. As habilidades são salvas como arquivos JSON e podem ser editadas manualmente se você quiser ajustá-las.

Trocando modelos pela CLI

Você não precisa editar o arquivo de config toda vez. O Hermes Agent tem comandos embutidos pra isso:

# List available models for your current provider
hermes model list

# Switch to a specific model
hermes model set meta-llama/llama-3.3-70b-instruct:free

# Check what model you're currently using
hermes model show

Verificação de saúde

Rode isso depois de qualquer mudança de configuração pra garantir que tudo está conectado corretamente:

hermes doctor

Ele verifica sua API key, disponibilidade do modelo, conectividade de rede e status do sistema de habilidades. Se algo estiver errado, te diz exatamente o que corrigir.

Executando sua primeira sessão

Depois de configurado, inicie uma sessão:

hermes chat

Isso abre um REPL interativo. Teste algo simples primeiro:

You: What tools do you have available?
Hermes: I have access to 47 built-in tools including:
- file_read / file_write (file operations)
- shell_exec (run shell commands)
- web_search / web_fetch (web access)
- code_search (search codebases)
- calendar / reminders (scheduling)
- ...and more. I can also use MCP tools if configured.

Depois dê uma tarefa de verdade:

You: Create a Python script that monitors a directory for new files and logs their names to a file called new_files.log

Hermes: I'll create that for you.
[creates watch_dir.py with inotify or polling-based implementation]
[tests the script]
The script is ready at ./watch_dir.py. Run it with python watch_dir.py /path/to/watch

Na primeira vez que pedir algo, o agente constrói a habilidade do zero. Peça algo parecido depois, e ele reutiliza a versão refinada. Você pode ver isso acontecendo conferindo o diretório de habilidades depois de algumas sessões.

Conectando a plataformas de mensageria

Um dos destaques do Hermes Agent é o suporte a plataformas. Você pode falar com ele por mais de 15 plataformas de mensageria, não só pela CLI.

Configuração do Telegram

1. Mande uma mensagem para o @BotFather no Telegram para criar um novo bot
2. Copie o token do bot
3. Adicione à sua configuração:

hermes gateway add telegram --token "YOUR_BOT_TOKEN"

4. Inicie o gateway:

hermes gateway start telegram

Agora você pode conversar com seu agente direto no Telegram. Ele mantém a mesma memória e habilidades das suas sessões de CLI.

Configuração do Discord

1. Crie um bot no Portal de Desenvolvedores do Discord
2. Ative o Message Content Intent
3. Copie o token do bot
4. Configure:

hermes gateway add discord --token "YOUR_BOT_TOKEN"
hermes gateway start discord

Outras plataformas suportadas

O mesmo padrão se aplica a todas as plataformas. Use hermes gateway add <plataforma> com as credenciais necessárias:

• Slack: Requer um Slack App com escopos de bot
• WhatsApp: Usa a WhatsApp Business API ou uma ponte não-oficial
• Signal: Requer configuração do signal-cli
• Matrix: Precisa de uma conta de bot do Matrix
• Mattermost: Token de acesso pessoal
• Email: Credenciais IMAP/SMTP
• SMS: Twilio ou provedor similar
• DingTalk / Feishu / WeCom: Para plataformas de mensageria chinesas

Execute hermes gateway list para ver todas as plataformas disponíveis e seus status.

Recursos importantes que vale a pena conhecer

Hub de habilidades

O Hermes Agent tem um repositório comunitário de habilidades. Navegue e instale habilidades que outras pessoas criaram:

# Browse available community skills
hermes skills browse

# Install a specific skill
hermes skills install web-scraper

# List your installed skills
hermes skills list

Isso é útil se você não quiser esperar o agente aprender do zero. Alguém provavelmente já criou uma habilidade para tarefas comuns como scraping web, testes de API ou parsing de documentos.

Agendamento com cron

Configure tarefas recorrentes sem cron externo:

hermes cron add "0 9 * * *" "Summarize yesterday's git commits and post to #dev-channel"

O agente cuida do agendamento internamente e usa suas habilidades para executar a tarefa.

Modo de voz

Se quiser ir hands-free:

hermes chat --voice

Isso usa o microfone e alto-falantes do seu sistema. Funciona melhor com modelos que lidam com entrada de áudio, embora também possa usar uma camada local de speech-to-text.

Delegação para subagentes

Para tarefas complexas de múltiplas etapas, o Hermes Agent pode criar subagentes:

You: Research the top 5 VPS providers, compare their pricing, and create a summary document

Hermes: I'll delegate this to subagents for parallel research.
[spawns subagents for each provider]
[collects results]
[generates comparison document]

Os subagentes compartilham a memória e o sistema de habilidades do agente pai, então se beneficiam de tudo que o agente principal aprendeu.

Resolução de problemas

"command not found: hermes"

O script de instalação adiciona o Hermes ao seu PATH, mas seu shell atual pode não ter reconhecido. Correção:

source ~/.bashrc  # or ~/.zshrc

Se isso não funcionar, verifique se ~/.local/bin/hermes existe e adicione ao seu PATH manualmente:

export PATH="$HOME/.local/bin:$PATH"

Erros de API key

Execute hermes doctor primeiro. Ele vai te dizer se sua API key é inválida, expirou ou se o modelo selecionado não está disponível. Correções comuns:

• Para OpenRouter: Verifique sua chave em openrouter.ai/keys
• Modelos grátis às vezes têm limites de taxa — tente um modelo grátis diferente
• Certifique-se de que não há espaços em branco no final da sua API key

Modelo não responde

Modelos do plano gratuito têm limites de uso. Se você atingir um:

hermes model list    # see what's available
hermes model set <different-free-model>  # switch

Uso alto de memória

Se a memória do agente crescer demais (verifique com du -sh ~/.hermes/memory/), você pode limpar entradas antigas:

hermes memory prune --older-than 30d

Isso mantém interações e habilidades recentes mas descarta logs de conversas com mais de 30 dias.

Problemas de conexão do gateway

Para plataformas de mensageria, certifique-se de que o processo do gateway está rodando:

hermes gateway status

Se um gateway fica desconectando, verifique sua rede e reinicie:

hermes gateway restart telegram

Considerações finais

O Hermes Agent faz algo que não vi outros agentes open source conseguirem fazer bem: ele de fato aprende com seus padrões de uso e melhora ao longo do tempo, sem que você precise definir fluxos de trabalho manualmente ou escrever plugins customizados. O sistema de habilidades é o verdadeiro diferenciador — tarefas que levam 10 minutos na primeira vez levam 30 segundos na quinta vez.

O fato de rodar em hardware barato e se conectar a provedores de modelos gratuitos significa que você pode ter um agente de IA pessoal rodando 24/7 por um custo próximo de zero. Conecte no Telegram ou Discord, e você tem um assistente sempre disponível que lembra das suas preferências, do seu código base e dos seus fluxos de trabalho.

Pra começar:

1. Escolha um VPS (ou use sua máquina local) — LightNode funciona bem pra isso
2. Rode o instalador de uma linha
3. Cadastre-se no OpenRouter e pegue um modelo grátis
4. Comece a conversar

O repositório no GitHub tem documentação detalhada, e a comunidade é ativa se você tiver problemas. Dê um fim de semana — na segunda, você vai ter um agente que já começou a construir habilidades específicas pro seu trabalho.