Hermes Agent on Your Local PC: Windows, Linux, macOS, and WSL2

This is the second of two install paths. D1 was the VPS bootstrap — a public host with a tunnel and a real hostname. D2 is the path most people actually start with: your own workstation, your own power, no inbound traffic by default.

Hermes runs the same way on a desktop as on a remote box, with one big behavioural difference — there is no public IP by default. That’s mostly an upside: no SSH hardening, no Cloudflare Tunnel, and your home router doesn’t need to know Hermes exists. The Telegram gateway still works because outbound HTTPS to api.telegram.org is enough; the gateway polls the Bot API, it doesn’t need to be reached.

What’s the same and what’s different

The Hermes install path on a local workstation is the same script and same venv shape as on a VPS, with three differences: no public IP by default, no inbound tunnel needed for outbound-only use, and (on Windows) WSL2 is the canonical host.

Platform-by-platform install

Platform	Path	Notes
macOS (Apple Silicon)	`curl -fsSL https://hermes-agent.nousresearch.com/install	bash`
Linux (Ubuntu 22.04+)	same script	pip + venv prerequisites
Windows (native)	not supported	use WSL2
Windows (WSL2 Ubuntu)	same Linux script inside WSL2	WSL2 systemd is on by default in Win11; enable systemd=true in /etc/wsl.conf on Win10

Apple Silicon Macs and a current Ubuntu install are the smoothest paths. On macOS, brew install [email protected] once and the rest is the same script. On Linux, make sure python3-venv and python3-pip are present (apt install python3-venv python3-pip on Debian-family). On Windows, the rule is simple: there is no native Hermes-on-Windows path — the agent relies on POSIX process and signal semantics that WSL2 gives you for free. Install WSL2, then run the Linux script inside it.

WSL2 is one PowerShell command from an elevated prompt: wsl --install. Reboot, set a UNIX username and password, and you’re in an Ubuntu environment where the Linux script just works. On Windows 11, WSL2 ships with systemd enabled by default; on Windows 10 flip it on by adding [boot] systemd=true under /etc/wsl.conf and running wsl --shutdown. Either way, once systemd is up, hermes gateway install supervises the gateway the same way it does on a VPS.

The install pattern

curl -fsSL https://hermes-agent.nousresearch.com/install | bash
hermes chat -q 'Reply with OK'

That’s the whole first-day path.

The installer creates ~/.hermes/venv/, drops the hermes binary on your PATH, and writes a default config. The hermes chat -q 'Reply with OK' smoke test is the cheapest possible proof that the runtime is alive — one model call, one second, and you know the agent, the provider, and the venv are wired correctly. Get “OK” back and you’re done with day one. Any other failure is almost always either the venv wasn’t activated when the binary ran, or the provider key isn’t set — both have well-known fixes in the verification checklist below.

Going further

If you want Telegram on day 1: hermes gateway install is local; the gateway reaches api.telegram.org directly without a tunnel. If you want a custom URL (mockups.nowandthenshirts.com pattern) you’d still need a tunnel back to the workstation, which is why D1 is the right pick for any production-grade hostname.

The gateway story is the part that surprises people. On a VPS, you’d normally front the gateway with a tunnel or a reverse proxy so that webhook-style integrations can reach it. The Telegram gateway doesn’t need any of that — it uses long polling against the Bot API, so as long as your workstation has outbound HTTPS, it works. The catch is that “outbound HTTPS” includes your home network’s normal NAT and firewall state, which is fine. The gateway process is supervised by systemd on Linux/macOS launchd, runs as your user, and survives reboots.

If at some point you want a stable hostname pointing at something Hermes is running on your local box — a mockup generator, a webhook receiver, a public-facing tool — that’s where the local-PC story breaks down. Home IPs are dynamic, residential ISPs block inbound 80/443, and exposing a workstation to the open internet is a security tax you don’t want. At that point D1 (VPS) is the right call, not a clever tunnel. Cloudflare Tunnel can technically bridge them, but if you’ve already got a VPS it’s simpler to run the workload there.

Disk and memory

Local PC Python venvs live at ~/.hermes/venv/. A full Hermes install with cron + gateway + image_gen is ~700MB. Models cache at ~/.hermes/cache/models/; expect 5-30GB if you load a local Ollama 32B.

The install footprint is small enough that you can keep it on a laptop without thinking about it. The model cache is the thing that surprises people. If you only ever talk to a remote provider — Anthropic, OpenAI, Nous Portal, anything cloud-side — the local cache stays empty and you don’t care. The moment you opt into local inference via Ollama (because you’re trying to keep some workloads private, or because you want offline), that cache starts filling up. A 7B quantised model is around 4-8GB; a 32B is in the 20-30GB range. Plan disk accordingly, and if you’re on a laptop with a small internal SSD, point ~/.hermes/cache/ at an external drive with a symlink rather than letting it sprawl.

What not to do

• Don’t try Hermes native on Windows. WSL2.
• Don’t run the installer outside your venv — python3 -m venv ~/.hermes/venv first, then source ~/.hermes/venv/bin/activate, then install.
• Don’t put the hermes binary in ~/bin/ and expect it found; either symlink into /usr/local/bin/ or update PATH.

The venv-installation order matters because hermes is a console script that lives inside the venv’s bin directory. If you skip source ~/.hermes/venv/bin/activate before invoking it, the shell falls back to a system Python that doesn’t have the agent’s dependencies installed, and you get a confusing ModuleNotFoundError on something as basic as pydantic. Activate the venv first, or call the binary by full path (~/.hermes/venv/bin/hermes) — both work; mixing them doesn’t.

The ~/bin/ warning is one of those things that bites people on macOS where ~/bin/ exists from an old Homebrew install but isn’t on PATH by default. Either drop a symlink in /usr/local/bin/hermes -> ~/.hermes/venv/bin/hermes (cleanest, survives reinstalls) or add export PATH="$HOME/.hermes/venv/bin:$PATH" to your shell rc.

Verification checklist

#	Command	What it proves
1	hermes --version	Local install landed
2	hermes chat -q 'Reply with OK'	Runtime alive
3	hermes cron list	Cron store reachable
4	python3 -c "import sys; print(sys.executable)"	venv Python is the system
5	ls -la ~/.hermes/cache/	Cache directory writable

Run these in order. Step 1 catches the “binary not on PATH” failure mode. Step 2 catches provider-key and venv activation failures. Step 3 catches filesystem permission issues with the cron store. Step 4 is the canary for “I’m running the venv Python” — the path should be inside ~/.hermes/venv/, not /usr/bin/python3. Step 5 confirms the cache directory exists and your user can write to it, which is what every downstream feature assumes.

If step 2 returns anything other than a clean “OK”, the most common cause is a missing provider key. Run hermes config set provider <name> and hermes config set api_key <key> (or use the interactive hermes config flow), then retry. If step 3 fails with a permission error, the cron store is probably owned by another user from a previous install — rm -rf ~/.hermes/cron.db* and re-run.

Sources

• Hermes Agent install docs
• ABS companion: Hermes Agent Setup v2
• ABS companion: Hermes Agent on a VPS

Last verified: 2026-07-14.