What Hermes Agent actually is

In this module — the 30-second definition, the one idea (an agent is a loop), what makes Hermes different, the design rule that explains everything, and getting it running in five minutes.

The 30-second definition

Hermes Agent is an open-source, self-hosted AI agent built by Nous Research. You run it yourself — on your laptop, a $5 VPS, or serverless infra — point it at any language model you like, and it can use tools, remember you across sessions, run on a schedule, and live inside Telegram or Discord instead of being trapped in one chat window.

It's released under the MIT license (see LICENSE in the repo), which is the permissive kind: you can read it, fork it, build a product on it, and ship that product commercially. That's the whole reason this tutorial exists — it's genuinely yours to build on.

If you've used these… Think of the tools you already know. ChatGPT is a model behind a chat box. Claude Code / Cursor are agents wired to your code editor. Hermes Agent is closest to those coding agents — a model in a loop with tools — but it's provider-neutral, self-hosted, and built to live anywhere you do, not just in an IDE. (We compare it to Claude Code in detail in the handbook.)

The one idea: an agent is a loop

A plain chatbot does one thing: you send text, it sends text back. Done. An agent adds a loop. The model can call a tool (run a command, read a file, search the web), see the result, and then decide what to do next — over and over — until the job is finished. Then it talks to you.

You: "What changed in this repo today?"
        |
        v
  +-------------------------------------------+
  |  THE LOOP                                 |
  |                                           |
  |   model thinks  -->  calls a tool (git)   |
  |       ^                      |            |
  |       |     sees the result  <--          |
  |       +------- loops again -------+       |
  |                                           |
  |   ...until it has the answer              |
  +-------------------------------------------+
        |
        v
Hermes: "3 commits today: ..."

That's it. That's the secret at the heart of every "AI agent." Everything else in the Hermes codebase — tools, skills, memory, the messaging gateway — is in service of making that loop more capable, safer, and able to remember. We trace the real loop line-by-line in Module 2.

Why this matters for you — when you want to extend Hermes, you're almost always doing one of two things: giving the loop a new tool to call, or giving the model better instructions (a skill) about when to call things. Hold that thought — it's the spine of Modules 3 and 4.

What makes Hermes different

There are lots of agent frameworks. The repo's README leads with a few design choices that genuinely set Hermes apart — and each one is a thing you can build on:

The most important design rule

Open the repo's AGENTS.md (its internal architecture bible) and you'll find a philosophy that will save you a lot of confusion. Paraphrased:

The "narrow waist" principle — "The core is a narrow waist; capability lives at the edges. Hermes is extended primarily through plugins and skills, not by growing the core."

In plain terms: the central agent loop is meant to stay small and stable. New abilities are supposed to be added around it — as skills, CLI commands, plugins, or MCP servers — not by hacking the middle. There's even a "Footprint Ladder" for choosing the lightest way to add something, which is the entire subject of our final module. For now, just internalize the vibe: you extend Hermes at the edges, and the edges are designed to be extended.

Get it running (5 minutes)

You learn an agent by talking to it. Here's the officially documented install (Quickstart docs). Pick your OS.

macOS / Linux / WSL2:

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
source ~/.bashrc          # reload your shell (or ~/.zshrc)

Windows (native, PowerShell):

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

The installer is self-contained — it brings its own Python 3.11, Node, ripgrep, ffmpeg, and (on Windows) a portable Git Bash, so it won't disturb anything you already have. Then:

hermes setup        # one-time wizard: pick a provider + model
hermes              # start chatting in the terminal UI

Fastest path to a key — Hermes works with any provider, but collecting five separate API keys (model, search, images, TTS, browser) is annoying. hermes setup --portal logs you in to Nous Portal via OAuth and covers all of them under one subscription. Or point it at a free local model with Ollama for zero API cost while you learn.

Try these three things

Once you're in, you're not just chatting — you're driving the loop. Try:

• Summarize the files in my current folder — watch it call a tool, read the result, then answer. That's the loop.
• /tools — see the toolbox the model is allowed to reach for (Module 3).
• /skills — see the procedural knowledge it can load on demand (Module 4).

Where everything lives

Two locations matter, and keeping them straight prevents 90% of beginner confusion:

Inside ~/.hermes/ you'll meet these again throughout the series: config.yaml (settings), .env (secrets), memories/ (Module 5), skills/ (Module 4), cron/ (Module 6), and state.db (the SQLite database of every conversation).

Key takeaways

• An agent is a loop: think → call a tool → see the result → repeat → answer.
• Hermes is self-hosted, model-neutral, MIT-licensed, and built to live on many platforms.
• Its standout trait is a self-improving learning loop (skills + memory).
• You extend it at the edges (skills, tools, plugins, MCP), not by growing the core.
• The repo = the program; ~/.hermes/ = your data and your extensions.

Quick check — A friend says "Hermes is just a wrapper around ChatGPT." What's the most important correction?

Answer: Two things. (1) It's not tied to one model — it's provider-neutral and runs on local/open models with no code change. (2) More fundamentally, it's not a chat wrapper at all — it's a loop that calls tools and acts, with memory and scheduling. The chat box is just one of several ways to talk to it.

Pair with your AI — this whole tutorial assumes you'll be working alongside an AI assistant. Clone the repo and let it read the real files with you. Try: "I cloned github.com/NousResearch/hermes-agent. Give me a guided tour of the top-level folders (agent/, tools/, skills/, gateway/, cron/) — one sentence each. I'm a product builder, keep it conceptual."