Windows installation Independent guide
Install Hermes Agent on Windows
Decide between native Windows and WSL2, install with the documented PowerShell command, and verify the runtime on Windows paths.
Install Hermes Agent natively on Windows 10 or 11 with the documented PowerShell one-liner — no administrator rights required. Choose WSL2 instead only if you need the dashboard's embedded terminal pane or you already work Linux-first; that pane is the one documented feature unavailable on native Windows.
Checked against Hermes Agent v0.20.5 on . Re-check when the Windows installer URL, the install paths under %LOCALAPPDATA%, or the documented native-Windows limitation changes.
Choose native Windows or WSL
Decide once, up front. Both are supported; they differ in what they cost you and what they unlock.
| Option | Choose it when | Setup cost | Known gap |
|---|---|---|---|
| Native Windows | You want the shortest path and work primarily in Windows tools | One PowerShell command, no admin rights | The dashboard's embedded terminal pane in /chat is unavailable — it needs a POSIX PTY |
| WSL2 | You need that terminal pane, or your development work is already Linux-shaped | Install and enable WSL2, ideally with systemd, then run the Linux installer | Windows-side files under /mnt/c are slow; keep work on the Linux filesystem |
Source: Nous Research Windows Native guide and Windows WSL2 quickstart, checked 25 August 2026 against v0.20.5.
Everything else — the CLI, the TUI, messaging gateways, the browser tool, cron scheduling, and the dashboard apart from that pane — is documented as working natively.
Windows prerequisites
- Windows 10 or 11, on x86_64 or aarch64.
- PowerShell or Windows Terminal. Administrator rights are not required.
- Nothing else installed in advance. The installer bootstraps
uv, installs Python 3.11, installs Node.js 26, and provisions a portable Git (about 45 MB) if Git is not already onPATH.
If you are taking the WSL2 route instead, install WSL2 first from an administrator PowerShell:
wsl --installExpected result: WSL2 and a default Linux distribution are installed; a reboot is typically required.
Source: Nous Research Windows WSL2 quickstart, checked 25 August 2026
wsl --list --verboseExpected result: A table of installed distributions. The VERSION column must read 2; if it reads 1, convert it with wsl --set-version followed by the distribution name and the number 2.
Source: Nous Research Windows WSL2 quickstart, checked 25 August 2026
Install on Windows
iex (irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1)Expected result: Dependencies are provisioned, the repository is cloned to %LOCALAPPDATA%\hermes\hermes-agent\, a virtual environment is created, and the setup wizard runs.
This downloads and executes a remote script in memory. Windows SmartScreen may prompt on first run. If your environment requires review before execution, save the script, read it, then run it.
Source: Nous Research Windows Native guide, checked 25 August 2026
The Nous Research installation page documents the shorter equivalent
iex (irm https://hermes-agent.nousresearch.com/install.ps1). Both appear in current official documentation; use
whichever your environment permits.
Inside WSL2, use the Linux installer instead:
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bashExpected result: The installer provisions dependencies inside the WSL2 distribution and installs the `hermes` command there.
Source: Nous Research Windows WSL2 quickstart, checked 25 August 2026
Optional installer parameters (native Windows)
The Windows installer accepts -Branch to clone a specific branch, -NoVenv to skip virtual-environment creation,
and -SkipSetup to skip the setup wizard. They are passed by creating a script block from the downloaded script
rather than piping it directly. Source: Nous Research Windows Native guide, checked 25 August 2026.
Configure PATH and dependencies
The installer writes to a per-user location and updates your user PATH:
- Code:
%LOCALAPPDATA%\hermes\hermes-agent\ - Data, and the value of
HERMES_HOME:%LOCALAPPDATA%\hermes\ - Executables:
%LOCALAPPDATA%\hermes\bin\ - Provisioned Git and Node.js, when installed:
%LOCALAPPDATA%\hermes\git\and%LOCALAPPDATA%\hermes\node\
Because HERMES_HOME points at %LOCALAPPDATA%\hermes\ and only the hermes-agent\ subdirectory is replaced on
reinstall, your configuration and data survive a reinstall.
Verify Hermes Agent
Get-Command hermesExpected result: The resolved path to the hermes executable under %LOCALAPPDATA%\hermes\bin\.
Source: Nous Research Windows Native guide, checked 25 August 2026
hermes --versionExpected result: A version string. If this fails in a new terminal, the PATH entry was not written.
Source: Nous Research Windows Native guide, checked 25 August 2026
Inside WSL2, verify with hermes --version in the WSL shell, and confirm systemd is running with
ps -p 1 -o comm=, which should print systemd.
Connect a provider
Installation does not connect a model. Run the provider picker, or wire up Nous Portal directly:
hermes setup --portalExpected result: Nous Portal is set as the provider through an OAuth login and the Tool Gateway is enabled.
Source: Nous Research Windows Native guide and Nous Portal integration, checked 25 August 2026
Any other provider path — hosted APIs, local endpoints, credential placement — is a separate decision covered by the models and providers guide.
Handle Windows security prompts
- SmartScreen may warn the first time a downloaded script runs. That warning is expected for remotely fetched
installers; verify the URL is the Nous Research domain or the
NousResearch/hermes-agentrepository before continuing. - Execution policy. The documented one-liner form handles PowerShell's execution requirements without manual policy changes. If you save the script to disk instead, your organisation's policy applies.
- Corporate managed devices may block user-scope installs entirely. That is a policy failure, not a Hermes Agent
failure — the installer needs to write to
%LOCALAPPDATA%.
Fix common Windows failures
| Symptom | Suspect component | Check | Expected result | If it still fails |
|---|---|---|---|---|
| hermes: command not found | User PATH in the current shell | Open a new PowerShell window and run Get-Command hermes | A path under %LOCALAPPDATA%\hermes\bin\ | Confirm the installer completed without error, then reinstall |
| WinError 193: %1 is not a valid Win32 application | Node tooling invoked without its Windows shim | Call the .cmd variant, for example npx.cmd instead of npx | The command runs | Report the calling tool with the exact command in a Windows issue |
| Non-ASCII characters render as ? | Console encoding | Confirm HERMES_DISABLE_WINDOWS_UTF8 is not set | Unicode output renders correctly | Use Windows Terminal rather than the legacy console host |
| [scriptblock]::Create(...) fails with an invalid assignment | Downloaded script picked up a UTF-8 byte-order mark | Re-run using the plain irm | iex form | The installer runs | Save the script and strip the BOM before executing |
| Browser tool times out | Chromium provisioning | Run hermes doctor | The browser backend reports as available | Reinstall the browser with npx playwright install chromium |
Source: Nous Research Windows Native guide, checked 25 August 2026 against v0.20.5.
Anything not on this list — provider errors, configuration errors, gateway failures — is not Windows-specific. Take it to Windows install troubleshooting, which diagnoses by component rather than by platform.
Continue setup
Installation is done when hermes --version works in a fresh terminal. To reach a verified first result, including
provider connection, safe defaults, and output verification, continue setup.