Run Your Own Hermes Agent

Hermes is a capable, open-source AI agent — it can search the web, remember things, work with files and data, and run tools on your behalf. It's the same engine behind the Launch Your Agent option in your dashboard. This guide is the do-it-yourself path: install Hermes on your own machine or server, point it at an AI model, and you've got your own agent — free, and entirely yours. 🦒

What you'll need

• A computer or server you can run commands on — Linux or macOS works best (a small cloud VM is perfect).
• About 15 minutes and basic comfort with a terminal.
• An AI model key. We recommend OpenRouter — one key gives you access to dozens of models, and you only pay for what you use. You can also use your own OpenAI, Anthropic, or Google key if you have one.

Step 1 — Install uv

Hermes uses uv to manage its Python environment. Install it with one line:

curl -fsSL https://astral.sh/uv/install.sh | sh

Close and reopen your terminal afterward so uv is on your path.

Step 2 — Get Hermes

Clone the project and install it:

git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent
uv venv venv --python 3.11
uv pip install -e '.[all]'

The [all] part matters — it pulls in everything (web search, tools, and memory support) so your agent has its full toolkit from the start.

Step 3 — Connect an AI model

We've had the best results with Qwen3 235B through OpenRouter — it's smart, fast, and inexpensive — so that's what we run for hosted agents. Grab an API key from your OpenRouter account, then point Hermes at it.

Set your key as an environment variable:

export OPENAI_API_KEY="sk-or-...your OpenRouter key..."

And in your Hermes config.yaml, use a custom (OpenAI-compatible) provider pointed at OpenRouter:

provider: custom
base_url: https://openrouter.ai/api/v1
key_env: OPENAI_API_KEY
default_model: qwen3-235b-a22b-2507

Step 4 — Talk to your agent

From the hermes-agent folder, start a chat:

uv run hermes

That's it — you've got a running agent. Ask it to search the web, summarize a page, or help with a task, and it'll use its tools to get it done.

Make it smarter (optional)

• Give it a memory. gbrain is a free, open-source memory layer that plugs into Hermes so your agent remembers context across sessions. Install it with bun install -g github:garrytan/gbrain and connect it as a tool.
• Add more tools. Hermes supports the Model Context Protocol (MCP), so you can bolt on extra capabilities — file access, fetching, time, and more — by adding MCP servers to your config.

Keeping it running

Running Hermes on your laptop is great for trying it out. To keep an agent online around the clock, run it on a small always-on server (a cheap cloud VM works) and start it as a background service. Maintaining a server, securing it, and keeping the model topped up is the part most people would rather not deal with — which is exactly why we offer the hosted option.