Table of Contents ▾
How to Install Hermes Agent on Windows — Complete Beginner's Guide
Hermes Agent is one of the most powerful local AI assistants available — but the setup can trip people up. This guide takes you from zero to running Hermes on your Windows PC, step by step, with no jargon.
What is Hermes Agent?
Hermes Agent is an AI assistant that runs on your own computer — not in the cloud. That means your conversations stay private, you don't pay per message, and it keeps working even if your internet is slow.
Think of it like having a personal assistant that lives on your PC. You can ask it questions, have it write things for you, do research, manage tasks, and more — all from a simple text interface. It's built by Nous Research and has over 168,000 people using it worldwide.
What makes it different from ChatGPT or Claude? You control everything. Your data never leaves your machine unless you explicitly connect it to an external service.
An AI model (also called an LLM — Large Language Model) is the "brain" that powers an AI assistant. Think of it like the engine in a car — Hermes is the car, and the model is what makes it actually move and think. Some models run locally on your computer (free, private), while others run on a company's servers and charge per use.
Hermes Agent can connect to external AI models (like Claude or GPT-4) if you want more power, but it also works with free local models that run entirely on your hardware. This guide covers both options.
Before You Start
Minimum System Requirements
| Component | Minimum | Required? |
|---|---|---|
| Windows Version | Windows 10 (version 2004 or later) or Windows 11 | Required |
| RAM | 8 GB (16 GB recommended) | Required |
| Storage | 10 GB free space | Required |
| GPU | Any — not required for basic use | Optional |
| Python, Node.js, Git | The installer sets these up automatically | Auto-installed |
Press Windows key + R, type winver, and press Enter. You need version 2004 (build 19041) or higher to use WSL2. If you're on Windows 11, you're fine.
What You'll Need Before Starting
- A Windows 10 (v2004+) or Windows 11 computer
- An internet connection (the installer downloads around 200 MB of files)
- About 20–30 minutes of uninterrupted time
- An API key for an AI provider — we'll cover this in Section 5
The Hermes installer does not require administrator privileges. It installs everything to your user account only.
Option A — Install via WSL2 (Recommended)
WSL2 (Windows Subsystem for Linux) is a feature built into Windows that lets you run Linux software without leaving Windows or buying a new computer. Think of it like a small Linux computer running quietly inside your Windows PC. Hermes was built for Linux first, so running it through WSL2 gives you the most stable experience.
Hermes Agent was built for Linux and Mac first — so running it through WSL2 gives you the most stable, well-tested experience.
A terminal is a text-based window where you type commands to control your computer — instead of clicking buttons, you type instructions. It looks old-fashioned but it's extremely powerful. Think of it like texting your computer instead of tapping icons. In this guide, you'll type a few short commands and the installer handles everything else.
If you've never used a terminal before, go with Option A (WSL2). It takes a few extra minutes to set up but it's significantly more reliable. Option B (Native Windows) is marked "early beta" by the Hermes team — meaning it works but may have occasional rough edges.
Open PowerShell as Administrator
Click the Start menu, type PowerShell, then right-click on "Windows PowerShell" and choose "Run as administrator." Click Yes when Windows asks for permission.
A blue terminal window will open. That's normal.
Install WSL2
In the blue PowerShell window, copy and paste this command, then press Enter:
# This installs WSL2 with Ubuntu (the most popular Linux version)
wsl --installWindows will download and install Ubuntu. This takes 5–10 minutes. You'll see a progress bar in the window.
When it finishes, it will ask you to restart your computer. Save anything open and restart now. WSL2 won't work until you do.
Set up your Ubuntu username and password
After restarting, a black terminal window should open automatically asking you to create a username and password for Ubuntu.
- Type a username (lowercase, no spaces — e.g.
mike) and press Enter - Type a password and press Enter — the cursor won't move as you type, that's normal
- Type the password again to confirm
If the window didn't open automatically, go to the Start menu and open Ubuntu.
Run the Hermes installer inside Ubuntu
In the Ubuntu terminal window, paste this command and press Enter:
# Downloads and runs the official Hermes installer
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bashThe installer will automatically download and set up Python 3.11, Node.js, and everything else Hermes needs. This takes about 5 minutes. You'll see lots of text scrolling past — that's normal.
When it's done you'll see a message like "Hermes installed successfully" and instructions to run source ~/.bashrc.
Reload your terminal
Run this command to make the hermes command available:
# Reloads your terminal settings so "hermes" command works
source ~/.bashrcVerify the install worked
# Checks your Hermes install and tells you if anything is misconfigured
hermes doctorYou should see a list of checks. Green checkmarks mean everything is working. Skip to Section 5 to set up your API key.
Option B — Install on Native Windows (Early Beta)
The Hermes team describes native Windows support as "early beta." It works, but it hasn't been as thoroughly tested as the WSL2 path. If you run into issues, switching to Option A (WSL2) is the recommended fix.
Open PowerShell (no admin needed)
Press Windows key + R, type powershell, and press Enter. A blue window will open.
You do not need to right-click and "Run as administrator" for this method.
Run the Windows installer
# Official Hermes installer for Windows — no admin required
iex (irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1)The installer automatically downloads and sets up:
- Python 3.11
- Node.js 22
- Git (a small portable version, ~45 MB)
- ffmpeg and ripgrep (tools Hermes uses internally)
Everything goes into %LOCALAPPDATA%\hermes — it won't affect any other software on your computer.
Windows may show a warning that it "can't verify the publisher." This is normal for scripts run directly from the internet. If you see this, click More info → Run anyway. The script is from the official Hermes GitHub repository.
Close and reopen PowerShell
After the installer finishes, close the PowerShell window completely and open a new one. This is required for the hermes command to be found — the installer updated your PATH, and the new window picks that up automatically.
PATH is a list your computer keeps of all the places it should look when you type a command. When the installer added Hermes to your computer, it also added Hermes's location to this list. Think of it like adding a new aisle to a store's directory — until the directory is updated, the cashier can't find that aisle. Opening a fresh terminal loads the updated list.
Verify the install
# Runs Hermes's built-in diagnostic tool
hermes doctorYou'll see a series of checks with green ✓ marks. If you see any red ✗ marks, scroll down to the Troubleshooting section.
Setting Up Your API Key
An API (Application Programming Interface) is a way for two pieces of software to talk to each other. Think of it like a waiter in a restaurant — you (the app) tell the waiter (the API) what you want, and the waiter goes to the kitchen (the AI company's servers) and comes back with your order. When Hermes sends your question to Claude or GPT-4, it's using an API to do that.
An API key is a long string of letters and numbers that acts as your password and account identifier combined. It tells the AI company "this request is coming from a legitimate, paying customer." Keep it private — anyone who has your API key can use your account and run up your bill.
The Easiest Option — Nous Portal
Nous Research runs their own portal that gives you access to 300+ AI models through a single login — no separate API keys needed. This is the simplest way to get started.
Run the portal setup wizard
# Opens the guided setup that connects Hermes to Nous Portal
hermes setup --portalThis will open a browser window asking you to log in or create a free Nous Research account. Follow the prompts.
Alternative — Use Your Own API Key
If you'd prefer to use Anthropic (Claude) or OpenAI (GPT-4) directly, here's how to get those keys:
Anthropic API Key (Claude)
- Go to console.anthropic.com
- Click Sign Up and create an account
- Click your profile → API Keys
- Click Create Key, give it a name (e.g. "Hermes")
- Copy the key — it starts with
sk-ant-
Anthropic only shows your API key once. If you close the page without copying it, you'll need to create a new one.
OpenAI API Key (GPT-4)
- Go to platform.openai.com/api-keys
- Sign in or create an account
- Click Create new secret key
- Copy the key — it starts with
sk-
Adding Your Key to Hermes
Run the interactive setup wizard — it will ask which provider you're using and where to paste your key:
# Walks you through choosing a model and entering your API key
hermes setupAlternatively, you can set it directly with a command. Replace YOUR_KEY_HERE with your actual key:
# For Anthropic/Claude
hermes config set ANTHROPIC_API_KEY YOUR_KEY_HERE
# For OpenAI/GPT-4
hermes config set OPENAI_API_KEY YOUR_KEY_HEREEnvironment variables are settings stored outside your code in a special file, so sensitive information like API keys doesn't get accidentally shared. Think of it like keeping your house Wi-Fi password written on a sticky note inside a drawer — the apps that need it know where to look, but it's not sitting on your desktop for everyone to see. Hermes stores your keys in a file called .env.
Your API keys are saved to a .env file on your computer — never sent anywhere except the AI provider you chose. On WSL2 the file is at ~/.hermes/.env. On native Windows it's at %LOCALAPPDATA%\hermes\.env.
Your First Task
Start Hermes by running:
# Starts Hermes in interactive mode — just type and press Enter to chat
hermesYou'll see a welcome banner showing your name, which AI model you're connected to, and a > prompt waiting for your input. Type anything and press Enter — Hermes should respond within a few seconds.
Three Simple Tasks to Try First
1. Ask a basic question
Type: "What can you help me with?" — Hermes will describe its capabilities. If you get a response, your setup is working correctly.
2. Ask it to write something
Type: "Write me a short professional email asking for a meeting." — Tests that the AI connection is working and responses are good quality.
3. Try a quick research task
Type: "What are three things I should know about running a home server?" — A bit more complex, good for seeing how Hermes handles research questions.
To exit Hermes, type exit or press Ctrl + C.
Other Useful Commands
# Start with a visual interface (easier to read)
hermes --tui
# Change which AI model Hermes uses
hermes model
# Enable or disable specific tools (web search, file access, etc.)
hermes tools
# Update Hermes to the latest version
hermes updateTroubleshooting
Here are the most common issues people run into, and exactly how to fix them.
The installer finished but your terminal doesn't know where to find the hermes command yet — the PATH hasn't been updated in your current window.
# WSL2/Ubuntu — reload your terminal settings
source ~/.bashrc
# Native Windows — just close PowerShell completely and open a new windowWindows has a security setting called "Execution Policy" that blocks scripts by default. Run this command to allow scripts for your user account only, then try the installer again:
# Allows PowerShell scripts to run for your account only (not system-wide)
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUserVirtualisation is disabled in your computer's BIOS/UEFI settings. Restart your PC, enter BIOS (usually by pressing F2, F10, or Delete at startup), find a setting called "Intel VT-x", "AMD-V", or "Virtualization Technology" and enable it. Search for your PC model + "enable virtualization BIOS" for specific steps.
The API key you entered is wrong, expired, or has a typo. Go back to your provider's dashboard and create a new key. Make sure you're copying the full key with no spaces before or after it.
AI companies charge by the "token" — roughly one token per word. When you send a message, you use tokens. When the AI replies, it uses more tokens. It's like paying for a phone call by the word instead of by the minute. Most casual use costs just a few cents per day.
Anthropic and OpenAI require you to add payment details and purchase credits before using their APIs. Log into your provider's billing page and add $5–10 of credits to get started. Alternatively, use the Nous Portal option (hermes setup --portal) which has its own pricing model.
You're trying to run the Linux/WSL2 installer in a regular Windows PowerShell window. For native Windows, use the PowerShell command with iex (irm ...) instead. For WSL2, make sure you're typing the command inside the Ubuntu window, not PowerShell.
The installer downloads around 200 MB of files. If your connection dropped mid-way, just run the installer command again — it will pick up where it left off.
Read each red item carefully — hermes doctor usually tells you exactly what's wrong and how to fix it. The most common red item is a missing API key. If you're stuck, run hermes setup to go through the configuration wizard again.
If you're using a local AI model (one that runs on your computer instead of the cloud), performance depends on your hardware. With 8 GB RAM, responses may take 10–30 seconds. Adding a GPU speeds this up significantly. Switching to a cloud model like Claude or GPT-4 via API will be much faster on low-end hardware.
Run hermes doctor and screenshot the output. Then open a GitHub issue at github.com/NousResearch/hermes-agent/issues — the team is active and usually responds within a day.
Next Steps
You've got Hermes running. Here's what to explore next:
- Explore tools — Run
hermes toolsto see what Hermes can do beyond basic chat (web search, file reading, and more) - Try the visual interface — Run
hermes --tuifor a cleaner, easier-to-read experience - Set up messaging — Hermes can connect to Telegram or Discord so you can chat with it from your phone
- Keep it updated — Run
hermes updateregularly to get new features and bug fixes - Not sure which model to use? — Read our plain-English model comparison guide to find the right local model for your hardware
InstallWizard AI is adding new guides every week — Ollama, Home Assistant, Plex, and more. Sign up below to get notified.
Glossary
All the technical terms used in this guide, explained in plain English.
.env. Used to keep sensitive things like API keys out of code that might accidentally get shared.localhost or 127.0.0.1) that refers to your own computer. When an app runs a web interface "on localhost," it means it's running on your machine only — nobody on the internet can access it.hermes tools.