Pular para o conteúdo principal

Documentação oficial desta página · v0.20.6

Windows (WSL2)

O Hermes Agent agora suporta os dois caminhos: Windows nativo e WSL2. Esta página cobre o caminho do WSL2; para a instalação nativa pelo PowerShell, veja o Guia do Windows (Nativo).

Quando escolher o WSL2 em vez do nativo:

  • Você quer usar o terminal embutido do painel (aba /chat) — esse painel exige um PTY POSIX e só existe no WSL2.
  • Você faz desenvolvimento pesado em POSIX e quer que suas sessões do Hermes compartilhem o mesmo sistema de arquivos / os mesmos caminhos que as suas ferramentas de desenvolvimento.
  • Você já tem um ambiente WSL2 e não quer manter uma segunda instalação.

Quando o nativo dá conta (ou é melhor):

  • Chat interativo, gateway (Telegram/Discord/etc.), agendador cron, ferramenta de navegador, servidores MCP e a maior parte dos recursos do Hermes rodam nativamente no Windows.
  • Você não quer pensar em atravessar a fronteira WSL↔Windows toda vez que referenciar um arquivo ou abrir uma URL.

No WSL2 existem, na prática, dois computadores em jogo: o seu host Windows e uma VM Linux gerenciada pelo WSL. A maior parte da confusão vem de não saber em qual dos dois você está a cada momento.

Este guia cobre as partes dessa divisão que afetam o Hermes especificamente: instalar o WSL2, levar arquivos de um lado para o outro entre Windows e Linux, rede nas duas direções e as armadilhas que as pessoas realmente encontram.

简体中文

Um passo a passo em chinês do caminho mínimo de instalação é mantido nesta mesma página — troque pelo menu de idioma (canto superior direito) e escolha 简体中文.

Por que WSL2 (em vez do Windows nativo)​

A instalação nativa do Windows roda direto no Windows: o seu terminal do Windows (PowerShell, Windows Terminal etc.), caminhos do sistema de arquivos do Windows (C:\Users\…) e processos do Windows. O Hermes usa o Git Bash para rodar comandos de shell, que é como o Claude Code e outros agentes lidam com o Windows hoje — isso contorna o abismo POSIX-versus-Windows sem uma reescrita completa.

O WSL2 roda um kernel Linux de verdade numa VM leve, então o Hermes lá dentro é essencialmente idêntico a rodar no Ubuntu. Isso vale muito quando você quer um ambiente POSIX de verdade: fork, /tmp, sockets UNIX, semântica de sinais, terminais com PTY, shells como bash/zsh e ferramentas como rg, git, ffmpeg se comportando do jeito que se comportam no Linux.

Consequências práticas do WSL2:

  • A CLI do Hermes, o gateway, as sessões, a memória, as skills e os runtimes de ferramenta vivem todos dentro da VM Linux.
  • Os programas Windows (navegadores, aplicativos nativos, o Chrome com o seu perfil logado) vivem fora dela.
  • Toda vez que você quiser que os dois conversem — compartilhar arquivos, abrir URLs, controlar o Chrome, acessar um servidor de modelo local, expor o gateway do Hermes para o seu celular — você atravessa uma fronteira. É sobre essas fronteiras que este guia fala.

Instalar o WSL2​

De um PowerShell como administrador ou do Windows Terminal:

wsl --install

Numa máquina nova com Windows 10 22H2+ ou Windows 11, isso instala o kernel do WSL2, o recurso Plataforma de Máquina Virtual e uma distro Ubuntu padrão. Reinicie quando for pedido. Depois do reboot, o Ubuntu abre e pede um nome de usuário + senha do Linux — esse é um usuário Linux novo, sem relação nenhuma com a sua conta do Windows.

Confirme que você está mesmo no WSL2 (e não no WSL1 antigo):

wsl --list --verbose

Você deve ver VERSION 2. Se alguma distro aparecer com VERSION 1, converta:

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

O Hermes não funciona de forma confiável no WSL1 — o WSL1 traduz chamadas de sistema do Linux em tempo real e alguns comportamentos (procfs, sinais, rede) divergem do Linux de verdade.

Escolha da distro​

O Ubuntu (LTS) é o que testamos. O Debian funciona. Arch e NixOS funcionam para quem os quiser, mas o instalador de uma linha assume um sistema derivado do Debian com apt — veja o guia de instalação com Nix para esse caminho.

O gateway do hermes (e qualquer outra coisa que você queira manter no ar) é mais fácil de gerenciar com o systemd. Nas versões modernas do WSL, habilite-o uma vez dentro da sua distro:

sudo tee /etc/wsl.conf >/dev/null <<'EOF'
[boot]
systemd=true

[interop]
enabled=true
appendWindowsPath=true

[automount]
options = "metadata,umask=22,fmask=11"
EOF

Depois, do PowerShell:

wsl --shutdown

Reabra o seu terminal WSL. O comando ps -p 1 -o comm= deve imprimir systemd.

A opção de montagem metadata acima é importante — sem ela, arquivos em /mnt/c/... não conseguem guardar bits reais de permissão do Linux, o que quebra coisas como chmod +x em scripts sob caminhos do Windows.

Instalar o Hermes dentro do WSL​

Com um shell WSL2 aberto:

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

O instalador trata o WSL2 como Linux puro — nada específico de WSL é necessário. Veja Instalação para o layout completo.

Sistema de arquivos: atravessando a fronteira Windows ↔ WSL2​

Essa é a parte que derruba mais gente. São dois sistemas de arquivos, e onde você coloca os seus arquivos importa — para desempenho, para correção e para o que as ferramentas conseguem enxergar.

As duas direções​

DireçãoCaminho lá dentroCaminho que você usa
Disco do Windows, visto do WSLC:\Users\you\Documents/mnt/c/Users/you/Documents
Disco do WSL, visto do Windows/home/you/code\\wsl$\Ubuntu\home\you\code (ou \\wsl.localhost\Ubuntu\... em builds mais novas)

Os dois são reais, os dois funcionam, mas eles não são o mesmo sistema de arquivos — por baixo dos panos, uma ponte com o protocolo de rede 9P liga um ao outro. Isso tem consequências reais de desempenho e de semântica.

Onde colocar o Hermes e os seus projetos​

Regra de bolso: mantenha tudo que é "coisa de Linux" dentro do sistema de arquivos do Linux.

  • A sua instalação do Hermes (~/.hermes/) — lado Linux. O instalador já faz isso.
  • Os seus repositórios git em que você trabalha pelo WSL — lado Linux (~/code/..., ~/projects/...).
  • Seus modelos, datasets, venvs — lado Linux.

O que você ganha seguindo essa regra:

  • E/S rápida. Operações em /mnt/c/... passam pelo 9P e são de 10 a 100× mais lentas que o ext4 nativo. Um git status num repositório de 10 mil arquivos que parece instantâneo em ~/code pode levar mais de 15 segundos em /mnt/c.
  • Permissões corretas. Os bits de permissão do Linux são uma emulação "na medida do possível" em /mnt/c. Coisas como o ssh recusar uma chave com "bad permissions" ou o chmod +x falhar em silêncio são comuns.
  • Observadores de arquivo confiáveis. O inotify através do 9P é instável — observadores de arquivo (servidores de desenvolvimento, executores de teste) perdem mudanças com frequência em /mnt/c.
  • Sem surpresas de maiúsculas e minúsculas. Caminhos do Windows não diferenciam maiúsculas de minúsculas por padrão; o Linux diferencia. Projetos com Readme.md e README.md ao mesmo tempo se comportam de forma diferente dependendo do lado em que você está.

Coloque coisas em /mnt/c só quando você precisar que um arquivo viva do lado do Windows — por exemplo, quando quiser abri-lo por um aplicativo gráfico do Windows, ou quando o DevTools MCP do Chrome do Windows precisar que o diretório atual seja um caminho alcançável pelo Windows.

Levar arquivos de um lado para o outro​

Do Windows → para dentro do WSL: o mais fácil é abrir o Explorer e digitar \\wsl.localhost\Ubuntu na barra de endereço. Daí você pode arrastar e soltar dentro de \home\<você>\.... Ou, do PowerShell:

wsl cp /mnt/c/Users/you/Downloads/arquivo.pdf ~/incoming/

Do WSL → para dentro do Windows: copie para /mnt/c/Users/<você>/... e ele aparece no Windows Explorer na hora:

cp ~/reports/output.pdf /mnt/c/Users/you/Desktop/

Abrir um arquivo do WSL num aplicativo do Windows (editor gráfico, navegador etc.): use explorer.exe ou wslview:

sudo apt install wslu     # uma vez — te dá wslview, wslpath, wslopen etc.
wslview ~/reports/output.pdf    # abre com o programa padrão do Windows
explorer.exe .                  # abre o diretório WSL atual no Windows Explorer

Converter caminhos entre os dois universos:

wslpath -w ~/code/project        # → \\wsl.localhost\Ubuntu\home\you\code\project
wslpath -u 'C:\Users\you'        # → /mnt/c/Users/you

Fim de linha, BOM e git​

Se você editar arquivos do lado do Windows com um editor do Windows, eles podem acabar com fim de linha CRLF. Quando o bash ou o Python do lado Linux os lê, scripts de shell quebram com bad interpreter: /bin/bash^M e o Python pode falhar em arquivos .env com BOM.

A correção é uma configuração de git sensata dentro do WSL (não no Windows):

git config --global core.autocrlf input
git config --global core.eol lf

Para arquivos que já estão com CRLF:

sudo apt install dos2unix
dos2unix caminho/do/script.sh

"Clonar dentro do WSL ou em /mnt/c?"​

Clone dentro do WSL. Sempre, a menos que você tenha um motivo específico para não fazer isso. Um fluxo típico do Hermes (hermes chat, chamadas de ferramenta que rodam rg/ripgrep no repositório, observadores de arquivo, gateway em segundo plano) vai ser dramaticamente mais rápido e mais confiável contra ~/code/meurepo do que contra /mnt/c/Users/you/meurepo.

Uma exceção: pontes MCP que lançam binários do Windows. Se você usa o chrome-devtools-mcp através do cmd.exe (veja Guia de MCP: WSL → Chrome do Windows), o Windows pode reclamar com um aviso de UNC se o diretório de trabalho atual do Hermes for ~. Nesse caso, inicie o Hermes de algum lugar sob /mnt/c/ para que o processo do Windows tenha um cwd com letra de unidade.

Rede: WSL ↔ Windows​

O WSL2 roda numa VM leve com a própria pilha de rede. Isso significa que o localhost dentro do WSL não é o mesmo que o localhost no Windows — do ponto de vista da rede, são duas máquinas separadas. Para cada serviço, você precisa decidir em que direção o tráfego flui e escolher a ponte certa.

Dois casos aparecem o tempo todo.

Caso 1 — o Hermes no WSL conversa com um serviço no Windows​

O mais comum: você está rodando Ollama, LM Studio ou um llama-server no Windows e o Hermes (dentro do WSL) precisa acessá-lo.

O passo a passo canônico para isso vive no guia de provedores: Rede WSL2 para Modelos Locais →

Versão curta:

  • Windows 11 22H2+: ligue o modo de rede espelhada (networkingMode=mirrored em %USERPROFILE%\.wslconfig, depois wsl --shutdown). Aí o localhost funciona nas duas direções.
  • Windows 10 ou builds mais antigas: use o IP do host Windows (o gateway padrão da rede virtual do WSL) e garanta que o servidor no Windows faça bind em 0.0.0.0, e não só em 127.0.0.1. O Firewall do Windows normalmente também precisa de uma regra para a porta.

Para a tabela completa (endereços de bind de Ollama / LM Studio / vLLM / SGLang, regras de firewall em uma linha, auxiliares para IP dinâmico, contorno do firewall do Hyper-V), siga o link acima — não duplique aquilo aqui.

Caso 2 — algo no Windows (ou na sua rede local) conversa com o Hermes no WSL​

Essa é a direção inversa e é menos documentada por aí, mas é o que você precisa para:

  • Usar o painel web do Hermes de um navegador do Windows.
  • Usar o servidor de API compatível com OpenAI (exposto pelo hermes gateway quando API_SERVER_ENABLED=true) de uma ferramenta do lado Windows. Veja a página do recurso Servidor de API.
  • Testar um gateway de mensagens (Telegram, Discord etc.) em que a plataforma chama uma URL de webhook local — normalmente você usaria cloudflared/ngrok em vez de encaminhamento de porta cru.

Subcaso 2a: a partir do próprio host Windows​

No Windows 11 22H2+ com o modo espelhado ligado, não há nada a fazer. Um processo no WSL que faz bind em 0.0.0.0:8080 (ou até em 127.0.0.1:8080) fica alcançável de um navegador do Windows em http://localhost:8080. O WSL publica o bind de volta no host automaticamente.

No modo NAT (Windows 10 / Windows 11 mais antigo), o "encaminhamento de localhost" padrão do WSL2 geralmente encaminha binds em 127.0.0.1 do lado Linux para o localhost do Windows, então um serviço do Hermes iniciado com --host 127.0.0.1 costuma ficar alcançável como http://localhost:PORT a partir do Windows. Se não ficar:

  • Faça bind explicitamente em 0.0.0.0 dentro do WSL.
  • Descubra o IP da VM do WSL com ip -4 addr show eth0 | grep inet e acesse esse endereço a partir do Windows.

Subcaso 2b: a partir de outro aparelho da sua rede local (celular, tablet, outro PC)​

Essa é a dor de verdade. O tráfego flui aparelho da rede → host Windows → VM do WSL, e você precisa montar os dois trechos:

  1. Faça bind em todas as interfaces dentro do WSL. Um processo escutando em 127.0.0.1 nunca vai ser alcançável de fora da VM. Use 0.0.0.0.

  2. Encaminhe a porta do Windows → VM do WSL. No modo espelhado isso é automático. No modo NAT você tem que fazer na mão, porta por porta, num PowerShell como administrador:

    # Pegue o IP atual da VM do WSL (ele muda a cada reinício do WSL sob NAT)
    $wslIp = (wsl hostname -I).Trim().Split(' ')[0]

    # Encaminhe a porta 8080 do Windows → WSL:8080
    netsh interface portproxy add v4tov4 `
      listenaddress=0.0.0.0 listenport=8080 `
      connectaddress=$wslIp connectport=8080

    # Libere no Firewall do Windows
    New-NetFirewallRule -DisplayName "Hermes WSL 8080" `
      -Direction Inbound -Protocol TCP -LocalPort 8080 -Action Allow

    Depois remova com netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=8080.

  3. Aponte o aparelho da rede para http://<ip-do-windows-na-rede>:8080.

Como o IP da VM do WSL muda a cada reinício no modo NAT, uma regra feita uma vez sobrevive só até o próximo wsl --shutdown. Para algo permanente, use o modo espelhado ou coloque o passo do port-proxy num script que roda no login do Windows.

Para webhooks de provedores de mensagem na nuvem (o setWebhook do Telegram, eventos do Slack etc.), não brigue com encaminhamento de porta — use túneis do cloudflared. Veja o guia de webhooks.

Rodar serviços do Hermes a longo prazo no Windows​

O Tool Gateway do Hermes e o servidor de API são processos de vida longa. No WSL2 você tem algumas opções para mantê-los no ar.

Atalho na área de trabalho para abrir o Hermes rapidinho​

Se você só quer um lançador de duplo clique para um shell interativo do Hermes, crie-o do lado do Windows e faça com que ele pule para dentro do WSL por você:

  1. Clique com o botão direito na área de trabalho do Windows e escolha Novo -> Atalho.

  2. Como destino, use o nome da sua distro (troque Ubuntu se for o caso):

    wt.exe -w 0 -p "Ubuntu" wsl.exe -d Ubuntu --cd ~ -- bash -ic "hermes"

  3. Dê a ele um nome óbvio, tipo Hermes.

Isso abre o Windows Terminal, inicia a sua distro WSL, te deixa no seu diretório home do Linux e sobe o Hermes. Se o hermes ainda não estiver no PATH, abra o WSL uma vez na mão e rode source ~/.bashrc, ou troque o comando por uv run hermes dentro do checkout do seu projeto.

Acabamentos opcionais:

  • Ícone personalizado: abra Propriedades -> Alterar Ícone e aponte para um arquivo .ico, como o favicon do Hermes que está no repositório.
  • Lançador fixado: quando o atalho estiver funcionando, fixe-o no Menu Iniciar ou na barra de tarefas para não ter que procurá-lo de novo.

Se você habilitou o systemd conforme a seção de configuração acima, o hermes gateway e o servidor de API funcionam do jeito que funcionam em qualquer máquina Linux. Use o assistente de configuração do gateway:

hermes gateway setup

Ele vai se oferecer para instalar uma unidade de usuário do systemd, para que o gateway suba automaticamente quando o WSL iniciar.

Fazer o próprio WSL iniciar no login do Windows​

A VM do WSL só fica viva enquanto alguma coisa a estiver usando. Para manter o seu gateway alcançável sem deixar uma janela de terminal aberta, suba um processo WSL no login do Windows pelo Agendador de Tarefas:

  • Gatilho: ao fazer logon (o seu usuário).
  • Ação: iniciar um programa
    • Programa: C:\Windows\System32\wsl.exe
    • Argumentos: -d Ubuntu --exec /bin/sh -c "sleep infinity"

Isso mantém a VM viva, de modo que o gateway gerenciado pelo systemd continua rodando. No Windows 11, os fluxos mais novos de wsl --install --no-launch + início automático também funcionam; o truque do sleep infinity é a versão portátil.

Passagem de GPU (modelos locais)​

O WSL2 suporta GPUs NVIDIA nativamente desde o kernel 5.10.43+ do WSL — instale o driver NVIDIA padrão no Windows (não instale um driver NVIDIA de Linux dentro do WSL) e o nvidia-smi dentro do WSL vai enxergar a GPU. A partir daí, toolkits CUDA, torch, vllm, sglang e llama-server compilam contra a GPU real como de costume.

O suporte a AMD ROCm e Intel Arc dentro do WSL2 ainda está evoluindo e está fora da matriz de testes do Hermes — pode funcionar com os drivers atuais, mas não temos uma receita para recomendar.

Se você roda um servidor de modelo local nativo do Windows (Ollama para Windows, LM Studio) que já usa a sua GPU pelos drivers do Windows, você não precisa de passagem de GPU no WSL — basta seguir o Caso 1 acima e acessá-lo pela rede a partir do WSL.

Armadilhas comuns​

"Connection refused" ao meu Ollama / LM Studio hospedado no Windows. Veja Rede WSL2. Em noventa por cento das vezes o servidor está com bind em 127.0.0.1 e precisa de 0.0.0.0 (no Ollama: OLLAMA_HOST=0.0.0.0), ou está faltando uma regra de firewall.

Lentidão absurda no git status / hermes chat dentro de um repositório. Você provavelmente está trabalhando sob /mnt/c/.... Mova o repositório para ~/code/... (lado Linux). Uma ordem de grandeza mais rápido.

bad interpreter: /bin/bash^M em scripts. Fim de linha CRLF vindo de um editor do Windows. Rode dos2unix script.sh e configure core.autocrlf input no git do seu WSL.

Aviso "UNC paths are not supported" de binários do Windows lançados via MCP. O cwd do Hermes está dentro do sistema de arquivos do Linux, e o cmd.exe do Windows não sabe o que fazer com ele. Inicie o Hermes de /mnt/c/... naquela sessão, ou use um wrapper que faça cd para um caminho alcançável pelo Windows antes de invocar o executável do Windows.

Relógio desregulado depois de suspender/hibernar. O relógio do WSL2 pode atrasar minutos depois que o host volta do sono, o que quebra qualquer coisa baseada em certificado (OAuth, APIs HTTPS). Corrija na hora:

sudo hwclock -s

Ou instale o ntpdate e rode-o no login.

O DNS para de funcionar depois de ligar o modo espelhado, ou quando uma VPN está conectada. O modo espelhado espelha as configurações de rede do host para dentro do WSL — se o DNS do Windows estiver estranho (VPN com split-tunnel, resolvedor corporativo), o WSL herda isso. Contorno: sobrescreva o resolv.conf na mão (defina generateResolvConf=false em /etc/wsl.conf e escreva o seu próprio /etc/resolv.conf com 1.1.1.1 ou com o DNS da sua VPN).

hermes não encontrado depois de rodar o instalador. O instalador acrescenta ~/.local/bin ao PATH do seu shell via ~/.bashrc. Você precisa rodar source ~/.bashrc (ou abrir um terminal novo) para que isso valha na sessão atual.

O Windows Defender fica lento com arquivos do WSL. O Defender escaneia arquivos pela ponte 9P quando eles são acessados do Windows, o que amplifica a lentidão do acesso cruzando a fronteira ao estilo /mnt/c. Se você só toca em arquivos do WSL de dentro do WSL, isso não importa. Se você usa ferramentas do Windows contra \\wsl$\... com frequência, considere excluir o caminho da distro WSL do escaneamento em tempo real.

Ficando sem espaço em disco. O WSL2 guarda o disco da VM como um VHDX esparso sob %LOCALAPPDATA%\Packages\.... Ele cresce, mas não encolhe sozinho quando você apaga arquivos. Para recuperar espaço: rode wsl --shutdown e, de um PowerShell como administrador, Optimize-VHD -Path <caminho-do-ext4.vhdx> -Mode Full (exige as ferramentas do Hyper-V) — ou o caminho mais simples com diskpart, documentado na documentação do WSL.

Para onde ir agora​