# Hermes Agent no Windows: instalação nativa, WSL2 e problemas comuns > Instale Hermes Agent no Windows 10 ou 11, compare o modo nativo com WSL2 e resolva PATH, ferramentas, permissões, desempenho e autenticação. **Autores:** Mauro Mequelussi **Publicado:** 2026-08-04T12:00:00.000Z **Atualizado:** 2026-08-04T12:00:29.157359029Z **Tags:** hermes-agent, agentes-de-ia, tutorial, windows, wsl2, vibe-coding --- 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. ::callout{type="info" title="Qual caminho escolher?"} Use Windows nativo para experimentar o Hermes rapidamente e trabalhar com arquivos e ferramentas do Windows. Use WSL2 quando seu projeto já roda em Linux, depende de utilitários Unix ou será publicado em um servidor Linux. :: ## 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: ```powershell 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: ```powershell hermes --version ``` Em seguida, inicie a configuração: ```powershell hermes setup --portal ``` Esse 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: ```powershell mkdir $HOME\hermes-teste cd $HOME\hermes-teste hermes ``` Na 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: ```powershell wsl --install ``` Reinicie 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: ```bash curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash ``` Depois: ```bash hermes --version hermes setup --portal ``` ### Onde colocar seus projetos Para melhor desempenho com ferramentas Linux, mantenha projetos dentro do sistema de arquivos do WSL, por exemplo: ```bash mkdir -p ~/projetos cd ~/projetos ``` Trabalhar 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. ::prompt-snippet{title="Primeira tarefa no Windows" model="Hermes Agent"} Leia AGENTS.md e analise o fluxo de cadastro deste projeto. Entregue: 1. como o fluxo funciona hoje; 2. riscos e casos ausentes; 3. arquivos que precisariam mudar; 4. plano em etapas; 5. 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. ::read-more{slug="hermes-agent-vibe-coding-agents-md" label="Aprenda a criar um AGENTS.md útil para o Hermes" placement="mid_content"} ## Problemas comuns no Windows ### `hermes` não é reconhecido Feche e reabra PowerShell. Verifique se o diretório de instalação entrou no `PATH`. Rode: ```powershell Get-Command hermes ``` Se 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: ```powershell hermes doctor ``` No 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. ### Fontes e leitura recomendada - [Hermes Agent: documentação oficial](https://hermes-agent.nousresearch.com/docs/) - [Hermes Agent: Windows nativo](https://github.com/NousResearch/hermes-agent/blob/main/website/docs/user-guide/windows-native.md) - [Hermes Agent: guia WSL2](https://github.com/NousResearch/hermes-agent/blob/main/website/docs/user-guide/windows-wsl-quickstart.md) - [Microsoft: instalar WSL](https://learn.microsoft.com/windows/wsl/install) - [Hermes Agent: segurança](https://hermes-agent.nousresearch.com/docs/user-guide/security/)