🧰 Hermes Agent: a local AI agent that actually works on your machine

Chat vs agent — the one thing to get first

Every model so far has done the same thing: in → text out. An agent adds two ingredients:

• Tools — the model can now act: run a terminal command, read a file, open a web page, write code.
• A loop — act, observe the result, decide the next action, repeat until the job is done.

you → model → "run the test suite" → terminal
            ← "3 passed, 1 failed"   ← observation
            → "fix the import, re-run" → terminal
            ← "4 passed"
            → "done, here's the diff" ← you

That loop — model decides, tool acts, observation comes back — is the whole trick. The loop, formally → The program that hosts the model, the tools, and the loop is called the harness. Harness →

Hermes Agent is an open-source harness from Nous Research. It’s local-first: it can run entirely on models in your machine, or mix local and cloud, and it works in a terminal, a desktop app, or over your chat apps.

Step 1 — Install

Python 3.11+ is the only hard requirement.

Simplest (all platforms):

pip install hermes-agent
hermes setup

Or the installer scripts:

# Linux / macOS / WSL2
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

# Windows (PowerShell)
irm https://hermes-agent.nousresearch.com/install.ps1 | iex

Or from source (if you want to tinker with the code):

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

Then check your install:

$ hermes doctor

The hermes setup wizard is the part most people skip — don’t. It asks what you want: which model, which tools, whether to run a messaging gateway.

Step 2 — Point it at your local model

This is where the previous three tutorials pay off. In the wizard (or later with hermes model), choose a custom / OpenAI-compatible endpoint and give it one of these:

No API key needed, no data leaving the machine. Why local →

Step 3 — Give it a job

Start small, and watch the loop:

$ hermes
> Read the README in this folder and summarize it in 3 bullets

You’ll see it: read the file → think → answer. Now something with more steps:

> Find every .py file here, count the lines in each, and write the result to report.txt

The model now issues several tool calls (list files → read each → write the report) and verifies the outcome. That’s the agent, working.

Tools and guardrails

Hermes ships with a toolbox:

• Terminal — run shell commands (the workhorse)
• Files — read, write, search
• Web — search and extract pages
• Browser — drive a real browser for JS pages, logins, clicks

Two rules make agents pleasant rather than scary:

1. Approvals — destructive or risky commands ask before running. Let the guardrail exist; you can loosen it per-task.
2. Small tasks — give the agent one job at a time (“refactor this function”), not a thesis (“make this app better”). Each step stays inspectable.

Skills and memory — the part that compounds

• Skills are how-to notes the agent loads when a task matches (e.g. “how we deploy this project”). Hermes can even write new skills from work it’s just done, so a procedure you taught once survives into next session.
• Memory holds durable facts (who you are, project conventions) across sessions.

This is the difference between a chatbot you re-explain everything to and a colleague who remembers.

What to honestly expect from a local model

Local 4B–9B models are genuinely useful for: file operations, small refactors, summaries, data wrangling, well-scoped multi-step jobs — especially when you give them clear acceptance criteria. What they’re weak at: long, ambiguous, multi-hour tasks and subtle multi-file refactors. For those, people typically escalate to a bigger local model (27B+) or a cloud model — the rest of the setup stays identical, because the model is just a base URL.

Where this leaves you

You’ve now completed the full local track: engine (Ollama / llama.cpp) → workstation (LM Studio) → interface (Open WebUI) → agent (Hermes). The next track is the opposite philosophy: renting frontier models instead of running them.