How to Install Hermes Agent on WSL2 (2026)

Last verified: Jul 31, 2026 · Hermes 0.16.0

Hermes is a self-hosted, self-improving AI agent (Python, MIT). On WSL2 it installs the same way as on Linux — the official installer lands under ~/.hermes. This guide was verified against a live WSL2 instance running Hermes v0.16.0.

1. Install (official one-liner)

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

The installer handles its own dependencies: uv, Python 3.11, Node.js, ripgrep, and ffmpeg. On WSL2 it detects your existing Git and uses it (no bundled Git needed). Everything lands in ~/.hermes, isolated from your system Python.

Verify the binary is on your PATH:

hermes --version

2. Run the setup wizard

hermes setup

This walks through configuration in one pass — model provider, channels, skills. For a guided web UI:

hermes setup --portal

3. Start the gateway + chat

hermes gateway setup    # configure messaging channels
hermes gateway start    # start the gateway

Then send your bot a message on a configured channel. That’s the happy path: install → setup → gateway start → chat.

4. (Optional) Run it as a systemd user service

hermes gateway start runs in your terminal; closing the terminal stops it. To keep Hermes running across logouts and start it at login, run it as a systemd user service. The unit below is adapted from a real running instance (verified 2026-07-31) — save it as ~/.config/systemd/user/hermes-gateway.service:

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

[Service]
Type=simple
ExecStart=%h/.hermes/hermes-agent/venv/bin/python -m hermes_cli.main gateway run
WorkingDirectory=%h/.hermes
Environment="HERMES_HOME=%h/.hermes"
Restart=always
RestartSec=5

[Install]
WantedBy=default.target

Then enable + start it, and enable lingering so user services run without an active login session:

systemctl --user daemon-reload
loginctl enable-linger $USER
systemctl --user enable --now hermes-gateway.service
systemctl --user status hermes-gateway.service

%h expands to your home directory, so the unit is portable across users on the standard ~/.hermes install path.

Troubleshooting

hermes not found — the installer puts the binary at ~/.hermes/hermes-agent/venv/bin/hermes and symlinks it into ~/.local/bin. Make sure ~/.local/bin is on your PATH (it usually is on WSL2).
Service won’t start — check journalctl --user -u hermes-gateway.service -f. The most common cause is an incomplete hermes setup (missing model provider or channel config).
WSL2 + Windows PATH noise — your service PATH may include Windows paths inherited from WSL2. That’s cosmetic; the venv python is what actually runs.

Sources + freshness

Install steps follow the official Hermes docs (quickstart, install.sh). The systemd unit and the ~/.local/bin symlink detail were verified against a live WSL2 instance on 2026-07-31 (Hermes v0.16.0). Hermes moves fast — re-check the installer URL and version before deploying.