Install Hermes Agent on a Windows VPS (via WSL2)

Hermes Agent doesn’t run natively on Windows. You install it inside WSL2 (Windows Subsystem for Linux). On a Windows VPS, that means enabling WSL2, installing Ubuntu, and running the Linux installer inside that environment. This guide walks through every step.

Time: about 25 minutes, most of which is WSL2 setup.

What you need

• A ColossusCloud Windows VPS with Windows Server 2022 or 2025, at least 4 GB RAM (cloud model APIs) or 8+ GB (local Ollama models)
• Administrator access
• An API key for your chosen model provider (OpenRouter, Anthropic, OpenAI, Nous Portal, or others)

Step 1: Connect to your Windows VPS

1. Log into the Client Portal and grab your Windows VPS 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 VPS IP and log in as Administrator

Step 2: Enable WSL2 on Windows Server

Open PowerShell as Administrator on the VPS and run:

wsl --install

On Windows Server, this may require an extra step. If the command above doesn’t work, install WSL manually:

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

Restart the VPS 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 automatically. It asks you to create a Linux username and password. This is separate from your Windows account. Pick a simple username (lowercase, no spaces).

Test that Ubuntu is running:

cat /etc/os-release

You should see Ubuntu 24.04 details.

Step 4: Update Ubuntu inside WSL2

Inside the Ubuntu terminal:

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

Step 5: Install Hermes Agent

Still inside the Ubuntu terminal:

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 your shell:

source ~/.bashrc

Verify:

hermes --version

Step 6: Run Hermes setup

hermes setup

The wizard asks for:

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

To switch providers later: hermes model.

Step 7: Install Docker inside WSL2 (recommended)

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

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

Exit the WSL2 terminal and re-open it (closing the window, then running wsl again from PowerShell) so the group change takes effect.

Start the Docker service:

sudo service docker start

Tell Hermes to use Docker for sandboxing:

hermes config set terminal.backend docker

Note: WSL2 doesn’t run systemd by default on older WSL versions. If service docker start doesn’t persist across WSL restarts, enable systemd in WSL by editing /etc/wsl.conf:

[boot]
systemd=true

Then run wsl --shutdown from PowerShell and re-open WSL. Docker will autostart with systemd.

Step 8: First run

hermes

You’re now in the Hermes TUI. Try:

> list all running services on this VPS

Hermes plans, uses its shell tool, and returns the list. Your interaction goes into its 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 easiest. Paste a bot token, done.

Step 10: Keep Hermes running 24/7 on Windows

This is where Windows + WSL2 gets quirky. Two options:

Option A: WSL2 with Windows Task Scheduler (simplest)

Have Windows start WSL and launch Hermes on boot.

1. In WSL2 Ubuntu, create a start script at ~/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 the task: check 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 (task to start WSL on boot) so WSL comes up automatically after a Windows restart.

WSL2 notes for Windows VPS

• Files. Keep Hermes data inside the WSL2 filesystem (~/.hermes) for performance. Accessing Windows files via /mnt/c/ is slower.
• Networking. WSL2 gets its own virtual network. Your gateway’s outbound connections to Telegram/Discord/etc. work fine. For inbound (webhooks), you may need port-forwarding rules in Windows. Most people avoid this by using outbound-only gateway protocols.
• Updates. Keep both Windows Server and WSL2 Ubuntu updated. Windows Updates can sometimes briefly stop WSL networking. Restart WSL if things act weird after an update.

Sizing your Windows VPS for Hermes

Use case	RAM	vCPUs	Notes
Cloud model APIs only	4 GB	2	WSL2 + Hermes is light
Ollama with small local models	8 GB	4	3-7B models comfortably
Ollama with mid-size local models	16 GB+	6+	13B+ models

Windows Server itself uses 1-2 GB baseline, so size accordingly.

Troubleshooting

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

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

Docker won’t start after reboot. Enable systemd inside WSL (Step 7) or run sudo service docker start on every WSL launch.

Task Scheduler runs but Hermes doesn’t connect. Check Windows event logs, and test the scheduled task’s arguments by running the wsl.exe command manually in PowerShell.

---

Deploy a ColossusCloud Windows VPS and get Hermes Agent running via WSL2. If you prefer native Linux, see our Linux VPS Hermes Agent guide.