Windows (Native) Guide | Hermes Agent

Skip to main content

On this page

Hermes runs natively on Windows 10 and Windows 11 — no WSL, no Cygwin, no Docker. This page is the deep dive: what works natively, what's WSL-only, what the installer actually does, and the Windows-specific knobs you might need to touch.

If you just want to install, the one-liner on the landing page or Installation page is all you need. Come back here when something surprises you.

Want WSL instead?<br>If you prefer a real POSIX environment (for the dashboard's embedded terminal, fork semantics, Linux-style file watchers, etc.), see the Windows (WSL2) Guide . Both coexist cleanly: native data lives under %LOCALAPPDATA%\hermes, WSL data lives under ~/.hermes.

Quick install​

Open PowerShell (or Windows Terminal) and run:

iex (irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1)

No admin rights required. The installer goes to %LOCALAPPDATA%\hermes\ and adds hermes to your User PATH — open a new terminal after it finishes.

Installer options (requires the scriptblock form to pass parameters):

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1))) -NoVenv -SkipSetup -Branch main

ParameterDefaultPurpose-BranchmainClone a specific branch (useful for testing PRs)-CommitunsetPin install to a specific commit SHA (overrides -Branch)-TagunsetPin install to a specific git tag (e.g. v0.14.0)-NoVenvoffSkip venv creation (advanced — you manage Python yourself)-SkipSetupoffSkip the post-install hermes setup wizard-HermesHome%LOCALAPPDATA%\hermesOverride data directory-InstallDir%LOCALAPPDATA%\hermes\hermes-agentOverride code location<br>The installer auto-retries flaky git fetches and strips BOM from any downloaded install.ps1 payload, so a UTF-8 BOM picked up during HTTP transit no longer breaks the [scriptblock]::Create((irm ...)) form.

Desktop installer (alternative)​

A thin GUI installer is also available — useful if you'd rather double-click an .exe than open PowerShell. Download Hermes Desktop, run the installer, and on first launch the GUI calls install.ps1 under the hood to provision Python (via uv), Node, PortableGit, and the rest of the dependency bootstrap described below. After the first run, the desktop app and the PowerShell-installed hermes CLI share the same %LOCALAPPDATA%\hermes\hermes-agent install and %USERPROFILE%\.hermes data directory — switch between the GUI and the CLI freely.

Use the desktop installer when you want a familiar Windows install experience or you're handing Hermes to a non-developer; use the PowerShell one-liner when you're already in a terminal.

Dependency bootstrap (dep_ensure)​

On first launch (and on demand when a missing tool is detected), Hermes runs a small Python bootstrapper — hermes_cli/dep_ensure.py — that checks for and lazily installs the non-Python dependencies it needs. On Windows, the relevant ones are:

DependencyWhy Hermes needs itPortableGit Provides bash.exe for the terminal tool and git for in-session clones. Provisioned at install time, not by dep_ensure.Node.js 22 Required for the browser tool (agent-browser), the TUI's web bridge, and the WhatsApp bridge.ffmpeg Audio format conversion for TTS / voice messages.ripgrep Fast file search — falls back to grep if unavailable.npm packages agent-browser, Playwright Chromium, and any per-toolset Node deps are installed once at first browser-tool use.<br>Each dep has a shutil.which(...)-style check; if a binary is missing and the run is interactive, dep_ensure offers to install it (deferring to scripts\install.ps1 -ensure for the actual install logic). Non-interactive runs (gateway, cron, headless desktop launches) skip the prompt and surface a clear this feature needs error instead.

What the installer actually does​

Top-to-bottom, in order:

Bootstraps uv — Astral's fast Python manager. Installed to %USERPROFILE%\.local\bin.

Installs Python 3.11 via uv. No existing Python needed.

Installs Node.js 22 (winget if available, else a portable Node tarball unpacked under %LOCALAPPDATA%\hermes\node). Used for the browser tool and the WhatsApp bridge.

Installs portable Git — if git is already on PATH the installer uses it; otherwise it downloads a trimmed, self-contained PortableGit (~45 MB, from the official git-for-windows release) to %LOCALAPPDATA%\hermes\git. No admin, no Windows installer registry, no interference with anything else on the box.

Clones the repo to %LOCALAPPDATA%\hermes\hermes-agent and creates a virtualenv inside it.

Tiered uv pip install — tries .[all] first, falls back to progressively smaller sets ([messaging,dashboard,ext] → [messaging] → .) if a git+https dep flakes on rate-limited GitHub. Prevents "single flake drops you to a bare install" failure mode.

Auto-installs messaging SDKs keyed off .env — if TELEGRAM_BOT_TOKEN / DISCORD_BOT_TOKEN / SLACK_BOT_TOKEN / SLACK_APP_TOKEN / WHATSAPP_ENABLED are present, runs python...