Até pouco tempo, muitos tutoriais sobre Hermes Agent no Windows começavam com WSL. Isso mudou. A documentação atual oferece uma instalação nativa para Windows 10 e 11, além do caminho pelo WSL2.
As duas opções são válidas, mas atendem perfis diferentes. O modo nativo simplifica o primeiro contato. O WSL2 aproxima o ambiente de Linux e costuma ser melhor quando o agente vai trabalhar com projetos, ferramentas e scripts pensados para esse ecossistema.
Este guia mostra como instalar o Hermes Agent no Windows, escolher entre nativo e WSL2 e evitar os problemas mais comuns.
O que você precisa
Para instalação nativa:
- Windows 10 ou 11;
- PowerShell;
- acesso à internet;
- uma conta ou chave de um provedor de modelo.
Para WSL2:
- Windows com WSL2 habilitado;
- uma distribuição Linux, como Ubuntu;
- espaço para o ambiente e dependências;
- familiaridade mínima com terminal Linux.
O Hermes pode ser configurado com o portal da Nous ou com provedores compatíveis. Não cole chaves em arquivos do projeto. Use o fluxo de configuração e o armazenamento apropriado.
Opção 1: instalar Hermes Agent no Windows nativo
Abra o PowerShell com seu usuário comum. A documentação oficial apresenta este instalador:
iex (irm https://hermes-agent.nousresearch.com/install.ps1)O instalador coloca os arquivos no perfil do usuário e não deveria exigir privilégios administrativos para o fluxo normal.
Depois, feche e abra o terminal para atualizar o caminho. Verifique:
hermes --versionEm seguida, inicie a configuração:
hermes setup --portalEsse comando conduz o acesso ao portal da Nous. Se preferir outro provedor, use o assistente de configuração correspondente.
Faça um primeiro teste seguro
Crie uma pasta sem dados sensíveis e peça uma tarefa somente de leitura:
mkdir $HOME\hermes-teste
cd $HOME\hermes-teste
hermesNa conversa:
Analise esta pasta, explique o que você consegue acessar e crie um plano de teste. Não execute comandos e não altere arquivos.
O objetivo é entender a experiência e as aprovações antes de entregar um projeto real.
Opção 2: instalar pelo WSL2
WSL2 executa um ambiente Linux dentro do Windows. Ele é interessante para projetos web, ferramentas de terminal, containers e servidores.
Se você ainda não tem WSL, abra PowerShell como administrador e consulte o procedimento atual da Microsoft. Em instalações compatíveis, o ponto de partida costuma ser:
wsl --installReinicie quando solicitado e abra a distribuição Linux.
Dentro do terminal do Ubuntu ou distribuição escolhida, use o instalador Linux da documentação do Hermes:
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bashDepois:
hermes --version
hermes setup --portalOnde colocar seus projetos
Para melhor desempenho com ferramentas Linux, mantenha projetos dentro do sistema de arquivos do WSL, por exemplo:
mkdir -p ~/projetos
cd ~/projetosTrabalhar continuamente sobre /mnt/c/... pode ter diferenças de desempenho e permissões. Use a integração do editor para abrir a pasta do WSL.
Windows nativo ou WSL2?
| Critério | Windows nativo | WSL2 |
|---|---|---|
| primeiro teste | mais direto | exige configurar Linux |
| ferramentas PowerShell | natural | acesso indireto |
| scripts Linux | compatibilidade variável | ambiente adequado |
| projetos que publicam em Linux | pode ter diferenças | mais próximo da produção |
| interface e terminal embutido | algumas limitações podem existir | experiência Linux mais completa |
| arquivos do Windows | acesso direto | disponíveis em /mnt/c |
A documentação de Windows nativo descreve esse suporte como uma frente em evolução. Verifique a matriz atual se você depende de uma ferramenta específica. Tutoriais antigos que afirmam que Hermes não funciona nativamente podem estar desatualizados.
Como usar Hermes em um projeto de vibe coding
Não comece com “termine meu aplicativo”. Dê contexto e peça uma entrega pequena.
Crie um AGENTS.md na raiz com:
- objetivo do projeto;
- stack;
- estrutura;
- comandos de teste;
- convenções;
- áreas proibidas;
- ações que exigem aprovação.
Leia AGENTS.md e analise o fluxo de cadastro deste projeto.
Entregue:
- como o fluxo funciona hoje;
- riscos e casos ausentes;
- arquivos que precisariam mudar;
- plano em etapas;
- testes de aceitação.
Não altere arquivos, não instale dependências, não use credenciais e não publique.
Revise o plano. Depois libere uma etapa de implementação em uma branch ou ambiente de teste.
[ CONTEÚDO_INTEGRAL_DISPONÍVEL ]
Aprenda a criar um AGENTS.md útil para o Hermes CLIQUE PARA DESBLOQUEAR A LEITURA
Construindo aplicações robustas com arquitetura de alto nível e infraestrutura otimizada na edge do Cloudflare Workers com SurrealDB.
Segurança de dados e conformidade com privacidade desde o primeiro dia de código com tratamento de estados e sessões resilientes.
Métricas de performance para monitorar a experiência do usuário e otimizar custos operacionais em produção com dashboards estruturados.
Construindo aplicações robustas com arquitetura de alto nível e infraestrutura otimizada na edge do Cloudflare Workers com SurrealDB.
Segurança de dados e conformidade com privacidade desde o primeiro dia de código com tratamento de estados e sessões resilientes.
Métricas de performance para monitorar a experiência do usuário e otimizar custos operacionais em produção com dashboards estruturados.
Problemas comuns no Windows
hermes não é reconhecido
Feche e reabra PowerShell. Verifique se o diretório de instalação entrou no PATH. Rode:
Get-Command hermesSe o comando não aparecer, consulte a saída do instalador e o guia nativo. Evite baixar executáveis de fontes não oficiais.
Política do PowerShell bloqueia o instalador
Ambientes corporativos podem restringir scripts. Não desative políticas de segurança sem autorização. Use o instalador Desktop, peça orientação ao administrador ou siga o procedimento oficial compatível com sua organização.
O Hermes não encontra uma ferramenta
Confirme se a ferramenta está instalada no mesmo ambiente.
- Hermes nativo vê programas do Windows.
- Hermes no WSL vê programas instalados na distribuição Linux.
Instalar Node no Windows não garante que node exista no WSL, e o inverso também vale.
Permissão ou final de linha quebra scripts
Projetos compartilhados entre Windows e Linux podem ter diferenças de caminho, caixa de letras e CRLF/LF. Mantenha configuração no Git e execute os testes no ambiente alvo.
O projeto ficou lento no WSL
Mova o repositório para ~/projetos dentro do WSL e evite tarefas intensivas sobre a montagem do disco C. Confira também memória e espaço disponíveis.
O agente quer executar comandos perigosos
Mantenha aprovações ativas. Leia o comando e o diretório. Não aprove exclusão, alteração de credenciais, deploy ou banco de produção só porque a solicitação original parecia simples.
A autenticação falha
Execute o diagnóstico oferecido pelo projeto:
hermes doctorNo WSL, rode o mesmo comando dentro do Linux. Verifique rede, relógio do sistema e configuração do provedor sem expor tokens em prints.
Segurança mínima
- use uma pasta de teste;
- mantenha aprovação para comandos sensíveis;
- não execute como administrador sem necessidade;
- use credenciais próprias e revogáveis;
- nunca coloque segredo em
AGENTS.md; - separe ambiente de produção;
- revise mudanças no Git;
- faça backup antes de tarefas amplas;
- prefira leitura no primeiro fluxo;
- limite integrações de mensagens a usuários autorizados.
Se o agente precisa ficar ativo o dia todo, um servidor ou VPS pode ser o próximo passo. Não use o computador pessoal como servidor permanente sem considerar suspensão, atualização e exposição.
Preciso de Docker?
Não para começar. Docker pode ser útil para isolar execução ou reproduzir um ambiente, mas adiciona uma camada. Primeiro confirme que o Hermes, o provedor e uma tarefa pequena funcionam.
Perguntas frequentes
Hermes Agent funciona no Windows sem WSL?
Sim. A documentação atual oferece instalação nativa para Windows 10 e 11. Algumas capacidades podem ter diferenças em relação ao Linux, então confira a matriz oficial.
O que é melhor: nativo ou WSL2?
Nativo é mais simples para começar. WSL2 é geralmente melhor para projetos e ferramentas Linux ou quando a produção também usa Linux.
Posso usar modelos da OpenAI ou Anthropic?
O Hermes suporta diferentes provedores e endpoints. Configure pelo assistente e avalie preço, privacidade e disponibilidade.
Dá para usar no VS Code?
Sim. No WSL, use a integração de desenvolvimento remoto para abrir a pasta Linux. No modo nativo, abra o projeto normalmente no Windows.
Próximo passo
Instale no ambiente que mais se aproxima do seu trabalho, crie uma pasta de teste e entregue ao Hermes uma análise sem permissão de escrita. Quando a saída estiver previsível, avance para uma mudança pequena com testes e revisão.
Velocidade vem depois de contexto e limites. Esse cuidado importa mais no Windows, onde é fácil misturar arquivos pessoais, credenciais e projetos no mesmo ambiente.
