Hermes Agent on Windows (WSL2 Complete Guide)

Why Windows needs WSL2

You might think: Hermes is just Python + Node, Windows can run those — why WSL2?

• Hermes uses Unix-style paths heavily (~/.hermes, /usr/local/bin). Windows path escaping inside Python subprocess calls is fragile.
• Most low-level Skill helpers (git, ripgrep, fd, etc.) are wrapped via Bash; Windows cmd/PowerShell are not interchangeable.
• Terminal ANSI/progress-bar rendering is fine in Windows Terminal, but the readline library Hermes uses is unstable on native Windows.
• TL;DR: it might work, but in practice ~60% of common Skills hit weird issues. WSL2 gives you a clean Linux environment identical to what Mac/Linux users have.

WSL2 is not a VM — it is a lightweight Linux subsystem in the Windows kernel: 1-second boot, shared filesystem with Windows. Set up once, lasts forever.

Install WSL2 (Win10/Win11)

Open PowerShell as Administrator (Win+X → Terminal (Admin)), then run:

wsl --install -d Ubuntu-22.04

1. 1. Reboot

   After the command finishes Windows asks to reboot. After reboot the Ubuntu terminal opens automatically and prompts for a Linux username + password (separate from your Windows account).

2. 2. Verify WSL2

   In PowerShell, run wsl -l -v. You should see Ubuntu-22.04 with state Running and VERSION 2. If it shows 1, run wsl --set-version Ubuntu-22.04 2 to upgrade.

3. 3. Update the system

   Inside Ubuntu: sudo apt update && sudo apt upgrade -y, then sudo apt install -y curl git build-essential for the basics.

You now have a complete Linux environment. From here, Hermes installs the same way as Mac/Linux.

Install Hermes inside WSL Ubuntu

In the Ubuntu terminal (Start menu → Ubuntu, or wsl from PowerShell), run the official one-liner.

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

• Install location: ~/.hermes inside WSL Ubuntu (visible from Windows at \\wsl$\Ubuntu-22.04\home\<user>\.hermes)
• Open a fresh terminal or run source ~/.bashrc to load PATH
• Verify: hermes --version should print a version string
• Then run hermes doctor for the 12-check self-test

Provider config and Skill installation are covered in /en/install.

VS Code Remote-WSL workflow

Recommended setup: VS Code on Windows + Remote-WSL extension to work inside WSL. You keep the Windows GUI but all terminals and file operations live in Linux.

1. 1. Install VS Code on Windows

   From https://code.visualstudio.com/. During setup, check "Add to PATH".

2. 2. Install Remote - WSL extension

   In VS Code, Ctrl+Shift+X opens the extensions panel. Search "Remote - WSL" (Microsoft, official), click Install.

3. 3. Open a project from the WSL terminal

   cd to your project directory in WSL Ubuntu, then code . — VS Code attaches to WSL and opens the directory. Bottom-left shows green "WSL: Ubuntu".

4. 4. Built-in terminal uses WSL Bash

   The integrated terminal in VS Code defaults to WSL Bash. Run hermes commands there with full ANSI color and progress-bar support.

Network and proxy setup

On restricted networks you may need a proxy to install Skills (GitHub raw + some LLM provider domains). WSL2 does not inherit Windows proxy settings — configure manually.

• Prereq: a proxy is running on the Windows host (e.g. Clash on port 7890)
• Find the Windows host IP from inside WSL: cat /etc/resolv.conf and read the nameserver line
• Append to ~/.bashrc: export HTTPS_PROXY="http://<that-IP>:7890" and HTTP_PROXY similarly
• Reload: source ~/.bashrc
• Verify: curl -I https://www.google.com should return 200

Then run hermes skills sync to pull the Skills registry. If you do not want a global proxy, set skills.proxy in hermes config to scope it to Hermes only.

8 common WSL errors

Most WSL2 + Hermes install issues come from one of these eight buckets. Match the symptom and apply the fix.

• WslRegisterDistribution failed with error: 0x800701bc

  原因 / Cause: WSL2 kernel missing or outdated.

  修复 / Fix: In PowerShell run wsl --update. If it still fails, download the WSL2 Linux kernel update package from Microsoft and install manually.

• "wsl --install" command not found

  原因 / Cause: Win10 below 21H2; wsl --install was added in 21H2.

  修复 / Fix: Old flow: in "Turn Windows features on or off" enable Hyper-V, Virtual Machine Platform, and Windows Subsystem for Linux. Reboot and install Ubuntu from Microsoft Store.

• Ubuntu hangs at "Installing, this may take a few minutes"

  原因 / Cause: C: drive low on space, or Hyper-V/virtualization disabled.

  修复 / Fix: Free at least 5 GB on C:. In BIOS, enable VT-x (Intel) or SVM (AMD).

• install.sh hangs at "Installing Python deps" inside WSL

  原因 / Cause: WSL2 inherits DNS from Windows host; pypi.org sometimes flakes on certain networks.

  修复 / Fix: echo "[network]\ngenerateResolvConf = false" | sudo tee /etc/wsl.conf, then wsl --shutdown in PowerShell, then sudo nano /etc/resolv.conf and set nameserver 8.8.8.8.

• hermes works in VS Code terminal but not Windows Terminal

  原因 / Cause: Windows Terminal default profile is not WSL.

  修复 / Fix: Open Windows Terminal settings (Ctrl+,) and set Default profile to Ubuntu-22.04.

• Filesystem operations on /mnt/d/... are very slow

  原因 / Cause: Cross-drive access uses the 9P protocol, ~10x slower than native ext4.

  修复 / Fix: Move your projects from Windows D: to ~/projects inside WSL. Access from Windows side via \\wsl$\Ubuntu-22.04\home\<user>\projects.

• ANSI colors render as garbage in Windows Terminal

  原因 / Cause: Font does not include Powerline / Nerd Font glyphs.

  修复 / Fix: Install a Nerd Font (recommended: JetBrainsMono Nerd Font), then change the Ubuntu profile font in Windows Terminal settings.

• WSL2 memory usage keeps growing

  原因 / Cause: WSL2 does not aggressively release memory back to Windows.

  修复 / Fix: Create %USERPROFILE%\.wslconfig with: [wsl2]\nmemory=4GB\nswap=2GB. Save and run wsl --shutdown.