Hermes Agent on Windows: The Installation That Actually Works (WSL2)
Independent service — not affiliated with Nous Research (publisher of the Hermes Agent software) or Hermès International.
Native Windows support for Hermes Agent is experimental: WSL2 is the real target. This guide covers what comes before the installation itself — enabling WSL2, checking the version, tuning allocated memory — so you don't add one more blocker.
- Why native Windows support isn't enough
- How do you enable WSL2 correctly?
- What if wsl --install fails with a virtualization error?
- Should you tune the memory allocated to WSL2?
- Should you worry about networking between Windows and WSL2?
- Once WSL2 is ready, what's next?
- How do you back up your WSL2 installation before tinkering with the configuration?
- WSL2 or a Linux VPS: which should you choose for serious use?
Want to skip the WSL2 step entirely? We install and host your agent for you.
Why native Windows support isn't enough
Native Windows support for Hermes Agent exists, but the project team itself calls it experimental: certain Python dependencies don't compile cleanly, the Docker sandbox behaves differently, and much of the community simply doesn't test it. WSL2 — Windows' Linux subsystem — is the target that's actually used and tested. That's what we used for the real-world installation described in our 6-pitfalls guide, on August 1, 2026.
This guide doesn't repeat those 6 pitfalls. It covers what comes before them: properly setting up WSL2 itself, so you don't add a seventh source of trouble before you've even run install.sh.
How do you enable WSL2 correctly?
Two commands are all it takes, in a PowerShell window launched as administrator. The first installs WSL2 and Ubuntu by default:
wsl --install
After the requested restart, check the active version — this is the most common mistake at this stage: a distribution still running WSL1 (inherited from an earlier install) instead of WSL2, which silently breaks the Docker sandbox later on.
wsl -l -v
The VERSION column should show 2 for Ubuntu. If it shows 1, convert it with wsl --set-version Ubuntu 2 — expect several minutes, as the operation re-encodes the virtual disk.
What if wsl --install fails with a virtualization error?
On some machines, the command stops with a message about hardware virtualization being unavailable. The cause is almost always the same: virtualization (VT-x on Intel, AMD-V on AMD) is disabled in the motherboard's BIOS or UEFI — a common factory setting on PCs sold with Windows preinstalled, especially in corporate environments.
The check is quick: open Task Manager, go to the Performance tab, and look at the "Virtualization" line. If it says "Disabled," you need to enable it in the BIOS (usually under an "Advanced" or "CPU Configuration" menu — the exact name varies by manufacturer) before re-running wsl --install.
Two Windows features also need to be active — WSL2 doesn't always enable them on its own depending on the Windows version:
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
A restart is required after these two commands.
Should you tune the memory allocated to WSL2?
Yes, almost always. By default, WSL2 allocates up to 50% of the machine's RAM (or 8 GB, whichever is lower) — a setting designed for general-purpose use, not for running an agent, its Docker sandbox, and the web dashboard continuously. On a 16 GB machine, that leaves Hermes Agent fighting the rest of Windows for 8 GB shared between them.
The solution is a .wslconfig file, created in your Windows user folder (C:\Users\YourName\.wslconfig, not inside WSL2 itself):
[wsl2]
memory=6GB
processors=4
Restart WSL2 to apply it (wsl --shutdown from PowerShell, then reopen an Ubuntu terminal). Without this setting, we observed noticeable slowdowns as soon as the Docker sandbox and the dashboard build (see our 6-pitfalls guide, pitfall #3) ran at the same time.
One related detail: processors should not exceed the number of physical cores actually available on your machine, minus one or two reserved for Windows itself. Setting it too high won't crash anything, but WSL2 will then start competing with Windows for cores, producing exactly the slowdown this setting is supposed to prevent.
Should you worry about networking between Windows and WSL2?
On recent versions of Windows 11, WSL2 uses a "mirrored" networking mode by default that greatly simplifies things: a service launched inside Ubuntu on localhost:PORT is directly reachable from a Windows browser at localhost:PORT, with no extra configuration. This is what lets you access Hermes Agent's web dashboard from Windows without any networking work.
On older versions of Windows, or if mirrored mode isn't active, WSL2 runs with its own virtual IP address, different from localhost. In that case, hostname -I from the Ubuntu terminal shows the IP to use from the Windows browser. A common symptom: the dashboard responds fine to curl localhost:PORT from within WSL2 itself, but stays unreachable from the Windows browser — a networking issue, not a Hermes Agent issue.
Common pitfall
The .wslconfig file goes in the Windows user folder, not in WSL2's Linux filesystem. A file created in the wrong location is silently ignored, with no error.Once WSL2 is ready, what's next?
From this point on, the actual Hermes Agent installation follows exactly the path we documented in detail — install.sh, the pitfall of the postinstall script that hangs, the choice between the interactive wizard and hermes config set, the dashboard build that requires Node 22 (Node 18 and Node 20 both fail outright — switching fixes it in 52 seconds; see why npm run build fails on Ubuntu with Node.js if that's the exact error you're hitting), the strict sequence of hermes gateway install then start. We won't repeat them here: our complete 6-pitfalls guide covers them one by one, with the exact error messages.
One Windows-specific point is worth flagging before you dive in: disk performance. If your project or working files live on /mnt/c/... (that is, on the Windows disk mounted inside WSL2), file operations are noticeably slower than on WSL2's native filesystem (~/). The reason is technical but concrete: /mnt/c/ goes through a translation layer between WSL2's Linux kernel and Windows' NTFS filesystem, protocol by protocol. For a simple text file, the difference is invisible. For a Docker sandbox that reads and writes continuously — exactly what Hermes Agent does — it becomes noticeable. Keep ~/.hermes and the cloned code on the native Linux filesystem — not on /mnt/c/.
How do you back up your WSL2 installation before tinkering with the configuration?
Before touching .wslconfig or ~/.hermes/config.yaml, a full backup of the distribution takes just one command. wsl --export generates an archive of the entire Ubuntu filesystem, agent included:
wsl --export Ubuntu ubuntu-backup.tar
If something goes wrong, wsl --unregister Ubuntu followed by wsl --import Ubuntu C:\WSL\Ubuntu ubuntu-backup.tar restores the exact saved state. Expect a few minutes for the export depending on disk size — well worth it the first time a configuration change goes sideways.
If you're only now discovering what Hermes Agent actually is, our complete guide answers the fundamental questions before even getting into installation. And if you're torn between a local install on your Windows machine and a dedicated server, our comparison of VPS plans breaks down both options with real costs.
A poorly tuned WSL2 setup means an extra hour of troubleshooting.
We configure your server ourselves, with the right architecture from the start — you never have to touch WSL2, Docker, or a config file.
Get my agent without configuring it myself →WSL2 or a Linux VPS: which should you choose for serious use?
WSL2 works very well for developing, testing, or running your agent while your PC is on. For serious use — an agent that needs to respond 24/7, even with the PC off — WSL2 isn't the right target: it shuts down with Windows. A dedicated Linux VPS then becomes necessary.
| Criterion | WSL2 (on your PC) | Dedicated Linux VPS |
|---|---|---|
| Availability | Only while the PC is on | 24/7 |
| Direct cost | None (hardware already owned) | Monthly server rental |
| Ideal for | Testing, developing | Real day-to-day use |
| Windows restart | Cuts off the agent | No impact |
If you've made it this far — through .wslconfig, virtualization flags, and /mnt/c/ performance quirks — you're exactly the profile our "Hermes hosted" plan is built for: technical enough to already have (or easily get) your own OpenRouter key, but done fighting a server for something that should just run.
You already have an API key, or you know how to get one.
Bring your own OpenRouter key, and we handle the server, the sandbox, and the uptime — none of what you just read above.
See Hermes hosted, from €12/month →Key takeaways
- Native Windows support is experimental: always install via WSL2.
- Check the VERSION with
wsl -l -v— WSL1 breaks the Docker sandbox without a clear error. - Set memory via a
.wslconfigfile in the Windows user folder, never inside WSL2. - Keep your Hermes Agent files on
~/, not on/mnt/c/— disk performance depends on it. - WSL2 shuts down with Windows: for an agent available continuously, a Linux VPS becomes necessary.
Prefer we handle it for you?
Three no-commitment plans, capped billing — never any overage, no matter what your agent does.
Frequently Asked Questions
Can you install Hermes Agent directly on Windows, without WSL2?
Technically yes, but the project team itself describes this native support as experimental: fragile dependencies, unstable Docker sandbox. WSL2 with Ubuntu is the actually tested and recommended configuration.
How do I check that WSL2 is really active, and not WSL1?
Run wsl -l -v in PowerShell. The VERSION column should show 2 for your Ubuntu distribution. If it shows 1, convert it with wsl --set-version Ubuntu 2.
Why tune the memory allocated to WSL2?
By default, WSL2 shares up to 50% of RAM with Windows, a setting designed for occasional use. For an agent running continuously with its Docker sandbox, a .wslconfig file with a dedicated allocation prevents slowdowns.
Where should I store Hermes Agent's files inside WSL2?
On the native Linux filesystem (~/), never on /mnt/c/. File operations on the mounted Windows disk are noticeably slower from WSL2.
Is WSL2 enough for serious day-to-day professional use?
For testing or development, yes. For an agent that needs to be available 24/7, even with the PC turned off, no: WSL2 shuts down with Windows. A dedicated Linux VPS then becomes necessary.