Run Hermes Agent on Windows

Can Hermes Run Natively on Windows?

No. Native Windows is explicitly unsupported by the Hermes installer. The upstream installer's supported targets are Linux, macOS, WSL2, and Android (Termux). Running Hermes directly on a bare Windows environment — without any Linux layer — is not a supported path.

WSL2 is required, not merely recommended. The two supported approaches on Windows are:

1. Run the Hermes installer directly inside WSL2 (simplest — no Docker Desktop needed).
2. Run the official nousresearch/hermes-agent Docker image via Docker Desktop with a WSL2 backend.

Requirements

• Windows 10 (64-bit, build 19041 or later) or Windows 11
• WSL2 enabled (see Step 1) — required for both paths
• Git installed inside WSL2 (only prereq for the installer path)
• Docker Desktop with the WSL2 backend enabled (only for the Docker path)
• At least 8 GB RAM recommended (Hermes loads an LLM backend; 16 GB is comfortable)
• Virtualization enabled in your BIOS/UEFI (required by WSL2)

Step 1: Enable WSL2

Open PowerShell as Administrator and run:

wsl --install

This installs WSL2 along with Ubuntu (22.04 or 24.04 depending on your Windows version) as the default distribution. Restart your computer when prompted. After reboot, Windows will finish the Ubuntu setup and ask you to create a Linux username and password.

If WSL is already installed but running version 1, upgrade it:

wsl --set-default-version 2

Step 2a: Install Hermes Inside WSL2 (Recommended)

Open Ubuntu from the Start menu (or run wsl in PowerShell). The only prerequisite inside WSL2 is Git. The installer handles everything else — Python 3.11 (via uv), Node.js v22, uv, ripgrep, and ffmpeg are all installed automatically.

Run the one-liner inside WSL2:

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

Once installed, start the gateway with hermes start. The dashboard is accessible via a separate command:

hermes dashboard

The dashboard runs on port 9119 and is localhost-only. WSL2 auto-forwards localhost:9119 to the Windows side, so you can open it in your Windows browser. To enable the OpenAI-compatible API server on port 8642, set the environment variable API_SERVER_ENABLED=true before starting Hermes.

Step 2b: Install Docker Desktop for Windows (Alternative)

If you prefer the Docker approach, download Docker Desktop from docker.com and run the installer. During or after installation:

1. Open Docker Desktop, go to Settings → General, and confirm that Use the WSL 2 based engine is checked.
2. Under Settings → Resources → WSL Integration, enable integration with your Ubuntu distribution so Docker commands work inside WSL.
3. Apply and restart Docker Desktop.

You can verify Docker is accessible from WSL by opening Ubuntu from the Start menu and running docker version.

Step 3: Run Hermes via Docker (Docker Path Only)

All Docker commands for Hermes should be run from inside WSL2, not from PowerShell, to avoid Windows path translation issues. The official image is on Docker Hub as nousresearch/hermes-agent. Always use a pinned version tag rather than :latest — check the upstream releases page for the current stable tag.

Keep your Hermes data directory inside the WSL filesystem (for example, ~/hermes-data) rather than on a Windows-mounted path like /mnt/c/.... Cross-filesystem I/O is slower and can cause permission problems.

Step 4: Expose the Gateway and Control UI

Hermes exposes two ports:

• Port 9119 — the dashboard (analytics, config, cron, logs, skills, status). This is a separate process: run hermes dashboard (or pip install hermes-agent[web] first if using the pip distribution). It is not started automatically by the default gateway process.
• Port 8642 — the OpenAI-compatible API server, enabled via API_SERVER_ENABLED=true.

If running via Docker, pass -p 9119:9119 and -p 8642:8642 in your docker run command. WSL2 automatically forwards these ports to localhost on the Windows side, so you can open http://localhost:9119 in your Windows browser once the dashboard process is running.

On first launch, Windows Defender Firewall may show a prompt asking whether to allow Docker connections. Allow access on private networks at minimum.

Step 5: Connect a Channel

Once the Hermes dashboard is reachable at http://localhost:9119, you can connect Telegram, Discord, Slack, or use the OpenAI API server as a platform. Pairing is handled through the dashboard UI or the hermes pairing approve CLI.

Common Windows Gotchas

WSL2 Memory Cap

By default, WSL2 can consume a large portion of your system RAM. If you see memory pressure, create a .wslconfig file in your Windows home folder (C:\Users\YourName\.wslconfig) to cap it:

[wsl2]
memory=8GB
processors=4

Run wsl --shutdown in PowerShell then reopen WSL to apply.

File Permission Issues on Windows-Mounted Paths

Paths under /mnt/c/ and other Windows drives are mounted with a fixed permission mask. Docker bind mounts pointing there can produce unexpected read-only or permission-denied errors inside the container. Always store Hermes data inside the WSL filesystem (e.g. ~/hermes-data).

Docker Desktop Must Be Running

Docker Desktop does not start automatically by default. If you open WSL and get a Cannot connect to the Docker daemon error, open Docker Desktop from the Start menu and wait for the whale icon in the system tray to turn solid before retrying.

Antivirus False Positives

Some antivirus products flag Docker's WSL2 integration binaries. If Docker fails to start or WSL2 processes are terminated unexpectedly, check your antivirus quarantine and add exceptions for the Docker installation folder and the WSL2 kernel process (wslhost.exe).

Port Conflicts

If localhost:9119 is already in use, change the host-side port in your docker run command (e.g. -p 19119:9119). The container-internal port stays the same; only the Windows-side port changes.

The Easy Way: Use OpenClaw Launch

If WSL2 setup, Docker Desktop configuration, and port forwarding sound like too much friction, OpenClaw Launch runs Hermes Agent for you in a managed cloud environment. There is nothing to install — open a browser on any Windows machine, configure your agent, and deploy. The dashboard is always at a stable HTTPS URL, TLS is handled automatically, and updates are applied without any action on your part.

Windows Self-Install vs. OpenClaw Launch

Frequently Asked Questions

Do I need WSL2 to run Hermes on Windows?

Yes — WSL2 is required, not merely recommended. Native Windows is explicitly unsupported by the Hermes installer. The supported targets are Linux, macOS, WSL2, and Android (Termux). WSL2 provides the Linux environment Hermes requires; without it, there is no supported way to run Hermes on Windows.

Can I run Hermes without Docker Desktop?

Yes. The simplest path is to install Hermes directly inside WSL2 using the one-liner installer — no Docker needed at all. If you prefer containers, you can also install Docker Engine directly inside your WSL2 Ubuntu environment without Docker Desktop on the Windows side. Docker Desktop is the easiest option for most Windows users because it handles WSL integration and the system tray UI automatically.

Does Hermes work on Windows 10?

Yes, provided WSL2 is installed. WSL2 requires Windows 10 build 19041 (version 2004) or later. If your Windows 10 is up to date, run wsl --install and it will work. Windows 11 users have WSL2 available by default in all recent builds.

Can I run a local model on Windows with Hermes?

Yes. Install Ollama or LM Studio on the Windows side (not inside WSL), then point Hermes at http://host.docker.internal:<port> as the model endpoint. The special hostname host.docker.internal resolves to the Windows host from inside a Docker container, so Hermes can reach a local model server running outside WSL.

What ports does Hermes Agent use?

Port 9119 is used by the dashboard — but the dashboard is a separate command (hermes dashboard), not part of the default gateway process. You must start it explicitly. Port 8642 is the optional OpenAI-compatible API server, enabled via API_SERVER_ENABLED=true. Both are auto-forwarded to Windows localhost by WSL2.

Where do I find the Hermes image tag to use?

Always use a pinned version tag rather than :latest. The image is nousresearch/hermes-agent on Docker Hub. Check the upstream releases page for the current stable tag, or refer to the install guide for the version currently tested and supported on OpenClaw Launch.

Related Guides

• Install Hermes Agent
• Hermes Agent with Ollama
• Hermes Agent on GitHub
• What is Hermes Agent?
• OpenClaw on Windows