Skip to main content
Log in Sign up FREE!

Install Hermes Agent on Windows via WSL2 (VPS or dedicated)

By ServerPoint's Team

Hermes Agent doesn’t run natively on Windows. You install it inside WSL2 (Windows Subsystem for Linux). On a Windows VPS or a Windows dedicated server, the path is the same: enable WSL2, install Ubuntu, and run the Linux installer inside that environment.

This guide covers the full setup on Windows Server 2022 and 2025, plus the Task Scheduler and systemd tricks needed to keep Hermes running 24/7.

Time: about 25 minutes, mostly WSL2 setup.

What you need

  • A Windows Server VPS or dedicated server with Windows Server 2022 or 2025
  • Administrator access
  • An API key for your chosen model provider (OpenRouter, Anthropic, OpenAI, Nous Portal, etc.), or plan to use local Ollama models

Step 1: Connect to your Windows server

  1. Log into the Client Portal and grab your RDP credentials
  2. From your local machine, open Remote Desktop Connection (mstsc on Windows, Microsoft Remote Desktop on macOS/iOS/Android)
  3. Connect to the server IP and log in as Administrator

Step 2: Enable WSL2 on Windows Server

Open PowerShell as Administrator and run:

wsl --install

On Windows Server, this sometimes needs the manual path. If wsl --install doesn’t work:

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

Restart when prompted.

After restart, set WSL2 as the default:

wsl --set-default-version 2

Step 3: Install Ubuntu inside WSL2

wsl --install -d Ubuntu-24.04

When install finishes, Ubuntu opens a terminal and asks you to create a Linux username and password. Keep it simple (lowercase, no spaces).

Test:

cat /etc/os-release

You should see Ubuntu 24.04 details.

Step 4: Update Ubuntu

Inside the Ubuntu terminal:

sudo apt update && sudo apt upgrade -y
sudo apt install -y curl git

Step 5: Install Hermes Agent

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

The installer handles Python 3.11+, Node.js, and all dependencies.

Reload shell:

source ~/.bashrc

Verify:

hermes --version

Step 6: Run Hermes setup

hermes setup

The wizard asks:

  1. Model provider (Nous Portal, OpenRouter, Anthropic, OpenAI, Ollama, etc.)
  2. API key if using a cloud provider
  3. Default model
  4. Storage location (defaults to ~/.hermes inside WSL2)

To switch providers later: hermes model.

Step 7: Install Docker inside WSL2

For sandboxed tool execution, install Docker directly inside WSL2 (cleaner than Docker Desktop on Windows Server):

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER

Close the WSL2 terminal, reopen it with wsl from PowerShell, then:

sudo service docker start

Tell Hermes to use Docker sandboxing:

hermes config set terminal.backend docker

WSL2 doesn’t run systemd by default on older versions. To make Docker auto-start and enable systemd services, edit /etc/wsl.conf:

[boot]
systemd=true

From PowerShell: wsl --shutdown, then reopen WSL. Docker autostarts, and you can use systemd for the Hermes service (Step 10 below).

Step 8: First run

hermes

You’re in the Hermes TUI. Try:

> list all running Windows services on the host

Hermes plans, uses its shell and web tools, and responds. Interactions go into memory automatically.

Exit with Ctrl+D or /quit.

Step 9: Messaging gateway (optional)

To reach Hermes from Telegram, Discord, Slack, WhatsApp, or Signal:

hermes gateway

First run walks through linking each platform. Telegram and Discord are the easiest. Paste a bot token, done.

Step 10: Keep Hermes running 24/7 on Windows

Two options. The simplest covers Windows reboots.

Option A: Windows Task Scheduler (simplest)

Have Windows start WSL and launch Hermes on boot.

  1. In WSL2 Ubuntu, create ~/start-hermes.sh:

    #!/bin/bash
cd /home/YOUR_USERNAME
exec /home/YOUR_USERNAME/.local/bin/hermes gateway

  2. Make it executable:

    chmod +x ~/start-hermes.sh

  3. In Windows Task Scheduler:

    • Create Basic Task → “Hermes Agent Gateway”
    • Trigger: When the computer starts
    • Action: Start a program
    • Program: wsl.exe
    • Arguments: -d Ubuntu-24.04 -u YOUR_USERNAME /home/YOUR_USERNAME/start-hermes.sh
    • Finish, then edit: enable Run whether user is logged on or not and Run with highest privileges

  4. Right-click the task, Run, to test.

Option B: systemd inside WSL2

If you enabled systemd in Step 7, create /etc/systemd/system/hermes.service:

[Unit]
Description=Hermes Agent Gateway
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=YOUR_USERNAME
WorkingDirectory=/home/YOUR_USERNAME
ExecStart=/home/YOUR_USERNAME/.local/bin/hermes gateway
Restart=on-failure

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable --now hermes

Combine this with Option A (a task to start WSL on boot) so WSL comes up automatically after Windows restarts.

WSL2 notes for Windows servers

  • Files. Keep Hermes data inside the WSL2 filesystem (~/.hermes) for performance. Windows files via /mnt/c/ are slower.
  • Networking. WSL2 has its own virtual network. Outbound connections (to Telegram, Discord, model APIs) work fine. For inbound webhooks, you’d need Windows port-forwarding rules. Most people avoid this by using outbound-only gateway protocols.
  • Windows Updates. Can briefly break WSL networking. Restart WSL (wsl --shutdown then reopen) if things act weird.

VPS vs dedicated server for Windows + Hermes

Same installation, different scale.

Windows VPS

Fine for:

  • Personal assistant or small team
  • Cloud model APIs only
  • Small local models (3B-7B via Ollama) with 8+ GB RAM

Windows dedicated server

Better for:

  • Large local models (13B-70B) without paying API fees on high-volume use
  • Multiple isolated Hermes profiles (one per client/project)
  • Heavy sandboxed workloads: build pipelines, browser automation at scale
  • GPU-backed inference
  • Predictable performance without shared-host variance

Troubleshooting

wsl --install fails on Windows Server. Use the manual dism.exe commands in Step 2. Windows Server’s path differs from Windows 10/11 desktop.

hermes: command not found inside WSL. Run source ~/.bashrc or add ~/.local/bin to PATH.

Docker won’t start after reboot. Enable systemd in /etc/wsl.conf (Step 7), or run sudo service docker start each time.

Task Scheduler runs but Hermes doesn’t respond. Check Windows event logs, and test the wsl.exe command manually in PowerShell with the exact arguments you used in the task.

Deploy a ServerPoint Windows VPS or a Windows dedicated server and run Hermes Agent via WSL2. Prefer native Linux? See Install Hermes Agent on Linux.

← Back to all guides