Hermes Agent
Hermes Agent on Windows: native or WSL2
Updated 20 November 2026
There are two ways to run Hermes Agent on a Windows PC: natively in PowerShell, or inside a Linux environment called WSL2. Both are documented, and they can sit side by side on the same machine. This page gives the install command for each, where the data goes, how they differ, and what to do when something fails.
Facts come from the Hermes Agent 0.23.3 documentation, mainly its Windows (Native) guide and Windows (WSL2) guide, plus its Installation and Platform Support pages, all read on 20 November 2026.
Two ways to run Hermes on Windows
The 0.23.3 documentation describes both routes, and its Platform Support page lists Windows 10 and 11 (x86_64 and aarch64) and Linux with WSL2 among the platforms it works hardest to keep working.
- Native Windows. Hermes runs directly on Windows 10 or 11, with no WSL, Cygwin or Docker. You use PowerShell or Windows Terminal, and Windows paths such as
C:\Users\. To run shell commands, Hermes’s terminal tool uses Git Bash. - WSL2. WSL2 runs a real Linux kernel in a lightweight virtual machine. Hermes inside it is, in the guide’s words, essentially identical to running on Ubuntu. The CLI, gateway, sessions, memory and skills all live inside that Linux VM, while your Windows browser and apps live outside it.
The native guide says both coexist cleanly. The desktop app is a separate thing with its own page, Hermes Agent desktop app; this page is about the command-line install.
Install commands
For native Windows, open PowerShell (or Windows Terminal) and run the line from the native guide:
iex (irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1)The Installation page writes the same command with a different address: iex (irm https://hermes-agent.nousresearch.com/install.ps1). No admin rights are needed. The installer goes to %LOCALAPPDATA%\hermes\ and adds hermes to your User PATH, so open a new terminal when it finishes. To pass options, the native guide uses a scriptblock:
& ([scriptblock]::Create((irm https://hermes-agent.nousresearch.com/install.ps1))) -NonInteractive -Channel mainThat page lists -Channel stable|main (stable is the default), -HermesHome PATH, -InstallDir PATH, -NonInteractive, -IncludeDesktop and -ShowResolvedPaths, among others.
For WSL2, first install WSL from an Admin PowerShell, reboot when prompted, and confirm the distro is version 2:
wsl --installwsl --list --verboseIf a distro shows VERSION 1, the guide converts it with wsl --set-version Ubuntu 2 and wsl --set-default-version 2, and says Hermes does not work reliably on WSL1. Ubuntu LTS is what the docs test against; Debian works. Then, in the WSL shell, install Hermes like on any Linux machine:
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bashThen run source ~/.bashrc and hermes. The WSL guide says the installer treats WSL2 as plain Linux. For the general install flow and first-run setup, see how to install Hermes Agent.
Where data lives in each
| Item | Native Windows | WSL2 |
|---|---|---|
| Data and config | %LOCALAPPDATA%\hermes | ~/.hermes/ |
| Source checkout | %LOCALAPPDATA%\hermes\hermes-agent\ | ~/.hermes/hermes-agent/ |
| Command launchers | %LOCALAPPDATA%\hermes\bin\ | ~/.local/bin/hermes |
| API keys file | %LOCALAPPDATA%\hermes\.env | the .env in your Hermes data directory |
These are defaults. HERMES_HOME and the installer’s -HermesHome and -InstallDir options can move them. The two installs do not share data, so a native Hermes and a WSL Hermes are two separate agents with their own sessions and keys. The WSL guide also covers reaching files across the boundary: from Windows, the WSL disk appears at \\wsl.localhost\Ubuntu, and from WSL your C: drive is at /mnt/c/.
Keep Hermes and your projects on the Linux side in WSL. The guide says work on /mnt/c goes through a slower bridge and can cause permission and file-watcher problems. Uninstalling is covered on the uninstall page; the native guide warns against deleting the whole data folder to repair an install, because that also deletes your data.
Native or WSL2: what differs and how to choose
The native guide’s feature table marks the CLI, the interactive TUI, the messaging gateway, cron, the browser tool, MCP servers, local model servers, the web dashboard and login auto-start as working in both. The remaining differences:
| Topic | Native Windows | WSL2 |
|---|---|---|
| Shell and paths | PowerShell, Windows paths, Git Bash for shell commands | Real Linux: bash, POSIX paths, /tmp, sockets, signals |
Dashboard /chat terminal pane | ConPTY through pywinpty | POSIX PTY |
| Gateway at login | Scheduled Task (schtasks), Startup-folder fallback | systemd, plus a Task Scheduler step to keep WSL alive |
| Local Ollama or LM Studio | Works | Works through WSL networking |
| Extra setup | Source builds can need a native compiler and platform development libraries | WSL itself, a distro, optionally systemd |
The two guides disagree slightly on the dashboard terminal. The WSL guide says the embedded terminal pane is WSL2-only, while the native guide says it works through pywinpty and that a missing or broken native dependency can make it unavailable, so WSL is an alternative, not a requirement. We follow the native guide, which is the more specific.
Limits the native guide lists:
- Matrix’s native encrypted adapter is Linux-only.
- Native Windows ARM64 excludes the
google-chatSDK extra and the openWakeWord engine, and local Faster-Whisper speech-to-text is excluded there too.
How to choose, from the WSL guide’s own reasoning:
- Pick WSL2 if you want a POSIX environment, want Hermes to share paths with your Linux dev tools, or already have a WSL2 setup you do not want to duplicate.
- Pick native if you mainly want chat, the gateway, cron, the browser tool and MCP servers, and do not want to think about crossing the WSL and Windows boundary for files and URLs.
Keeping the gateway running in the background
The gateway is the process that connects Hermes to chat apps such as Telegram, so it needs to stay up after you close the terminal. How depends on the route.
Native. Run hermes gateway install in PowerShell. The native guide says it registers a Scheduled Task named Hermes_Gateway that starts at your login with standard permissions (UAC is asked once to register it), and that if group policy blocks Scheduled Tasks it falls back to a hidden launcher in the Startup folder. It starts the gateway detached, with no console window. Manage it with:
hermes gateway status
hermes gateway start
hermes gateway stop
hermes gateway restart
hermes gateway uninstallThe guide explains why it uses a Scheduled Task and not a Windows Service: a service needs admin rights and ties the gateway to machine boot, while a task runs at your login and ends when you log out. So the gateway is up while you are signed in to Windows, not while the PC is off or you are signed out.
WSL2. Enable systemd in /etc/wsl.conf (the guide sets systemd=true under [boot]), run wsl --shutdown from PowerShell, reopen WSL, and run:
hermes gateway setupIt offers to install a systemd user unit so the gateway comes up when WSL starts. The guide adds that WSL’s VM only stays alive while something uses it, so to keep the gateway reachable without a terminal open, create a Task Scheduler task that runs at logon with C:\Windows\System32\wsl.exe and the arguments -d Ubuntu --exec /bin/sh -c "sleep infinity".
In both cases the gateway runs on your PC. It cannot stay available while the PC is asleep or shut down, and chat-app connections need network access. That is the main practical limit of a Windows install for an always-on assistant.
WSL2 networking notes
In WSL2, localhost inside Linux is not the same as localhost on Windows. The guide covers two directions.
- Hermes in WSL reaching a model server on Windows (Ollama, LM Studio, llama-server). On Windows 11 22H2 or later, set
networkingMode=mirroredin%USERPROFILE%\.wslconfig, then runwsl --shutdown;localhostthen works both ways. On Windows 10 or older builds, use the Windows host address and make the server bind to0.0.0.0, not only127.0.0.1; a firewall rule is usually needed too. For Ollama the guide namesOLLAMA_HOST=0.0.0.0. See Hermes Agent with Ollama for the model side. - Windows or another device reaching Hermes in WSL (the dashboard, or the API server when
API_SERVER_ENABLED=true). With mirrored mode, a process in WSL listening on0.0.0.0:8080or127.0.0.1:8080is reachable athttp://localhost:8080from a Windows browser; 8080 is an example, so use the port your service actually listens on. In NAT mode the default localhost forwarding usually works from the host itself; if not, bind to0.0.0.0or use the VM’s address. For access from a phone or another PC on your LAN, the service inside WSL must listen on0.0.0.0. In NAT mode you also need a Windows-to-WSL port forward and a Windows Firewall rule, and the VM address changes on each WSL restart.
For chat-app webhooks the guide advises a tunnel such as cloudflared rather than raw port forwarding. Our page on the Hermes Agent dashboard covers the dashboard itself.
Windows-specific errors and fixes
| What you see | What the docs say to do |
|---|---|
hermes not found right after a native install | Open a new PowerShell window so the User PATH change applies. Meanwhile run & "$env:LOCALAPPDATA\hermes\bin\hermes.exe". Check with Get-Command hermes. |
hermes not found after a WSL install | Run source ~/.bashrc or open a new terminal. |
WinError 193 when a tool runs | A command bypassed the .cmd shim. Use the .cmd variant, for example npx.cmd. |
| Scriptblock install fails with a message that the assignment expression is not valid | The download picked up a UTF-8 BOM. Use the plain irm | iex form, which strips it. |
| Gateway will not stay running after a restart | Run hermes gateway status. If the task is registered but not running, group policy may block logon triggers; schtasks /Query /TN Hermes_Gateway /V /FO LIST shows the failure reason. |
/edit or Ctrl-X Ctrl-E does nothing | Hermes defaults EDITOR to notepad. If you set your own, set it at User scope or in your PowerShell profile and reopen the shell; for VS Code use code --wait. |
| Chinese, Japanese or Arabic text shows as question marks | Check that HERMES_DISABLE_WINDOWS_UTF8 is not set. If it is empty and the problem stays, the console host may lack UTF-8 support; use Windows Terminal. |
| Browser tool launches but times out | Run hermes doctor and hermes pm doctor, and raise browser.command_timeout for a slow first Chromium start. See Hermes Agent browser. |
WSL: bad interpreter: /bin/bash^M | Windows line endings. Run dos2unix script.sh and set git config --global core.autocrlf input inside WSL. |
| WSL: very slow git or chat in a repo | The repo is probably under /mnt/c. Move it to the Linux side, such as ~/code. |
| WSL: clock drift after sleep breaks HTTPS or OAuth | Run sudo hwclock -s. |
| WSL: DNS fails with mirrored mode or a VPN | Set generateResolvConf=false in /etc/wsl.conf and write your own /etc/resolv.conf. |
One more caution from the native guide: a file saved with a byte-order mark inside a folded YAML value such as description: > can silently break parsing, so save config and skill files as plain UTF-8 without BOM. Skills are explained on the Hermes Agent skills page.
Skipping the install: ReadyHermes
A ReadyHermes assistant runs on our servers, so nothing is installed on your PC, and it keeps working when the computer is asleep or off. You use it from a browser and from the chat apps you connect (Telegram, WhatsApp, Discord, WeChat and Lark). There is no Windows-specific ReadyHermes app, and no PowerShell, WSL or Scheduled Task to manage.
Plans start at US$3.99 a month (Lite) or US$6.99 (Pro), with US$1 of AI included every month and a 1-hour free trial. To weigh running it yourself against hosting, see self-hosting vs managed hosting.
Questions
Does Hermes Agent run natively on Windows?
Yes. The Hermes Agent 0.23.3 documentation says it runs natively on Windows 10 and 11 with no WSL, Cygwin or Docker. You install it from PowerShell with the install.ps1 script, and it goes to %LOCALAPPDATA%\hermes without admin rights.
What is the install command for Hermes Agent on Windows?
In PowerShell, the native guide gives: iex (irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1). The Installation page writes the same command with https://hermes-agent.nousresearch.com/install.ps1. Open a new terminal afterwards so the PATH change applies.
Should I use WSL2 or native Windows for Hermes?
Both work. The WSL2 guide suggests WSL2 if you want a POSIX environment, shared paths with Linux dev tools, or already use WSL2. Native is fine for chat, the gateway, cron, the browser tool and MCP servers, without crossing the WSL and Windows file boundary.
How do I keep the Hermes gateway running on Windows?
Natively, run hermes gateway install, which registers a Scheduled Task named Hermes_Gateway that starts at your login. In WSL2, enable systemd, run hermes gateway setup, and add a Task Scheduler task that keeps WSL alive. Either way it runs on your PC, so it is not available while the PC is off.
Do I need to install anything on Windows to use ReadyHermes?
No. A ReadyHermes assistant runs on our servers and is used from a browser and the chat apps you connect, so nothing is installed on your PC and it keeps working when the computer is asleep or off. Plans start at US$3.99 a month with a 1-hour free trial.