The 30-second version, then the depthWhat you're actually installing
Hermes Agent is Nous Research's open-source agent, MIT-licensed, that runs on hardware you control and keeps state between sessions. The video covered the what. This guide is the how — the commands, the files it writes to disk, and the spots where it doesn't do what the hype says. Everything below is checked against the live docs (linked at the bottom). One thing worth knowing before you start: Hermes is a CLI-first tool that stores everything under a single ~/.hermes/ directory. Memory, skills, scheduled jobs, conversation history — all of it lives there as files and one SQLite database you can read, back up, or move to another machine.
- Open-source, MIT-licensed, from Nous Research — runs on your laptop, a VPS, or serverless
- Everything it learns is stored as plain files under
~/.hermes/(skills, memory, cron jobs) plus~/.hermes/state.db - CLI-first, but it connects to chat platforms so you can drive it from your phone
- The 'self-improving' part is real but narrow — it offers to save skills after hard tasks; it does not silently rewrite itself
Two commands, and what each one doesInstall and first run, exactly
The only thing you install by hand is Git. The installer script provisions the rest for you — uv, Python 3.11, Node.js 22 (for browser automation and the WhatsApp bridge), ripgrep, and ffmpeg (for voice). After it finishes you reload your shell once, then run the setup wizard. --portal is the zero-key path: it logs you into Nous Portal over OAuth, which covers 300+ models on a subscription so you don't paste any API keys to get going.
- Linux / macOS / WSL2 / Android (Termux):
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash - Windows (PowerShell):
iex (irm https://hermes-agent.nousresearch.com/install.ps1) - Prefer a desktop app? Download the installer at hermes-agent.nousresearch.com/desktop instead
- Reload your shell:
source ~/.zshrc(orsource ~/.bashrc) - Setup wizard:
hermes setup --portal— OAuth login, picks a model, configures tools - Start chatting:
hermes— that's the running agent in your terminal
hermes isn't found after install, your shell didn't pick up the new PATH — open a fresh terminal or re-run the source line. When something behaves oddly later, hermes doctor checks your config and hermes --continue (or -c) resumes your last conversation instead of starting cold.What a skill is on disk, and what actually triggers oneHow it 'writes its own skills' — the real mechanism
This is the headline feature, so here's what's literally happening. A skill is a folder under ~/.hermes/skills/ (grouped into category subfolders) containing a SKILL.md file: YAML front-matter on top, a Markdown body below. The body uses plain sections like When to Use, Procedure, Pitfalls, and Verification. A skill can ship supporting folders — references/, templates/, scripts/ — that the agent only opens when it needs them. The trigger is human-in-the-loop, not magic: per the docs, after a complex multi-step task, Hermes will often offer to save the approach as a skill. You say yes, it writes the file using its skill_manage tool. Next session, it sees the skill and reuses it instead of figuring the task out again.
| Piece | What it is | Where it lives |
|---|---|---|
SKILL.md | YAML front-matter (name, description, version, tags, category) + Markdown body | ~/.hermes/skills/<category>/<skill>/ |
references/ | API docs / examples the agent reads on demand | inside the skill folder |
templates/ | Config or boilerplate files it fills in | inside the skill folder |
scripts/ | Executable helpers the skill can run | inside the skill folder |
| Progressive load | skills_list() (~3k tokens) at start, then skill_view(name) only when used | in-session, not on disk |
SKILL.md is pulled in only when the agent decides it needs that skill.The commands the wizard doesn't show youManaging skills yourself
You're not stuck with whatever the agent saves. Skills are just files, so you can list, search, browse the official optional ones, install community skills from the hub at agentskills.io, and edit any SKILL.md by hand. When a skill is wrong or out of date, the fix is to tell Hermes what went wrong and ask it to update that skill — it patches the file with what it learned.
- List what you have:
hermes skills list(or/skillsinside a session) - Search by keyword:
/skills search <keyword> - Browse official optional skills:
/skills browse - Install from the hub or a URL:
hermes skills install <path-or-url> - Improve one: in chat, point out where a skill failed and ask Hermes to update it
Two files, one database — and what it deliberately forgetsHow its memory actually works
Hermes splits memory into a small always-on layer and a searchable archive. The always-on layer is two short Markdown files in ~/.hermes/memories/: MEMORY.md (the agent's own notes — environment facts, conventions, lessons) and USER.md (your profile — preferences, communication style). The memory docs cap them deliberately small — MEMORY.md around 2,200 characters (~800 tokens) and USER.md around 1,375 characters (~500 tokens) — and inject them into the system prompt as a frozen snapshot at session start (the docs' phrasing: the injection is captured once at session start and never changes mid-session). The archive is your full conversation history in ~/.hermes/state.db, a SQLite database the agent searches with the session_search tool (FTS5 full-text search) when it needs something you discussed weeks ago. It saves proactively, but it's opinionated about what's worth keeping — it skips trivia, raw data dumps, and one-off session noise.
| Layer | File / store | Size or behavior | Loaded how |
|---|---|---|---|
| Agent notes | ~/.hermes/memories/MEMORY.md | ~2,200 chars (~800 tokens), per docs | Frozen snapshot into system prompt at session start |
| User profile | ~/.hermes/memories/USER.md | ~1,375 chars (~500 tokens), per docs | Frozen snapshot into system prompt at session start |
| Conversation archive | ~/.hermes/state.db (SQLite) | Full history, FTS5 indexed | On demand via session_search |
write_approval key under memory: — set it to true and review staged writes with /memory pending, then /memory approve <id> (or /memory reject <id>). Because the snapshot is frozen at session start, a fact it just saved mid-session may only fully take effect next session.The gateway and a real cron jobPut it on your phone (and on a schedule)
Two things turn Hermes from a terminal toy into something that works while you sleep: the messaging gateway and cron. The gateway connects it to a chat platform — Telegram, Discord, Slack, WhatsApp, Signal, Email, Microsoft Teams, Home Assistant. Message it from your phone, it wakes, runs the task, and replies (voice or text). Cron runs a stored prompt on a schedule and delivers the result to a channel. The schedule field is flexible: a relative delay (30m), an interval (every 2h), a standard 5-field cron expression, or an ISO timestamp.
- Connect a channel:
hermes gateway setup— then pick Telegram (or any of the others) - Pick the brain:
hermes model— Nous Portal (zero-key) or OpenAI / Anthropic / OpenRouter with your own key - Schedule a daily brief:
hermes cron create "0 8 * * 1-5" "Summarize my overnight email and GitHub notifications" --deliver telegram - See what's scheduled:
hermes cron list· trigger one now:hermes cron run <name>· remove:hermes cron remove <name>
~/.hermes/cron/output/ even when delivery is set, so you have a local record.The honest limitsWhere it falls short (so you're not surprised)
The marketing around self-improving agents runs ahead of the docs, so here's the grounded version. The skill-creation loop is genuinely useful but it is assisted, not autonomous in the way clips imply: Hermes offers to save a skill after a hard task and you accept it, and stale skills are your job to fix — the docs are explicit that unmaintained skills 'become liabilities,' not that the agent silently retires them for you. It also gives terminal and code-execution tools real power on your machine, so treat tool permissions like you would SSH access. And because it runs on your own infra, uptime, backups, and the model bill are on you — there's no managed SLA behind it.
- Skill creation is human-in-the-loop — it suggests, you confirm; it doesn't rewrite itself unprompted
- Skill upkeep is manual — out-of-date skills stay wrong until you tell it to fix them
- It can run terminal commands and execute code locally — scope tool access deliberately
- Self-hosted means self-operated: you own uptime, backups (
~/.hermes/), and the model spend
Running it vs. selling itIf you build one good agent, here's the part nobody tells you
Once Hermes is answering your phone and running your morning brief, the obvious next thought is: a small business owner would pay for this and never set it up themselves. That's a real gap, and it's a different job from building. Selling agent access means giving each client their own login, metering what they use, putting your brand on it, and billing them — none of which Hermes itself does. That's the layer Knotie handles: a white-label platform where you stand up AI voice and chat agents (Retell, LiveKit, VAPI, Ultravox) plus automations for clients under your own domain, with a customer portal and credit-based billing. It also includes an OpenAI-compatible AI gateway — point the standard OpenAI SDK at a new base_url, hand each client a metered virtual key locked to specific models, add your markup, and the usage bills back to you. Hermes teaches you the craft of running an agent; this is how you'd charge for it.
Get the next drop
New AI build guides + the occasional bonus template. No spam, unsubscribe anytime.
By submitting you agree to our Privacy Policy & Terms. Unsubscribe anytime.
Frequently asked questions
Do I have to pay for a model, or is Hermes really free?
hermes setup --portal, which uses Nous Portal's subscription (300+ models, no API keys to paste). Or run hermes model and plug in your own OpenAI, Anthropic, or OpenRouter key and pay that provider directly.What does the install actually put on my machine?
uv, Python 3.11, Node.js 22 (browser automation and the WhatsApp bridge), ripgrep, and ffmpeg. Everything Hermes itself learns later lives under ~/.hermes/ — skills, memory, cron jobs — plus ~/.hermes/state.db for conversation history.How does it decide to write a skill — is that automatic?
SKILL.md (YAML front-matter + a Markdown body with When to Use / Procedure / Pitfalls / Verification) under ~/.hermes/skills/. It won't secretly rewrite its own behavior without you confirming.Can I edit or fix a skill it wrote?
SKILL.md and edit it. The lighter path is to tell Hermes in chat where a skill went wrong and ask it to update it; it patches the file. There's no auto-curator, so keeping skills current is on you — the docs warn that unmaintained skills become liabilities.Does it remember things between sessions, and where does that live?
~/.hermes/memories/ (MEMORY.md for the agent's notes, USER.md for your profile) load into every session as a frozen snapshot. Older conversations live in ~/.hermes/state.db (SQLite) and are searched on demand with FTS5 full-text search. Because the snapshot is frozen at session start, a fact saved mid-session may not fully apply until the next one.How do I run a scheduled job and send the result to Telegram?
hermes gateway setup, then create the job: hermes cron create "0 8 * * 1-5" "<your task>" --deliver telegram. Schedules accept relative delays (30m), intervals (every 2h), 5-field cron, or ISO timestamps. Manage jobs with hermes cron list / run / remove.Is there a minimum model requirement?
How risky is it to give it terminal and code-execution tools?
hermes tools (including per-platform presets like hermes-telegram), so a phone channel doesn't get the same powers as your local CLI session. Start narrow and widen as you trust it.