How to Setup Hermes Agent on Your PC (Step By Step Guide)

Hermes is a powerful AI agent, but most guides skip the part that actually matters — how to run it without slamming into API rate limits or paying for every single request. In this tutorial, you’ll learn how to setup Hermes Agent on both Windows and Mac, connect it to OpenRouter, and configure it so you can use it freely without constantly hitting AI model usage caps. No unnecessary theory — just the exact steps to get it running on your PC today.

Table of Contents

Windows Setup

01. Download & Install Hermes Agent

Desktop app by Nous Research — requires Windows 10/11 x64.

Go to the Hermes Agent GitHub Releases page and download the latest .exe installer for Windows:

https://github.com/NousResearch/hermes-agent/releases/latest

Download the file named Hermes-Agent-Setup-x.x.x.exe → run it → follow the installer → launch Hermes from the Start menu.

Note
Alternatively, use winget in PowerShell: winget install NousResearch.HermesAgent (if available in the registry).

Important
Context Window Requirement: Hermes Agent requires a model with at least 64,000 tokens of context. The OmniRoute combo you create in Step 4 must use 64K+ models. This guide covers that.

02. Install Node.js & OmniRoute

OmniRoute is the AI gateway that Hermes will route through.

Open PowerShell and run:

# Step 1: Verify Node.js is installed (v18+ required)
PS > node --version

# Step 2: Install OmniRoute globally
PS > npm i -g omniroute

Note
No Node.js? Download from nodejs.org (v18 or higher). After installing, restart PowerShell and re-run the npm command.

03. Start the OmniRoute Server

Keep this terminal open — it must run in the background.

PS > omniroute

Warning
Do not close this window. OmniRoute must keep running. Open a new PowerShell window for all next steps.

Open your browser and visit the dashboard:

http://localhost:20128/home

04. Add AI Providers in OmniRoute Dashboard

Must include at least one provider with 64K+ context models.

In the dashboard → Providers → add the following. The ones marked ✅ are required for Hermes (64K+ context):

Important
Critical for Hermes: Every model in your combo must have at least 64K ctx. Providers with only 16K models (e.g., base Ollama with small models) will cause Hermes to fail. Use Antigravity or OpenRouter as primary providers.

05. Create Hermes Combo (64K+ Context Required)

Dashboard → Combos → Create New Combo

Go to Combos in the dashboard → Create New Combo. Use only models with 64K+ context and name it omni-channel-combo:

claude-sonnet-4-6   ← Priority 1 (200K ctx ✅) via Antigravity
    ↓
gpt-4o              ← Priority 2 (128K ctx ✅) via OpenRouter
    ↓
deepseek-chat       ← Priority 3 (64K ctx ✅) via OpenRouter
    ↓
auto/best-coding    ← or use auto — OmniRoute picks best 64K+ model
    ↓
Combo Name: omni-channel-combo

Recommended models (all 64K+ context):

Model	Context	Provider
claude-sonnet-4-6	200K	Antigravity / OpenRouter
claude-opus-5	200K	Antigravity / OpenRouter
gpt-4o	128K	OpenRouter
gemini-2.0-flash	1M	OpenRouter
deepseek-chat	64K	OpenRouter
auto/best-coding	64K+	OmniRoute Auto

Tip
You can also set the combo model to auto/best-coding — OmniRoute will automatically score and route to the best 64K+ capable provider it has configured.

06. Create an OmniRoute API Key

This is the token Hermes Agent will use to authenticate.

In the OmniRoute dashboard → API Keys in the left sidebar → Create API Key → name it hermes-agent → select All Permissions → copy the key.

http://localhost:20128/dashboard/api-manager

Tip
Your key looks like sk-xxxxxxxxxxxxxxxx-xxxxxxxxx. Keep it safe — you’ll paste it into Hermes settings in the next step.

07. Configure Hermes Agent — Add OmniRoute Endpoint

Settings → Providers → Custom Endpoints → New Endpoint

Open Hermes Agent → click the ⚙ Settings gear (bottom-left) → Providers → Custom Endpoints → click “+ New Endpoint” (or Edit if one already exists) and fill in these exact values:

Field	Value to Enter
Name	omni-routeAny friendly name for your reference
Provider ID	omni-channel-comboMust match the combo name you created in Step 5
Endpoint URL	http://localhost:20128/v1OmniRoute local server — always include /v1
Default Model	auto/best-codingOr your combo name: omni-channel-combo
Context	131072⚠️ CRITICAL — must be 64000 or higher. We recommend 131072 (128K)
API Key	sk-your-omniroute-keyPaste the key you copied in Step 6

Important
Context must be 64000+. If you enter a value below 64K (e.g. leaving it at 16000), Hermes will refuse to start with the error: “Model has a context window below the minimum 64,000 required by Hermes Agent.” Set it to 131072.

After filling everything in, click Save then click “✦ Use” to activate this endpoint.

omni-route
http://localhost:20128/v1
auto/best-coding  ${HERMES_CUSTOM_OMNI_CHANNEL_COMBO_API_KEY}

08. Set the API Key as Environment Variable (Optional)

For secure key management instead of storing in app settings.

Hermes Agent reads the key from HERMES_CUSTOM_OMNI_CHANNEL_COMBO_API_KEY. Set it permanently in Windows:

[System.Environment]::SetEnvironmentVariable("HERMES_CUSTOM_OMNI_CHANNEL_COMBO_API_KEY", "YOUR_TOKEN_HERE", "User")

Note
Replace YOUR_TOKEN_HERE with your actual OmniRoute API key. Restart Hermes Agent after setting this. If you prefer, you can skip this step and just paste the key directly in the API Key field in Step 7.

09. Test the Connection

Verify OmniRoute is reachable from Hermes.

In Hermes Settings → Custom Endpoints → click “✦ Test” on your omni-route endpoint. You should see a green checkmark.

Also verify OmniRoute is running and reachable from PowerShell:

curl http://localhost:20128/health
# Should return: {"status":"ok"}

Warning
If the test fails, make sure OmniRoute is still running in Window 1 (Step 3). If you closed that window, re-run omniroute in a new PowerShell window first.

10. Launch Hermes Agent — Start a New Session

Final step — create a new session and start prompting!

In Hermes Agent → click “+ New session” in the left sidebar → type your first message and send. Hermes should respond without any “agent init failed” errors.

Tip
Monitor live traffic: open http://localhost:20128/home in your browser while chatting to see real-time provider routing, token usage, and cost tracking.

Quick Reference — Hermes + OmniRoute (Windows)

PowerShell Window 1 — Start OmniRoute:

npm i -g omniroute
omniroute

Hermes App — Settings → Providers → Custom Endpoints:

Name:          omni-route
Provider ID:   omni-channel-combo
Endpoint URL:  http://localhost:20128/v1
Default Model: auto/best-coding
Context:       131072  ← MUST be 64000+
API Key:       sk-your-omniroute-key

macOS Setup

01. Download & Install Hermes Agent

Desktop app by Nous Research — requires macOS 12+ (Apple Silicon or Intel).

Go to the Hermes Agent GitHub Releases page and download the latest .dmg file for macOS:

https://github.com/NousResearch/hermes-agent/releases/latest

Download Hermes-Agent-x.x.x.dmg → open it → drag Hermes to Applications → launch from Spotlight (⌘Space → “Hermes”).

ℹ️ Note
On first launch macOS may show “unidentified developer”. Go to System Settings → Privacy & Security → click Open Anyway next to the Hermes entry.

🚨 Important
Context Window Requirement: Hermes Agent requires a model with at least 64,000 tokens of context. The OmniRoute combo you create in Step 4 must use 64K+ models. This guide covers that.

02. Install Node.js & OmniRoute

OmniRoute is the AI gateway that Hermes will route through.

Open Terminal (or iTerm2) and run:

# Check Node.js version (v18+ required)
$ node --version

# Install OmniRoute globally
$ npm i -g omniroute

ℹ️ Note
If you get permission errors, use nvm (recommended): curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash then nvm install 20 && nvm use 20.

03. Start the OmniRoute Server

Keep this terminal tab open — it must run in the background.

$ omniroute

⚠️ Warning
Do not close this tab. Open a new Terminal tab (⌘T) for all next steps.

Open your browser and visit the dashboard:

http://localhost:20128/home

04. Add AI Providers in OmniRoute Dashboard

Must include at least one provider with 64K+ context models.

In the dashboard → Providers → add the following. The ones marked ✅ are required for Hermes (64K+ context):

🚨 Important
Critical for Hermes: Every model in your combo must have at least 64K ctx. Providers with only 16K models will cause Hermes to fail. Use Antigravity or OpenRouter as primary providers.

05. Create Hermes Combo (64K+ Context Required)

Dashboard → Combos → Create New Combo

Go to Combos → Create New Combo. Use only 64K+ models. Name it omni-channel-combo:

claude-sonnet-4-6   ← Priority 1 (200K ctx ✅) via Antigravity
    ↓
gpt-4o              ← Priority 2 (128K ctx ✅) via OpenRouter
    ↓
deepseek-chat       ← Priority 3 (64K ctx ✅) via OpenRouter
    ↓
auto/best-coding    ← or use auto — OmniRoute picks best 64K+ model
    ↓
Combo Name: omni-channel-combo

Model	Context	Provider
claude-sonnet-4-6	200K	Antigravity / OpenRouter
claude-opus-5	200K	Antigravity / OpenRouter
gpt-4o	128K	OpenRouter
gemini-2.0-flash	1M	OpenRouter
deepseek-chat	64K	OpenRouter
auto/best-coding	64K+	OmniRoute Auto

06. Create an OmniRoute API Key

This is the token Hermes Agent will use to authenticate.

In the OmniRoute dashboard → API Keys → Create API Key → name it hermes-agent → All Permissions → copy the key.

http://localhost:20128/dashboard/api-manager

💡 Tip
Your key looks like sk-xxxxxxxxxxxxxxxx-xxxxxxxxx. You’ll paste this in Hermes settings next.

07. Configure Hermes Agent — Add OmniRoute Endpoint

Settings → Providers → Custom Endpoints → New Endpoint

Open Hermes Agent → ⚙ Settings (bottom-left) → Providers → Custom Endpoints → “+ New Endpoint” → fill in:

Field	Value to Enter
Name	omni-routeAny friendly name for your reference
Provider ID	omni-channel-comboMust match the combo name you created in Step 5
Endpoint URL	http://localhost:20128/v1OmniRoute local server — always include /v1
Default Model	auto/best-codingOr your combo name: omni-channel-combo
Context	131072⚠️ CRITICAL — must be 64000 or higher. We recommend 131072 (128K)
API Key	sk-your-omniroute-keyPaste the key you copied in Step 6

🚨 Important
Context must be 64000+. If below 64K, Hermes will fail with: “Model has a context window below the minimum 64,000 required by Hermes Agent.” Always set Context to 131072.

Click Save then click “✦ Use” to activate this endpoint.

08. Set API Key as Environment Variable (Optional)

For secure key management via shell profile.

Hermes reads the API key from the environment variable HERMES_CUSTOM_OMNI_CHANNEL_COMBO_API_KEY. To set it permanently:

# Open zshrc
$ nano ~/.zshrc

# Add this line at the bottom:
export HERMES_CUSTOM_OMNI_CHANNEL_COMBO_API_KEY="YOUR_TOKEN_HERE"

# Save (Ctrl+O, Enter, Ctrl+X) then reload:
$ source ~/.zshrc

ℹ️ Note
Restart Hermes Agent after setting this environment variable so it picks up the new value. This step is optional — you can also just paste the key directly into the API Key field in Step 7.

09. Test the Connection

Verify OmniRoute is reachable from Hermes.

In Hermes Settings → Custom Endpoints → click “✦ Test” on the omni-route endpoint. Also run a quick health check from Terminal:

$ curl http://localhost:20128/health
# Expected response: {"status":"ok"}

⚠️ Warning
If the test fails, make sure OmniRoute is still running in Tab 1. If closed, re-run omniroute in a new Terminal tab.

10. Launch Hermes Agent — Start a New Session

Final step — create a new session and start prompting!

In Hermes Agent → “+ New session” → type your message → send. Hermes should respond without any context window errors.

Hermes Agent → OmniRoute → omni-channel-combo

Hermes is now routing through your local OmniRoute server with auto-fallback across Claude Sonnet → GPT-4o → DeepSeek → any 64K+ model. Context set to 131K — fully operational.

Quick Reference — Hermes + OmniRoute (macOS)

Terminal Tab 1 — Start OmniRoute:

npm i -g omniroute
omniroute

Hermes App → Settings → Providers → Custom Endpoints:

Name:          omni-route
Provider ID:   omni-channel-combo
Endpoint URL:  http://localhost:20128/v1
Default Model: auto/best-coding
Context:       131072  ← MUST be 64000+
API Key:       sk-your-omniroute-key