Como instalar e rodar o Hermes Agent no Windows?

Fala aí, beleza? Dá pra rodar o Hermes Agent no Windows sem WSL, sem Cygwin e sem Docker, e isso muda bastante coisa pra quem tava esperando ter que montar um Linux só pra testar um agente

O Hermes Agent é um agente de IA open source da Nous Research, com repositório oficial em NousResearch/hermes-agent, licença MIT e lançamento público em 25 de fevereiro de 2026

Aqui tu vai sair sabendo instalar no Windows nativo, configurar um provedor de modelo, conhecer o caminho alternativo pelo WSL2 e destravar os erros que mais aparecem nesse sistema

Um aviso honesto logo de cara: esse caminho nativo está em early beta, roda (CLI, gateway, TUI e ferramentas) mas tem arestas conhecidas em subprocessos, caminhos e saída de console não ASCII

O que você precisa antes de instalar

A lista de requisitos é curta, e a lista do que tu NÃO precisa é o que deixa a coisa boa 🙂

O que é exigido:

• Windows 10 ou Windows 11
• PowerShell ou Windows Terminal aberto
• uma chave de um provedor de modelo

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

O que NÃO é exigido:

• direitos de administrador (o instalador roda sem admin)
• WSL, Cygwin ou Docker
• instalar as dependências na mão

Esse último ponto merece uma parada. O instalador cuida sozinho de uv, Python 3.11, Node.js, ripgrep, ffmpeg e ainda descompacta um Git portátil (MinGit) em %LOCALAPPDATA%\hermes\git

Git portátil? É uma cópia isolada do Git, separada de qualquer Git que tu já tenha instalado no sistema. Se você conhece aquele padrão de ambiente virtual do Python, a ideia é a mesma: o Hermes não mexe no teu ambiente e o teu ambiente não quebra o dele

Sobra então o único pré-requisito humano: um provedor de modelo configurado. O quickstart oficial cobre Nous Portal, OpenRouter, OpenAI, Anthropic e qualquer endpoint compatível com OpenAI

Se tu curte o caminho do modelo rodando na tua máquina, já mostrei por aqui como rodar um modelo local no agente de código em outra ferramenta de terminal, dá pra sentir a diferença de abordagem

Como instalar o Hermes Agent no Windows passo a passo

Bora ver na prática?

1. Abre o PowerShell (ou o Windows Terminal) e roda o instalador

iex (irm https://hermes-agent.nousresearch.com/install.ps1)

A documentação também traz uma variante puxando o script direto do repositório:

iex (irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1)

O erro comum deste passo: tentar abrir o PowerShell como administrador achando que precisa. Não precisa, o instalador foi feito pra rodar sem admin

2. Fecha o terminal e abre uma janela NOVA

Esse passo parece bobo e é o campeão de dor de cabeça. O instalador adiciona %LOCALAPPDATA%\hermes\hermes-agent\venv\Scripts ao User PATH do usuário, e terminal já aberto não pega mudança de PATH

O erro comum deste passo: digitar hermes na mesma janela onde tu instalou e receber "comando não encontrado". Abre uma janela nova do PowerShell ou uma aba nova do Windows Terminal e tenta de novo

3. Configura o provedor de modelo

hermes config set OPENROUTER_API_KEY sk-or-...
hermes config set model <provedor/modelo>

A chave do OpenRouter tu cria em openrouter.ai, em Settings > API Keys, e ela começa com sk-or-

O erro comum deste passo: sair da tela da chave sem copiar. Chave de API costuma aparecer uma vez só, então guarda na hora

4. Roda o agente

hermes --tui

O comando hermes sozinho abre a CLI clássica e o hermes --tui abre a TUI, que é a recomendada, com banner mostrando modelo, ferramentas e skills

5. Passa o diagnóstico uma vez

hermes doctor

Ele detecta pendência de dependência e imprime o comando de correção na tela, o que economiza MUITO tempo de chute

Onde tudo isso mora no Windows:

No Windows nativo, o HERMES_HOME fica em %LOCALAPPDATA%\hermes, com as subpastas hermes-agent\, git\, node\ e bin\

Vale anotar esse caminho, porque metade dos problemas do próximo bloco se resolve olhando pra dentro dele

Instalação pelo WSL2: o caminho alternativo

Se tu prefere o ambiente Linux (ou vai deixar o agente trabalhando por horas), o caminho é o WSL2

1. Instala o WSL, em Windows 10 22H2 ou superior e no Windows 11

wsl --install

Esse comando instala o kernel WSL2, o recurso Virtual Machine Platform e o Ubuntu padrão

2. Confere a versão da distro e converte se preciso

wsl --set-default-version 2
wsl --set-version Ubuntu 2

O erro comum deste passo: seguir em frente com uma distro marcada como VERSION 1. O Hermes não funciona de forma confiável no WSL1, então converte antes de instalar qualquer coisa

3. Dentro da distro, roda o instalador de uma linha

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

O instalador de uma linha assume sistema apt. Ubuntu LTS é a distro testada e Debian funciona

O erro comum deste passo: procurar os arquivos em %LOCALAPPDATA%\hermes depois. Nesse caminho a instalação fica em ~/.hermes, igualzinho ao Linux

Erros comuns do Hermes Agent no Windows e como resolver

Se liga nos que já estão documentados, com sintoma, causa e solução

O comando hermes não é reconhecido:

Sintoma: tu instala, digita hermes e o terminal diz que não conhece o comando

Causa: o instalador escreveu no User PATH, mas o terminal já estava aberto e ficou com o PATH velho

Solução: abrir uma nova janela do PowerShell ou uma nova aba do Windows Terminal. Prevenção: fecha o terminal assim que a instalação terminar, vira hábito

O agent-browser falha com erro de versão do Node:

Sintoma: a ferramenta de navegação reclama da versão do Node

Causa: o instalador provisiona o Node em %LOCALAPPDATA%\hermes\node, mas um Node de sistema mais velho está vindo antes no PATH e ganha a disputa

Solução: mover a pasta node do Hermes pra frente no PATH ou remover o Node do sistema. Prevenção: se tu tem Node antigo instalado de outra época, resolve isso ANTES de sair testando ferramenta por ferramenta

Acentos virando ? no console:

Sintoma: o texto sai com ? no lugar de acento e caractere não ASCII

Causa: o shim UTF-8 do Windows não ativou

Solução: conferir que a variável HERMES_DISABLE_WINDOWS_UTF8 não está definida. Se mesmo assim aparecer ?, o console host antigo (cmd.exe) pode não suportar UTF-8, então migra pro Windows Terminal

Chromium do Playwright ausente:

Sintoma: falta o Chromium pra parte de navegação

Causa: ele é instalado automaticamente no primeiro uso e, quando não está lá, o hermes doctor acusa

Solução: o próprio diagnóstico imprime a correção

npx playwright install chromium

O terminal embutido do dashboard não abre:

Sintoma: a aba /chat do dashboard não sobe o terminal no Windows nativo

Causa: aquele terminal embutido usa PTY POSIX (ptyprocess), primitiva que simplesmente não existe no Windows nativo

Solução: esse recurso é WSL2 only, não tem contorno mágico. O resto do dashboard roda nativo normalmente

Nativo, WSL2 ou Hermes Desktop: qual caminho escolher

Tem três rotas e cada uma serve um perfil diferente

A documentação é bem direta: o Windows nativo não é o recomendado pra automação de produção. Se a tua ideia é deixar agente rodando em cron e recebendo mensagem, a indicação segue sendo WSL2 ou uma máquina Linux, e por aqui já falei sobre usar uma VPS para agentes de IA exatamente por esse motivo

E o Hermes Desktop? É o front-end nativo pra macOS, Windows e Linux, anunciado como public preview em 2 de junho de 2026, junto da versão v0.15.2 do Hermes Agent

Detalhe massa: na primeira execução a GUI chama o mesmo install.ps1 pra provisionar Python (via uv), Node e o Git portátil, e depois o app e a CLI hermes compartilham a mesma instalação em %LOCALAPPDATA%\hermes\hermes-agent, com os dados em %LOCALAPPDATA%\hermes

Ou seja: escolher o Desktop não cria uma segunda instalação paralela pra tu gerenciar

O que percebi usando o Hermes Agent na prática

Aqui vale o disclaimer: quando gravei o vídeo, eu não instalei no Windows

Naquele momento minha leitura era que a ferramenta não rodava direito nesse sistema e que só dava pra fazer contorno improvisado, porque o foco do projeto eram ambientes mais simples de gerenciar. Então eu fui de servidor Linux e acessei tudo pelo terminal do painel da VPS

Na hora de escolher a máquina, peguei um plano com folga em vez do mais básico: o básico aguenta pra testar, o intermediário roda tranquilo. Também desmarquei o pacote pré-instalado que vinha junto, pra começar com a máquina limpa, e escolhi o Brasil como localização

Depois da instalação veio uma surpresa boa: o assistente de configuração abriu sozinho, sem eu disparar nada

Fui de configuração rápida em vez da completa, porque eu queria ver a coisa funcionando logo. Escolhi um roteador de LLMs como provider e colei a chave de API ali

Criei uma chave nova só pra essa ferramenta, com nome, limite de crédito e expiração opcional, e olha o alerta: a chave aparece UMA vez na tela

Evito apontar o agente pras APIs de provedores que estão restringindo esse tipo de uso, então selecionei um modelo gratuito da lista que o próprio setup ofereceu. Pulei a configuração do gateway de mensagens (Telegram) pra deixar pra depois

No fim, a configuração mostrou na tela onde ficam os arquivos principais e alguns comandos de verificação e ajuste, o que já ajuda a não sair perdido

Aí veio a parte divertida. Perguntei pro agente quais ferramentas ele tinha e recebi uma lista com leitura, busca, edição e escrita de arquivos, navegação web, memória e tarefas recorrentes

Pedi uso de disco e memória da máquina e ele executou a checagem na hora, sem enrolação

Numa busca na web o Google bloqueou a requisição e ele simplesmente seguiu pelo Bing, não travou. E quando foi usar curl, avisou que era um comando perigoso antes de executar, o que eu achei topzera pra quem tem medo dos rm -rf da vida 😀

O que eu recomendo mesmo assim: lê a documentação oficial em vez de confiar só em vídeo de YouTuber, incluindo o meu

No vídeo abaixo eu mostro esse fluxo todo em movimento: a contratação da máquina, o assistente de configuração abrindo sozinho, a criação da chave e o agente executando tarefa de verdade no terminal

Próximo passo depois de instalar

Com o hermes respondendo e o provedor configurado, o próximo passo é simples: abre a TUI com hermes --tui, roda hermes doctor uma vez pra limpar pendência de dependência e vê como o agente se comporta na tua máquina

Depois disso é decisão de perfil. Uso pessoal e CLI leve? Segue no nativo, lembrando que ele está em early beta. Automação contínua, gateway e tarefa longa? Migra pro WSL2 ou pra um servidor Linux, que é o caminho recomendado

E fica de olho aqui no Hora de Codar, que conteúdo de agente de IA não vai faltar…

até o próximo post! =)