Instalação do Hermes AI no Windows: Desktop, PowerShell e WSL2

O Hermes Agent oferece suporte ao Windows 10 e ao Windows 11. Os usuários contam com três cenários de implantação: execução nativa via PowerShell, aplicativo gráfico Hermes Desktop ou ambiente WSL2. A escolha do caminho ideal depende das ferramentas de compilação necessárias, dos requisitos de terminal e da arquitetura do sistema de arquivos.

Escolhendo o caminho de instalação: ambiente nativo vs. WSL2

Antes da instalação, é fundamental definir o contexto de execução de suas tarefas:

• PowerShell nativo e Hermes Desktop compartilham a mesma estrutura de dados: o código-fonte e o ambiente virtual ficam em %LOCALAPPDATA%\hermes\hermes-agent, enquanto as configurações de usuário, o histórico de sessões e as habilidades (skills) ficam armazenados em %LOCALAPPDATA%\hermes. O cliente gráfico e a interface de linha de comando (CLI) são intercambiáveis e operam exatamente sobre o mesmo estado.
• WSL2 isola o ambiente dentro de uma máquina virtual Linux e mantém a configuração separada em ~/.hermes.

Exemplos de seleção de arquitetura

1. Projetos focados em Windows (PowerShell / .NET / utilitários do sistema): se você automatiza fluxos de trabalho no host, executa gateways em segundo plano para Telegram ou Discord via Agendador de Tarefas do Windows e manipula arquivos locais no NTFS, escolha o PowerShell nativo ou o Hermes Desktop.
2. Projetos com stack Linux (Docker, Make, scripts POSIX): se o agente precisa compilar binários para Linux, interagir com soquetes UNIX ou gerenciar sessões por meio do terminal integrado no painel web (web dashboard), faça a implantação no WSL2. Na compilação nativa do Windows, o painel web oferece suporte a métricas e configurações, mas a aba de terminal integrado /chat exige um PTY POSIX e está disponível apenas no WSL2.

---

Opção 1: Instalação nativa via PowerShell

O instalador nativo não exige privilégios de administrador e configura automaticamente o gerenciador de pacotes uv, um runtime isolado do Python 3.11, Node.js para ferramentas de automação de navegador e o PortableGit. Não é necessário instalar o Python globalmente no sistema.

Abra um console padrão do PowerShell e execute:

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

O script adiciona %LOCALAPPDATA%\hermes\bin à variável de ambiente PATH do usuário atual. Após a conclusão do script, feche a janela do console e abra uma nova sessão de terminal para aplicar o PATH atualizado. Para consultar parâmetros avançados do script, acesse o guia oficial do Windows Native.

---

Opção 2: Cliente gráfico Hermes Desktop

O Hermes Desktop oferece uma interface em janelas com barra lateral de sessões, grafo visual de habilidades, suporte a abas e gerenciamento de agentes paralelos.

1. Baixe o instalador na página de documentação do Hermes Desktop.
2. Execute o instalador baixado. Na primeira inicialização, o aplicativo executará automaticamente o script de configuração de dependências no diretório %LOCALAPPDATA%\hermes.

Se você já configurou o agente via PowerShell, o aplicativo desktop detectará imediatamente as chaves de API existentes e as conversas salvas.

---

Opção 3: Instalação dentro do WSL2

O WSL2 oferece um ambiente Linux padrão (sistema de arquivos ext4, sinais POSIX, suporte a PTY).

Passo 1. Preparar o WSL2

Em um console do PowerShell com privilégios de administrador (Executar como Administrador), execute:

wsl --install

Reinicie o computador se solicitado pelo sistema e, em seguida, configure seu nome de usuário e senha do Linux. Depois, verifique a versão da distribuição:

wsl --list --verbose

Certifique-se de que a coluna VERSION exiba o valor 2 para a distribuição selecionada (Ubuntu por padrão).

Passo 2. Implantar o Hermes Agent

Abra o terminal do Ubuntu e execute o comando de instalação de acordo com o guia de início rápido do WSL2:

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

Importante: mantenha seus repositórios de trabalho e arquivos de projeto dentro do sistema de arquivos Linux (por exemplo, ~/projects/), e não em um disco montado do Windows (/mnt/c/). Chamadas entre sistemas de arquivos pelo protocolo 9P podem reduzir a velocidade de operações de E/S e deixar a execução do git lenta.

---

Verificação do ambiente e primeira execução

O diagnóstico e a execução devem ser realizados no terminal correspondente a cada ambiente: utilize o PowerShell para a instalação nativa e o Hermes Desktop, e use o terminal do Ubuntu para o WSL2.

Para a instalação nativa e o Hermes Desktop, abra uma nova sessão do PowerShell e execute:

Get-Command hermes
hermes --version
hermes doctor

Para a instalação no WSL2, abra o terminal do Ubuntu e execute o diagnóstico:

command -v hermes
hermes --version
hermes doctor

O comando hermes doctor analisa a resolução de caminhos para o git, o mecanismo de navegador Chromium e as dependências auxiliares.

Antes de iniciar uma sessão de chat, é necessário configurar seu provedor de modelos: se ele ainda não estiver configurado, execute primeiro o comando hermes setup e selecione o provedor (no PowerShell para o ambiente nativo ou no terminal do Ubuntu para o WSL2).

Após a configuração, inicie uma conversa padrão no terminal apropriado e teste-a com uma tarefa que não exija gravação de arquivos; lembre-se de que o hermes chat não inclui isolamento de permissões (sandboxing):

hermes chat

Como primeiro comando, envie uma instrução que não necessite de gravação em disco (como solicitar a explicação de um conceito de arquitetura). O resultado esperado é a inicialização correta do provedor de modelo configurado e a saída de texto contínua (streaming) sem erros de codificação de caracteres.

Para obter detalhes sobre a configuração opcional de modelos individuais, consulte a documentação do BetterToken.

---

Solução de problemas comuns

Sintoma observado	Causa	Solução
hermes: The term 'hermes' is not recognized	A sessão atual do console não recarregou o User PATH atualizado.	Reinicie a janela do PowerShell ou chame o binário diretamente: & "$env:LOCALAPPDATA\hermes\bin\hermes.exe".
A aba /chat no painel web exibe um banner de erro	O Windows nativo não possui o mecanismo de sistema POSIX PTY.	O gerenciamento de sessões e tarefas funciona nativamente, mas para o terminal web em /chat, execute o agente no WSL2.
WinError 193: %1 is not a valid Win32 application	Tentativa de chamar um script diretamente sem o wrapper .cmd.	No Windows, execute ferramentas Node e npm com sua extensão explícita (por exemplo, npx.cmd).
Pontos de interrogação (?) em vez de caracteres Unicode na CLI	Host de console desatualizado sem suporte a CP 65001.	Utilize o Windows Terminal. Certifique-se de que a variável de ambiente HERMES_DISABLE_WINDOWS_UTF8 não esteja definida como 1.
Alta latência durante o git status no WSL2	O diretório de trabalho do projeto está localizado em /mnt/c/....	Mova o repositório para o diretório base do Linux da distribuição (~/code/...) para aproveitar o desempenho nativo do ext4.