iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
Antihost offers VPS plans with one-click Hermes Agent, NVMe storage and a 14-day free trial.
Install Hermes Agent inside a WSL2 Linux distribution, not in Windows PowerShell: enable WSL2, open Ubuntu, run the official installer, reload your shell, and complete Hermes setup. WSL2 is the recommended choice because Hermes expects Linux process and filesystem behavior; WSL1 is not reliable for this use. This guide also covers Windows-to-WSL networking, keeping a gateway running, and the common installation failures.
Before you start: what WSL2 changes
Windows Subsystem for Linux (WSL) lets you run a Linux distribution alongside Windows. Hermes Agent runs inside that distribution as a Linux program, while you can continue to use Windows applications and access Windows files when needed. For this guide, the commands are split between elevated Windows PowerShell and the Linux shell inside WSL; run each command in the environment named above it.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minutePC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11| # | Preview | Product | Price | |
|---|---|---|---|---|
| 1 |
|
Microsoft OEM System Builder | Windоws 11 Pro | Intended use for new systems | Authorized by... | $168.99 | Buy on Amazon |
| 2 |
|
Windows 11 Pro Upgrade, from Windows 11 Home (Digital Download) | $99.00 | Buy on Amazon |
| 3 |
|
Microsoft Windows 11 (USB) | $124.97 | Buy on Amazon |
Use WSL2 rather than WSL1. The Hermes Windows guide says WSL1 is not reliable because its system-call, process, signal, and networking behavior differs from a real Linux environment. WSL2 is also the appropriate choice when you need Hermes’s dashboard embedded terminal or a POSIX-style development environment. Hermes supports native Windows too, but WSL2 is a better fit when those Linux-specific capabilities matter.
WSL2 versus native Windows
| Consideration | WSL2 | Native Windows |
|---|---|---|
| Dashboard embedded terminal | Available in the WSL2 setup described by the official guide. | Not the WSL2-only terminal experience. |
| Filesystem and processes | Linux filesystem and process semantics; suited to POSIX-oriented projects. | Windows-native paths and process behavior. |
| Windows file access | Windows drives can be mounted, such as under /mnt/c, but active repositories there may be slower. |
Direct access to Windows paths. |
| Networking | May require choosing mirrored or NAT behavior for services on Windows or the LAN. | Does not require crossing the WSL networking boundary for Windows-local services. |
| Long-running gateway | Can use systemd in WSL, with an optional Windows logon task to keep the distribution running. | Uses the native Windows service/runtime arrangement. |
| GPU and local models | WSL2 can use NVIDIA GPUs through the standard Windows NVIDIA driver; local-service connectivity depends on networking. | Uses Windows-native drivers and local service endpoints. |
This is not a performance benchmark or a claim that one installation suits every workload. Choose WSL2 for Linux tooling, the embedded terminal, or repositories that expect POSIX behavior. Choose native Windows if keeping everything on Windows paths and avoiding WSL network or lifecycle configuration matters more.
#1 Best Overall
- STREAMLIMED AND INTUITIVE UI | Intelligent desktop | Personalize your experience for simpler efficiency | Powerful security built-in and enabled.
- JOIN YOUR BUSINESS OR SCHOOL DOMAIN for easy access to network files, servers, and printers.
- OEM IS TO BE INSTALLED ON A NEW PC WITH NO PRIOR VERSION of Windows installed and cannot be transferred to another machine.
- OEM DOES NOT PROVIDE PRODUCT SUPPORT | To acquire product with Microsoft support, obtain the full packaged “Retail” version.
1. Install WSL2 and verify the distribution
Run the install command from elevated PowerShell
- Open Windows Terminal or PowerShell with Run as administrator.
- Run
wsl --install. On a fresh supported Windows installation, reboot if Windows prompts you to do so. - After installation, open the Linux distribution from the Start menu. Ubuntu will ask you to create a Linux username and password. These are Linux credentials, separate from your Windows account.
- Return to PowerShell and run
wsl --list --verbose.
Check the VERSION column for your distribution. It must say 2. If it says 1, the distro is still using WSL1 and should be changed to WSL2 before installing Hermes. The command output also shows the distribution name; note it because commands such as the Task Scheduler keep-alive use that name.
Confirm WSL2 before troubleshooting Hermes
Do not diagnose an installation as a Hermes problem until the distribution is confirmed as version 2. WSL version is a property of the Linux distribution, not merely the Windows installation. If the list contains more than one distribution, verify the exact one in which you intend to install Hermes.
Free tools Windows power users keep installed
One-click scans. No signup required.
2. Enable systemd if you want managed gateways
Systemd is recommended when you want Hermes to install a systemd user unit for its gateway. It is not required just to run the installer or start Hermes interactively. To enable it, edit or create /etc/wsl.conf inside the Linux distribution. For example, use sudo nano /etc/wsl.conf, then add these sections:
[boot]
systemd=true
[interop]
enabled=true
appendWindowsPath=true
[automount]
options = "metadata,umask=22,fmask=11"Keep the section spelling and brackets exactly as shown, including [automount]. The metadata mount option preserves Linux permission bits on Windows-mounted paths; the accompanying mask options set the default permission masks for those mounts. The interop settings enable Windows interoperability and append Windows paths to the Linux PATH.
Save the file, then run this in PowerShell to stop WSL completely:
wsl --shutdownReopen the distribution for the configuration change to take effect. To check whether systemd is PID 1, run in WSL:
ps -p 1 -o comm=If the command reports systemd, it is active. If you do not need a managed gateway, you can skip this section and install Hermes without enabling systemd.
3. Install Hermes inside the WSL2 shell
Open the Linux distribution and run the installer in its shell—not in PowerShell. The official installation command is:
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bashThe command downloads the installer script and passes it to Bash. Hermes’s Windows (WSL2) guide says the installer treats WSL2 as plain Linux, so there is no separate WSL-specific installer step. The official installation page describes the source installer as bootstrapping uv and preparing pinned Python, Node, npm, ripgrep, and FFmpeg tooling. It also installs browser and computer-use tools by default and writes logs under the Hermes data directory. For the command and installer source, see the official Hermes installer.
Rank #2
- Instantly productive. Simpler, more intuitive UI and effortless navigation. New features like snap layouts help you manage multiple tasks with ease.
- Smarter collaboration. Have effective online meetings. Share content and mute/unmute right from the taskbar (1) Stay focused with intelligent noise cancelling and background blur.(2)
- Reassuringly consistent. Have confidence that your applications will work. Familiar deployment and update tools. Accelerate adoption with expanded deployment policies.
- Powerful security. Safeguard data and access anywhere with hardware-based isolation, encryption, and malware protection built in.
Let the installer finish and pay attention to any errors it reports. Once it returns to the shell prompt, reload your Bash configuration:
Recommended Free Tools
source ~/.bashrcThen start Hermes:
hermesIf the shell still says the command is unavailable, do not rerun the installation immediately. First open a new WSL terminal or source ~/.bashrc again; the current shell may not have loaded the path changes made by the installer.
4. Complete setup and configure Hermes
Run the full interactive setup wizard inside WSL:
hermes setupUse the wizard to configure the providers and options you need. For a more targeted setup, the official CLI also documents these commands:
| Command | Purpose |
|---|---|
hermes model |
Configure or manage model settings. |
hermes tools |
Configure tools. |
hermes gateway setup |
Set up the gateway, including a systemd user unit when systemd is available. |
hermes config set |
Set a configuration value. |
Nous Portal users can also use hermes setup --portal as a quicker setup path. When something fails or the configuration is unclear, run hermes doctor for diagnostics. Setup choices depend on the providers and tools you actually intend to use; installing Hermes does not by itself select or configure every model endpoint.
5. Keep projects and active work in the Linux filesystem
For repositories Hermes will read, modify, or run commands in, prefer a location such as ~/code/project inside the WSL distribution. Avoid using /mnt/c/... as the working location when practical. Windows-mounted paths can make operations such as git status and hermes chat much slower than working inside the Linux filesystem, and crossing the Windows/Linux filesystem boundary can create permission friction.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Clear out junk files and repair common Windows errors3Fix the driver behind crashes, sound loss and screen glitchesWindows applications can still be part of the workflow; the recommendation is about where active repository operations happen. If you keep a checkout on a Windows drive for other reasons, expect slower repository operations and pay attention to executable permissions and line endings.
Prevent CRLF script failures
A shell script with Windows CRLF line endings can fail with an error such as bad interpreter: /bin/bash^M. Configure Git inside WSL to check out LF endings and convert committed line endings appropriately:
git config --global core.autocrlf input
git config --global core.eol lfThese are global settings for Git in that Linux user account. They help avoid CRLF-related interpreter failures and related byte-order-mark problems; they do not convert every existing file automatically. For an already affected script, convert its line endings to LF, then retry it.
6. Choose a Windows-to-WSL networking mode
Networking matters when Hermes needs to call a service running on Windows, when a Windows browser needs to reach a Hermes dashboard in WSL, or when other devices on the local network need to reach a service. The right setup depends on which machine initiates the connection and whether WSL is using mirrored networking or NAT.
Rank #3
- Less chaos, more calm. The refreshed design of Windows 11 enables you to do what you want effortlessly.
- Biometric logins. Encrypted authentication. And, of course, advanced antivirus defenses. Everything you need, plus more, to protect you against the latest cyberthreats.
- Make the most of your screen space with snap layouts, desktops, and seamless redocking.
- Widgets makes staying up-to-date with the content you love and the news you care about, simple.
- Stay in touch with friends and family with Microsoft Teams, which can be seamlessly integrated into your taskbar. (1)
| Mode or access need | What to expect | What to configure |
|---|---|---|
| Mirrored networking on Windows 11 22H2 or later | Can make localhost work in both directions between Windows and WSL. | Set networkingMode=mirrored in the Windows user’s .wslconfig, then shut down and reopen WSL. |
| NAT, Windows host to WSL service | Localhost forwarding usually works for Windows-host access, but the service may need to listen on 0.0.0.0. |
Check the service bind address and Windows firewall behavior if Windows cannot connect. |
| LAN client to a WSL service | Usually needs explicit forwarding from Windows rather than assuming WSL localhost is reachable from the network. | Configure a Windows port proxy and an appropriate Windows Firewall rule. |
| Hermes in WSL to a Windows-hosted model service | Mirrored networking is the simplest route when available. | With older or NAT setups, use the Windows host IP, bind the Windows service to 0.0.0.0, and allow the port through Windows Firewall as appropriate. |
Enable mirrored networking
Mirrored networking is available for Windows 11 22H2 or later according to the WSL2 guide. Edit %USERPROFILE%.wslconfig on the Windows side and add:
[wsl2]
networkingMode=mirroredSave the file, run wsl --shutdown in PowerShell, then reopen WSL. The setting belongs in the Windows user’s .wslconfig, not Linux’s /etc/wsl.conf. They control different aspects of the environment.
Access a WSL dashboard from Windows or the LAN
In NAT mode, Windows-host access through localhost usually works, but a service may need to bind beyond its loopback interface. If you need a device elsewhere on your LAN to reach a WSL-hosted dashboard or service, configure a Windows port proxy and a matching firewall rule. A service listening only on its own loopback address will not necessarily be reachable through an external interface. Only expose ports you intend to make reachable, and limit firewall access to the needed scope.
Connect Hermes to a Windows local model server
For a Windows-hosted Ollama, LM Studio, or llama-server endpoint, mirrored mode is the simplest option when your Windows version supports it. On older or NAT-based configurations, Hermes may need to connect to the Windows host’s IP rather than assuming the Linux guest’s localhost is the Windows host. The Windows service must listen on 0.0.0.0 for connections from WSL, and Windows Firewall must allow the relevant port. A connection-refused error can therefore mean the service is not listening on a reachable interface, not that Hermes itself is broken.
7. Keep a gateway running beyond an interactive session
For a gateway that should be managed rather than launched manually each time, enable systemd first, then run:
hermes gateway setupThe setup wizard can install a systemd user unit. WSL still has a lifecycle of its own, so a configured unit alone may not keep the distribution running after Windows has no active WSL process. If the gateway needs WSL to remain alive after Windows login, the guide’s keep-alive approach is to create a Windows Task Scheduler task that runs at user logon:
wsl.exe -d Ubuntu --exec /bin/sh -c "sleep infinity"Replace Ubuntu with the exact distribution name shown by wsl --list --verbose if yours differs. This scheduled process keeps that WSL distribution active; it is not a substitute for configuring Hermes’s gateway itself. Use the systemd gateway setup and the Windows keep-alive together when both service management and a persistent WSL process are needed.
8. GPU and local-model notes
WSL2 supports NVIDIA GPUs through the standard Windows NVIDIA driver. Do not install a separate Linux NVIDIA driver inside WSL for this setup. The Hermes WSL2 guide describes AMD ROCm and Intel Arc support as evolving and outside its test matrix, so the available information does not establish a comparable supported configuration for those GPUs. For local models hosted on Windows, use the networking checks above in addition to configuring the model provider in Hermes.
Troubleshoot common installation problems
| Symptom | Likely cause | What to do |
|---|---|---|
hermes: command not found |
The current shell has not loaded the installer’s path changes. | Run source ~/.bashrc or close and reopen the WSL terminal. |
bad interpreter: /bin/bash^M |
A script has CRLF line endings. | Convert the script to LF and apply the Git line-ending settings shown above. |
| Connection refused when Hermes calls a Windows model | The endpoint may be listening only on loopback, the address may be wrong for the selected networking mode, or the firewall may block it. | Check mirrored versus NAT networking, use the Windows host IP for older/NAT setups, bind the Windows service to 0.0.0.0, and review the firewall rule. |
Slow git status or Hermes work in a repository |
The repository is on a Windows-mounted path such as /mnt/c. |
Move active work into the WSL Linux filesystem, for example ~/code/project. |
UNC paths are not supported from an MCP-launched binary |
The binary was started from a path that Windows cannot use in that context. | For that session, start Hermes from a Windows-reachable path such as /mnt/c/.... |
| Certificate-based connections fail after sleep | The WSL clock may have drifted while the machine was asleep. | The WSL2 guide suggests an on-demand correction with sudo hwclock -s. |
If an error occurs during the install rather than after it, first confirm that you ran the shell command inside the intended WSL2 distribution and that the installer completed. For configuration issues, hermes doctor is the documented diagnostic command. Keep the distinction between a Linux-shell issue, a Windows-to-WSL connectivity issue, and a provider endpoint issue in mind: each crosses a different boundary.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
