How to Install Hermes Agent on Windows 11 With WSL2

Install Hermes Agent in a WSL2 Linux distribution, not WSL1. From an elevated PowerShell, run wsl --install, verify that Ubuntu reports VERSION 2, then run Hermes’ Linux installer inside the distribution. After installation, reload your shell, run the setup wizard, keep active repositories in the Linux filesystem, and choose mirrored or NAT networking according to how Windows and LAN clients must reach Hermes.

Antihost offers VPS plans with one-click Hermes Agent, NVMe storage and a 14-day free trial.

What you need before installing

This procedure targets Windows 11 with a current WSL2 installation and an Ubuntu distribution. Hermes Agent supports native Windows as well, but WSL2 is the better fit when you need POSIX process and filesystem behavior or the dashboard’s embedded terminal. You will need administrator access to enable WSL, a reboot during the initial setup, and a normal Linux user account inside Ubuntu.

#	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

As an Amazon Associate I earn from qualifying purchases.

• Windows 11 with hardware virtualization enabled in firmware and a supported WSL installation.
• PowerShell or Windows Terminal started with Run as administrator.
• An internet connection for the WSL distribution and Hermes installer.
• Enough disk space for the Linux distribution and Hermes’ downloaded tooling.
• Credentials for whichever model or provider you plan to configure. Your Ubuntu username and password are separate from your Windows account.

WSL1 is not a dependable target for Hermes. Its system-call, process, signal, and networking behavior differs from a real Linux environment, while WSL2 provides the Linux kernel behavior Hermes expects.

1. Install and verify WSL2

Run the installation command

1. Open PowerShell or Windows Terminal as an administrator.
2. Run:

wsl --install

On a fresh supported Windows installation, the command enables the required components, installs a default Linux distribution, and asks you to reboot. Restart Windows when prompted.

#1 Best Overall

Microsoft OEM System Builder | Windоws 11 Pro | Intended use for new systems | Authorized by Microsoft

• 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.

$168.99

Buy on Amazon

Create the Ubuntu account

After the reboot, Ubuntu opens its first-run setup. Choose a Linux username and password. These credentials control commands run inside WSL and are not your Microsoft or Windows sign-in details. The password is also what sudo will request when you perform administrative tasks inside Ubuntu.

Confirm that the distribution is version 2

From PowerShell, run:

wsl --list --verbose

Find your distribution in the output and check the VERSION column. It must show 2. If it reports version 1, convert that distribution before installing Hermes:

wsl --set-version Ubuntu 2

Replace Ubuntu with the exact distribution name displayed by wsl --list --verbose. Conversion can take time because WSL has to create a virtualized Linux filesystem. Run the listing command again when it finishes and do not proceed until the value is 2.

2. Enable systemd and sensible mount permissions

Hermes can run without systemd, but enabling it is recommended when you intend to run a gateway as a user service. The same configuration also makes Windows-mounted paths behave more like normal Linux files by preserving permission bits.

Edit /etc/wsl.conf

Open Ubuntu and create or edit the file with root privileges:

sudo nano /etc/wsl.conf

Use this configuration:

[boot]
systemd=true

[interop]
enabled=true
appendWindowsPath=true

[automount]
options = "metadata,umask=22,fmask=11"

The metadata mount option preserves Linux permission bits on Windows-mounted paths. The interop settings allow WSL programs to invoke Windows executables and retain the Windows path in the environment, which is useful for mixed workflows.

Save the file, exit the editor, and fully stop WSL from PowerShell:

wsl --shutdown

Open Ubuntu again. To check whether systemd is PID 1, run:

ps -p 1 -o comm=

A systemd-enabled instance reports systemd. If you changed the file while Ubuntu was running, the shutdown and restart are required before the setting takes effect.

3. Install Hermes Agent inside Ubuntu

Start the Ubuntu distribution and run the official Linux installer from the WSL shell:

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

The installer treats WSL2 as plain Linux—nothing WSL-specific is needed. It bootstraps uv, prepares pinned Python, Node, npm, ripgrep, and FFmpeg tooling, and installs browser and computer-use tools by default. Installation logs are written under Hermes’ data directory.

Reload the shell environment so the newly installed command is on your PATH:

source ~/.bashrc

Then start Hermes:

hermes

If the command launches, the core installation is complete. The first launch may take a moment while components are initialized. Keep this terminal inside Ubuntu; installing the script from a Windows PowerShell prompt instead of the WSL shell places the Linux installation in the wrong environment.

4. Run setup and configure a model

Use the full setup wizard

For the normal first-run path, execute:

hermes setup

The wizard walks through provider credentials, model selection, tool settings, and other required configuration. Complete it before trying to use chat or a gateway so Hermes has a model endpoint and the permissions it needs.

Configure only one area

When you want to revisit a specific part of the configuration, use the focused commands:

Rank #2

Windows 11 Pro Upgrade, from Windows 11 Home (Digital Download)

• 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.

$99.00

Buy on Amazon

hermes model
hermes tools
hermes gateway setup
hermes config set

hermes model selects or updates the model provider. hermes tools controls optional capabilities. hermes gateway setup configures a long-running gateway, and hermes config set changes individual settings without rerunning the entire wizard.

Nous Portal users and diagnostics

Users of Nous Portal can use the shorter path:

hermes setup --portal

If setup or startup fails, run:

hermes doctor

The diagnostic command is useful after changing WSL networking, model endpoints, or filesystem locations because it can distinguish an installation problem from a provider or connectivity problem.

5. Keep active projects in the Linux filesystem

Put repositories and files Hermes actively reads or modifies under your Linux home directory, such as:

mkdir -p ~/code
cd ~/code
# clone or create the project here

A path such as ~/code/project is preferable to /mnt/c/Users/you/project for active work. WSL2 can access Windows-mounted paths, but Git operations and Hermes chat sessions are commonly much slower there because every file operation crosses the Windows–Linux boundary. Linux-native paths also avoid many permission mismatches.

Make line endings predictable

If a Windows editor writes shell scripts with CRLF endings, Linux can report:

bad interpreter: /bin/bash^M

Configure Git inside WSL to check out LF endings and commit them consistently:

git config --global core.autocrlf input
git config --global core.eol lf

Convert an already affected script to LF in your editor or with a line-ending conversion tool, then remove any UTF-8 BOM if the interpreter still fails. The Git settings prevent new checkouts from reintroducing the same problem.

When a Windows path is deliberately required

Some MCP-launched Windows binaries expect a Windows-reachable working directory. If one reports UNC paths are not supported, start Hermes for that session from a Windows-mounted location such as /mnt/c/.... Use this as a compatibility exception rather than moving every repository there, because normal repository work is faster in the Linux filesystem.

6. Connect Windows, WSL, dashboards, and local models

Networking choice matters when Hermes calls a model server running on Windows, when Windows must open a dashboard served by Hermes, or when another device on your LAN must connect to a WSL service.

Mirrored networking on Windows 11 22H2 or later

Mirrored mode makes localhost behavior more symmetrical between Windows and WSL and is the simplest option for many Windows-hosted model services. Edit %USERPROFILE%\.wslconfig in Windows and add:

[wsl2]
networkingMode=mirrored

Apply the change by running this in PowerShell:

wsl --shutdown

Reopen Ubuntu and restart Hermes or its gateway. With mirrored networking, a Windows service and a WSL client can often use the same localhost address, reducing the address translation that NAT requires.

NAT mode and Windows-host services

NAT remains the default on many installations. Windows-to-WSL localhost forwarding usually works for a service listening on the expected interface, but a service that binds only to its loopback interface may reject connections from the other side. For a Windows-hosted Ollama, LM Studio, or llama-server endpoint, check the service’s bind address and expose it on an address WSL can reach. On older or NAT setups, use the Windows host IP, bind the Windows service to 0.0.0.0 when the service’s security model permits it, and allow the listening port through Windows Firewall as appropriate.

Binding to all interfaces increases exposure. Restrict the firewall rule to the required profile, interface, or source addresses rather than opening a model endpoint broadly.

Opening a Hermes dashboard from Windows

If Hermes serves a dashboard inside WSL, first identify the address and port on which the gateway listens. A service bound to 127.0.0.1 is available only inside WSL unless forwarding is provided. Mirrored mode can make localhost access work in both directions; in NAT mode, use the forwarded Windows localhost address when available or bind the service appropriately and connect through the WSL IP.

Allowing LAN clients

LAN access is a separate requirement from opening the dashboard on the same Windows machine. In NAT mode, configure a Windows port proxy from a Windows listening port to the WSL service, then add a matching Windows Firewall rule. The proxy must point to the current WSL address and listening port; WSL addresses can change when the instance restarts, so verify the target after a shutdown or network change. Do not expose a gateway or model endpoint to the LAN unless authentication and firewall scope are configured for that use.

Rank #3

Sale

Microsoft Windows 11 (USB)

• 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)

$124.97

Buy on Amazon

7. Keep Hermes gateways running after logout

Install a systemd user unit

With systemd enabled, run:

hermes gateway setup

The wizard can install a systemd user unit for the gateway. Use this when Hermes should be managed as a Linux service rather than started manually in an interactive shell. Check the service status with the systemd tools presented by the wizard, and inspect Hermes logs under its data directory if the unit exits.

Keep the WSL instance alive

WSL can stop when no process is running, which can take down a gateway even when its service configuration is correct. Use Windows Task Scheduler to launch this command at user logon:

wsl.exe -d Ubuntu --exec /bin/sh -c "sleep infinity"

In Task Scheduler, create a task that runs at your logon and uses the exact distribution name shown by wsl --list --verbose. The long-running sleep keeps the distribution present; systemd then manages the Hermes gateway inside it. If you use a different distribution name, replace Ubuntu in the command.

8. GPU and local-model considerations

WSL2 supports NVIDIA GPUs through the standard Windows NVIDIA driver. Install and maintain the Windows driver; do not install a separate Linux NVIDIA driver inside the WSL distribution, because competing driver installations can break the supported integration.

AMD ROCm and Intel Arc support are still evolving and are outside the Hermes WSL2 guide’s tested matrix. Treat those combinations as hardware- and driver-dependent rather than assuming that a Linux installation procedure for another distribution will work unchanged. If a local model cannot see the accelerator, first confirm the Windows driver and WSL GPU integration before changing Hermes provider settings.

Troubleshooting the common failures

hermes: command not found

The installer may have completed while the current shell still has the old PATH. Run:

source ~/.bashrc

Alternatively, close the Ubuntu window and open a new WSL terminal. If the command remains unavailable, confirm that you ran the installer inside Ubuntu and that the installation log completed without an error.

bad interpreter: /bin/bash^M

The script contains Windows CRLF line endings. Convert it to LF, remove a possible BOM, and apply the Git settings in the filesystem section. Re-run the script from the WSL shell after conversion.

A Windows-hosted model returns “connection refused”

• Confirm that the model service is running and listening on the port Hermes is using.
• Check whether it binds only to 127.0.0.1; NAT clients may need the Windows host IP and a service bound to 0.0.0.0.
• Try mirrored networking on Windows 11 22H2 or later, then run wsl --shutdown before testing again.
• Check Windows Firewall and any provider-specific access-control setting.

Git status or Hermes chat is unusually slow

Check the repository path with pwd. If it begins with /mnt/c/ or another Windows mount, move or clone the active project under your Linux home directory and retry. Keep a Windows-mounted copy only when a Windows tool specifically requires it.

A Windows executable launched through MCP rejects the path

The UNC paths are not supported message indicates that the binary received a path it cannot interpret as a Windows drive path. Start Hermes from a Windows-reachable path such as /mnt/c/... for that session, or adjust the MCP command so it receives a drive-letter path.

Certificates fail after the computer wakes from sleep

Clock drift can invalidate certificate-based connections. As an on-demand correction inside WSL, run:

sudo hwclock -s

Retry the connection after the system time is corrected. Persistent drift should be investigated at the Windows and WSL time-synchronization layers rather than worked around by disabling certificate checks.

The gateway disappears after logging out

Verify that systemd is active with ps -p 1 -o comm=, rerun hermes gateway setup if the user unit is missing, and confirm that Task Scheduler launches wsl.exe with the correct distribution at logon. A service cannot stay available after WSL exits, so the keep-alive process is part of the Windows-side setup.

Native Windows or WSL2?

Both deployment styles are supported. Choose based on the environment Hermes must interact with, not on the installation command alone.

WSL2 is the practical choice when Hermes needs Linux command-line tools, POSIX semantics, a Linux-native repository, or the dashboard terminal. Native Windows can be simpler when all tools, files, and model services already live on the Windows side and no Linux-specific workflow is needed.

Quick Recap

Bestseller No. 1

Microsoft OEM System Builder | Windоws 11 Pro | Intended use for new systems | Authorized by Microsoft

$168.99

Bestseller No. 2

Windows 11 Pro Upgrade, from Windows 11 Home (Digital Download)

$99.00

SaleBestseller No. 3

Microsoft Windows 11 (USB)

Make the most of your screen space with snap layouts, desktops, and seamless redocking.; FPP is boxed product that ships with USB for installation

$124.97

Final installation checklist

• wsl --list --verbose shows your Ubuntu distribution with VERSION 2.
• /etc/wsl.conf contains the systemd, interop, and metadata mount settings if you need those features.
• You ran wsl --shutdown after changing WSL configuration and reopened Ubuntu.
• The Hermes installer ran inside WSL, followed by source ~/.bashrc.
• hermes setup or hermes setup --portal completed, and a model provider is configured.
• Active repositories live under the Linux filesystem whenever performance matters.
• Networking mode, bind address, Windows Firewall, and any port proxy match the way Windows or LAN clients must connect.
• hermes gateway setup has created the service you need, and Task Scheduler keeps WSL alive after logon when required.
• NVIDIA users rely on the Windows driver rather than installing a second Linux driver in WSL.

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.