Rodando o Hermes Agent no Windows com WSL2

O Hermes Agent Não Suporta Windows Nativo

Se você está no Windows e tentando instalar o Hermes Agent, vai bater em um muro rapidamente. A documentação oficial do Hermes afirma claramente: Windows nativo não é suportado. As plataformas suportadas são Linux, macOS, WSL2 e Android via Termux.

Essa lacuna não deve fechar tão cedo. O Hermes usa shell tooling, gerenciamento de processos e convenções de sistema de arquivos que são nativas do Linux. O caminho correto no Windows é o WSL2, o Windows Subsystem for Linux 2, que oferece um kernel Linux real rodando dentro do Windows.

Este guia percorre o setup completo do WSL2 para o Hermes Agent e explica onde a fricção aparece após o primeiro run bem-sucedido.

O Que o WSL2 Realmente É

O WSL2 não é um emulador nem uma camada de compatibilidade. Ele roda um kernel Linux real em uma máquina virtual leve. Dentro de um shell WSL2, você tem um ambiente Linux de verdade: sistema de arquivos, tabela de processos, gerenciador de pacotes e rede.

Para o Hermes, isso significa que tudo que funciona em um servidor Linux também funciona no WSL2, com algumas ressalvas de rede e persistência que vamos cobrir abaixo.

A Microsoft inclui o WSL2 no Windows 10 moderno (build 1903 e posterior) e no Windows 11. Se o seu Windows está razoavelmente atualizado, você já tem acesso a ele.

Passo 1: Habilitar o WSL2

Abra o PowerShell como Administrador e execute:

wsl --install

Esse comando habilita o recurso WSL, instala a distribuição Linux padrão (Ubuntu) e define o WSL2 como a versão padrão. Requer uma reinicialização para concluir.

Se você já tem o WSL1 instalado e quer atualizar para WSL2:

wsl --set-default-version 2

Depois, verifique qual versão sua distribuição está usando:

wsl --list --verbose

Procure a coluna VERSION. Você quer 2.

Passo 2: Configurar o Ubuntu no WSL2

Após a reinicialização, abra o Ubuntu pelo menu Iniciar. O primeiro launch guia você pela criação de um username Unix e senha. Esse é seu usuário WSL2, separado da sua conta Windows.

Atualize a lista de pacotes e atualize os pacotes instalados:

sudo apt update && sudo apt upgrade -y

Instale o curl e outros básicos que o Hermes vai precisar:

sudo apt install -y curl git build-essential

Passo 3: Instalar o Hermes Agent Dentro do WSL2

Com um ambiente Ubuntu funcionando, instale o Hermes usando o script oficial de instalação:

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

Após a instalação, execute o setup:

hermes setup

Isso guia você pela seleção de provedor, configuração de modelo e setup opcional do Telegram. Escolha OpenRouter para o primeiro run mais simples: você vai precisar de uma API key do OpenRouter pronta.

Após o setup, inicie o Hermes:

hermes

Se você ver a interface de terminal, sua instalação no WSL2 está funcionando.

Passo 4: Configuração do Telegram no WSL2

Colocar o Hermes no Telegram dentro do WSL2 requer alguns passos extras em comparação com um servidor Linux nativo.

O gateway de mensagens do Hermes precisa ficar rodando para receber mensagens do Telegram. No WSL2, o processo roda enquanto a sessão WSL2 estiver aberta. Se você fechar o terminal, o gateway para e as mensagens do Telegram não serão entregues.

Para manter o gateway rodando em segundo plano:

hermes gateway start --detach

Verifique que está rodando:

hermes gateway status

Se você quer que o gateway inicie automaticamente quando o WSL2 começar, pode adicioná-lo ao seu ~/.bashrc ou configurar um serviço systemd (o WSL2 suporta systemd em versões recentes no Windows 11).

Limitações Conhecidas do WSL2 para o Hermes

Memória e estado não sobrevivem a shutdowns do WSL2. Por padrão, o WSL2 encerra quando você fecha a última sessão. Os processos em execução param. Se o Hermes está recebendo mensagens do Telegram ou executando tarefas agendadas, elas serão interrompidas. Você precisa reiniciar o Hermes e o gateway toda vez que o WSL2 iniciar.

A rede é em bridge, não nativa. O WSL2 cria um adaptador de rede virtual. Sua instância do Hermes não tem um endereço IP estável pela perspectiva da internet. Isso importa se você está construindo integrações que precisam receber tráfego webhook, mas não afeta chamadas de saída para o Telegram ou APIs de modelo.

Fricção de caminhos de arquivo. O WSL2 tem seu próprio sistema de arquivos Linux (\\wsl$\Ubuntu\home\... no Windows). Se você quer compartilhar arquivos entre o WSL2 e aplicações Windows, pode montar caminhos Windows dentro do WSL2 (/mnt/c/...). Os arquivos de memória e configuração do Hermes ficam no seu diretório home WSL2 por padrão, o que significa que não são acessíveis diretamente pelo Explorer sem usar o caminho de rede.

Desempenho em caminhos Windows. Se você armazenar arquivos do Hermes no sistema de arquivos Windows (sob /mnt/c/), as operações de arquivo serão mais lentas do que se estiverem no sistema de arquivos WSL2. Mantenha os dados do Hermes no diretório home Linux para melhor desempenho.

Requer deixar o WSL2 aberto. Para o Hermes estar continuamente disponível no Telegram, seu terminal WSL2 precisa ficar rodando. Essa é a maior restrição operacional para usuários Windows que querem um agente persistente.

Quando Hospedagem Gerenciada É a Melhor Escolha para Usuários Windows

Para a maioria dos usuários Windows, o WSL2 funciona bem o suficiente para avaliação e aprendizado. Os problemas aparecem quando você quer disponibilidade persistente e always-on do Hermes.

O WSL2 é uma ferramenta de desenvolvedor, não um servidor. Mantê-lo rodando continuamente significa que sua máquina Windows precisa ficar ligada, a sessão WSL2 não pode fechar e você é responsável por restarts quando atualizações do Windows forçam uma reinicialização.

Se você quer o Hermes disponível no Telegram 24 horas por dia sem que sua máquina local esteja rodando, tem duas opções:

Alugar um VPS Linux e rodar o Hermes lá em vez de localmente.
Usar hospedagem gerenciada como a Hermify, onde o runtime fica em um servidor persistente e você interage com ele pelo Telegram e pelo dashboard.

O segundo caminho não exige conhecimento de Linux, sem gerenciamento de VPS, e funciona no Windows sem WSL2 algum. Você não instala nada localmente. A Hermify gerencia o runtime por você. O bot do Telegram fica disponível porque está rodando em um servidor real, não no seu laptop.

Esse é o caminho que a maioria dos usuários Windows toma quando passam da avaliação e querem o Hermes como assistente diário de verdade.

Um Framework Prático de Decisão

| Cenário | Recomendação | |---|---| | Testando o Hermes pela primeira vez no Windows | WSL2 funciona bem | | Construindo tooling customizado ou contribuindo para o Hermes | WSL2 numa máquina de desenvolvimento | | Quer o Hermes no Telegram disponível o dia todo | Hospedagem gerenciada (Hermify) ou VPS Linux | | Quer pular o setup Linux completamente | Hospedagem gerenciada | | Já roda Linux localmente ou em servidor | Linux nativo, sem WSL2 |

O WSL2 não é a ferramenta errada: é a ferramenta certa para desenvolvimento. Para uso persistente em produção, um runtime no servidor é mais confiável. Você pode explorar como a hospedagem gerenciada do Hermes se compara a um setup auto-hospedado em VPS se quiser avaliar as opções lado a lado.