How to Install Hermes Agent on Windows: A Complete Troubleshooting Guide

Hermes Agent is an open-source AI agent framework built by Nous Research. It supports multiple inference backends — including OpenAI, Anthropic, and Ollama — and is designed to run locally on your machine. On paper, the installation is straightforward. In practice, Windows users regularly hit a handful of the same walls: GitHub timeouts, PowerShell script restrictions, and large binary downloads that stall or 404.

This guide walks through the full installation process on Windows, explains why each error happens, and gives you a working fix for each one. If you’re already stuck on a specific step, jump to the relevant section below.

Prerequisites: What You Need Before You Start

The installer script checks for these dependencies automatically and tells you what’s missing. Make sure the following tools are already installed before running the script.

Dependency	Purpose	Required Version
Python	Runs the agent’s core logic	3.11.x
Git	Clones the repository and handles updates	Any
Node.js	Required for browser automation tools	v18 or later recommended
ripgrep	Fast file search within the agent	Any
ffmpeg	Text-to-speech (TTS) voice messaging	Any
uv	Python virtual environment manager	Auto-installed by the script

When the script detects everything successfully, you’ll see output like this:

[OK] Python found: Python 3.11.15
[OK] Git found (git version 2.54.0.windows.1)
[OK] Node.js v22.23.1 found
[OK] ripgrep 15.1.0 found
[OK] ffmpeg found

Step 1: Run the Official Installer

Open PowerShell and run:

iex (irm https://hermes-agent.nousresearch.com/install.ps1)

The script handles dependency detection, repository cloning, virtual environment creation, and Python package installation automatically. Under normal network conditions, the whole process takes about 3 to 5 minutes.

Issue 1: Git Clone Fails — GitHub Connection Timeout

One of the most common installation failures looks like this:

fatal: unable to access 'https://github.com/NousResearch/hermes-agent.git/':
Failed to connect to github.com port 443 after 21079 ms: Could not connect to server
[X] Installation failed: git fetch failed (exit 128)

Why this happens: The script tries to clone the repository from GitHub over both SSH and HTTPS. If your network blocks or throttles GitHub connections, both attempts fail.

What the script does next: It automatically falls back to downloading a ZIP archive of the repository. You’ll see:

[!] Git clone failed -- downloading ZIP archive instead...
[OK] Downloaded and extracted

This fallback is intentional and produces a fully working installation — the only difference is that git history won’t be initialized, which means the auto-update feature on subsequent runs won’t work. If even the ZIP download fails, you’ll need to route traffic through a proxy before retrying.

Issue 2: Multiple `.broken` Folders Appearing

After a few installation attempts, you might notice your Hermes directory looks like this:

hermes-agent.broken-20260626-165435
hermes-agent.broken-20260626-170027
hermes-agent.broken-20260626-171749
hermes-agent.broken-20260626-174324

Why this happens: Each time you re-run the installer, it checks whether the existing hermes-agent directory is a valid git repository. If it isn’t — because the previous install used ZIP fallback or failed partway through — the script renames the old directory with a .broken-[timestamp] suffix and starts fresh. One re-run, one new .broken folder.

These directories are safe to delete. They contain leftover files from failed installs and serve no purpose once the installation succeeds.

# Replace YourUsername with your actual Windows username
Get-ChildItem "C:\Users\YourUsername\AppData\Local\hermes" -Filter "*.broken-*" | Remove-Item -Recurse -Force

Issue 3: PowerShell Execution Policy Blocks Scripts

You may see this when trying to activate the virtual environment:

.\venv\Scripts\activate : File cannot be loaded because running scripts is
disabled on this system.

Or this when running npm:

npm : File C:\nvm4w\nodejs\npm.ps1 cannot be loaded because running scripts
is disabled on this system.

Why this happens: Windows restricts execution of .ps1 PowerShell scripts by default as a security measure. This blocks both the virtual environment activation script and npm’s PowerShell wrapper.

Fix 1: Use the .bat and .cmd equivalents instead (recommended — no system changes required)

# Activate the virtual environment
.\venv\Scripts\activate.bat

# Use npm.cmd instead of npm
npm.cmd install
npm.cmd config set registry https://registry.npmjs.org

Fix 2: Change the execution policy for your user account

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned -Force

No restart needed. After running this, .\venv\Scripts\activate will work as expected.

Issue 4: Node.js Dependency Installation Fails or Hangs

Running npm install can fail in two distinct ways.

4a: Electron Download Fails with ECONNRESET

npm error command failed
npm error command C:\Windows\system32\cmd.exe /d /s /c node install.js
npm error RequestError: read ECONNRESET

Why this happens: Electron’s binary package is over 100MB and is downloaded from GitHub Releases during npm install. Slow or unstable connections to GitHub’s servers will cause this download to drop mid-stream.

Fix: Set the Electron mirror to a faster CDN

$env:ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/"
npm.cmd install

4b: EPERM Permission Error on Cleanup

npm warn cleanup [Error: EPERM: operation not permitted, rmdir ...]

Why this happens: A previous interrupted install left directory handles open. The operating system is still holding locks on those paths.

Fix: Disable antivirus real-time protection temporarily (including Windows Defender), open Command Prompt as Administrator, then clean up and reinstall:

Remove-Item -Recurse -Force node_modules -ErrorAction SilentlyContinue
npm.cmd install

Issue 5: Playwright Chromium Download Is Slow or Returns 404

The installer downloads a Playwright-managed Chromium browser for web automation features:

Downloading Chrome for Testing 149.0.7827.55 (playwright chromium v1228)
from https://cdn.playwright.dev/...
|                                            |   0% of 183.6 MiB

At 183MB served from an international CDN, this download can take a very long time or stall entirely. Switching to the npmmirror CDN sometimes results in a 404:

Error: Download failed: server returned code 404
<Code>NoSuchKey</Code>

Why this happens: Playwright chromium v1228 is a recent release. Mirror services haven’t necessarily synced this specific version yet, so the file simply doesn’t exist at that URL.

Fix: Skip the browser download and get the core agent running first

$env:PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD="1"
npm.cmd install

Note: The Playwright browser (Chromium) is an optional add-on for web automation features like screenshots, form filling, and page interaction. If you primarily use Hermes Agent for text conversations, code generation, or file operations, you can skip it entirely for now. You can always install it later when you have a stable connection.

Step 2: Configure Your Inference Provider

Once installation is complete, tell Hermes Agent which AI backend to use:

cd C:\Users\YourUsername\AppData\Local\hermes\hermes-agent
.\venv\Scripts\activate.bat
hermes setup model

This launches an interactive setup wizard. Use the arrow keys to select your provider:

◆ Inference Provider
  Choose how to connect to your main chat model.

  > Anthropic
    OpenAI
    OpenRouter
    Ollama
    ...

Choosing the right inference provider:

Provider	Best for	What you need
Anthropic	Claude models (Claude 3.5, Claude 3 Opus, etc.)	Anthropic API key
OpenAI	GPT-4o, GPT-4 Turbo, and other OpenAI models	OpenAI API key
OpenRouter	Access to many models via one API, pay-per-use	OpenRouter API key
Ollama	Running open-source models locally at no API cost	Ollama installed locally

After selecting a provider, the wizard will prompt you to enter your API key.

Step 3: Launch Hermes Agent

Once configured, launching the agent every time takes two commands:

cd C:\Users\YourUsername\AppData\Local\hermes\hermes-agent
.\venv\Scripts\activate.bat && hermes

Tip: Create a desktop shortcut so you can launch with a double-click

Create a new text file on your desktop, name it Launch Hermes.bat, and paste in the following:

@echo off
cd /d C:\Users\YourUsername\AppData\Local\hermes\hermes-agent
call .\venv\Scripts\activate.bat
hermes
pause

Replace YourUsername with your actual Windows username (visible under C:\Users\). From now on, double-clicking this file starts the agent directly — no terminal required.

Installation Flow at a Glance

Run installer script
    │
    ├─ GitHub unreachable → Script falls back to ZIP download → Continues normally
    │
    ├─ npm install fails
    │       ├─ Electron download drops → Set ELECTRON_MIRROR
    │       └─ Playwright 404 → Set PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1
    │
    ├─ PowerShell blocks .ps1 scripts → Use .bat / .cmd equivalents
    │
    └─ Installation complete
            │
            ├─ hermes setup model  (configure API key)
            └─ hermes              (start the agent)

Frequently Asked Questions

Can I run the installer script more than once?

Yes, but each run that finds an existing non-git directory will create another .broken backup folder before starting fresh. Once the installation is working, there’s no reason to re-run the script unless you want to update to a newer version.

What’s inside the .broken folders — can I delete them?

They contain leftover files from failed or incomplete installs. They have no functional value and can be safely deleted at any time.

If I skip Playwright, what features won’t work?

You’ll lose browser-based automation: opening web pages, taking screenshots, clicking buttons, and filling out forms. Core features — text conversations, code execution, file operations — are unaffected.

The hermes command isn’t found after installation. What do I do?

First, make sure the virtual environment is active. Your prompt should show (venv) at the start. Then try:

python -m hermes

If that also fails, check whether the package installed correctly:

pip show hermes-agent

Is there a way to launch Hermes without opening a terminal every time?

Yes — use the .bat launcher described in Step 3. You can also add it to your Windows startup folder (shell:startup in Run) to have it launch automatically when you log in.

Which local models does Hermes Agent support through Ollama?

Any model that Ollama supports, including Llama 3, Mistral, Qwen 2, Gemma 2, and many others. Running locally means no API costs, but you’ll need sufficient RAM or VRAM depending on the model size.

Does Hermes Agent work with self-hosted or alternative API endpoints?

Yes. OpenRouter in particular acts as a unified gateway to dozens of models. You can also point it at any OpenAI-compatible endpoint by configuring a custom base URL during setup.

Summary

The core installation process for Hermes Agent is not complicated — most blockers come down to network connectivity and a few Windows-specific quirks around script execution policies. Here’s the short version:

GitHub unreachable: The installer falls back to ZIP download automatically. No manual intervention needed.
PowerShell script errors: Use .bat for virtual environment activation and npm.cmd instead of npm.
npm install stalls: Set ELECTRON_MIRROR to redirect Electron’s download to a faster CDN.
Playwright 404: Skip the browser download with PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 and install it separately later.

The .broken directories that accumulate during repeated install attempts are harmless backups — clean them up once everything is running. The browser automation module and the agent core are independent, so you can get the agent working first and add Playwright later when your connection allows.

How to Install Hermes Agent on Windows: Complete Troubleshooting Guide for Common Errors