Hermes Agent is the open source agent from Nous Research that lives on your machine, remembers what it learns, and writes its own skills. Here is the full setup: install, the big name model connections, and the free route through Ollama.
Most AI agents are a subscription wearing a trench coat. Hermes Agent is the other kind: an open source agent from Nous Research, MIT licensed, that runs on your own machine or server and keeps its memory, its skills, and its history in a folder you control. Its signature trick is a learning loop. After a complex task it writes itself a skill file describing what worked, refines those skills as it reuses them, and searches its own past sessions when a new job smells familiar. The agent stays constant; the brain is swappable. This tutorial installs it, connects it to the big name models first, then shows the cheap and free route through Ollama. The project lives on GitHub under NousResearch/hermes-agent, with documentation on the Hermes Agent site.
What you need
Almost nothing. Git is the only prerequisite; the installer handles Python, Node, and the rest itself, and the agent takes about 2GB of disk. It runs on Linux, macOS, WSL2, and even Android through Termux. Windows users get a desktop installer and a PowerShell route, though WSL2 remains the supported path for the full terminal experience. A GPU is optional and only matters for the local model route at the end.
Step 1: Install
One line on Linux, macOS, or WSL2, using the installer script from the project repository:
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
source ~/.bashrc
On Windows, the quickstart offers a desktop installer, which sets up the app and the command line tools together, plus a PowerShell installer command for terminal purists. Prefer a package manager? pip install hermes-agent followed by hermes postinstall gets you the same place. Everything Hermes owns lives in ~/.hermes: config.yaml for settings, .env for secrets, and the memory and skill files the agent maintains.
Step 2: Connect a big name brain
Run hermes setup and you get three doors: Quick Setup through a Nous Portal subscription, Full Setup where you bring your own keys, and Blank Slate, which starts with the bare minimum of tools enabled. The fastest first run is the Portal:
hermes setup --portal
That opens your browser for a Nous sign in, stores the token at ~/.hermes/auth.json, and gives you the Portal catalog of 300 plus models plus its Tool Gateway for web, image, and browser work. One subscription, every frontier model, no key juggling.
Bringing your own keys instead? Run hermes model and pick from the provider list. The headline routes:
- Anthropic. Claude direct, through Claude Code sign in or an API key.
- OpenAI. The Codex model line through a device code sign in.
- Google. Gemini, including the huge context builds.
- OpenRouter. One key, 200 plus models, useful if you want everything behind a single bill.
- DeepSeek, xAI, Kimi, MiniMax, and friends are also on the list for cheaper frontier class runs.
Nous publishes its own picks for agent work, and they are sensible defaults to start from. Switch models mid session with the /model command:
/model anthropic/claude-sonnet-4.6
/model openai/gpt-5.5-pro
/model google/gemini-3-pro-preview
/model deepseek/deepseek-v4-pro
Claude Sonnet is their best general purpose agent pick, GPT Pro is the reasoning heavyweight, Gemini brings the giant context window, and DeepSeek is the budget coder. Start the agent with hermes (or hermes --tui for the terminal interface) and give it a testable first job, something like asking it to inspect your current folder and name the project it finds. If it chats and calls a tool, the core is alive.
Step 3: Put it in your pocket
The gateway is one process that connects the same agent to the chats you already live in: Telegram, Discord, Slack, WhatsApp, Signal, and email.
hermes gateway setup
hermes gateway start
Set an allowlist while you configure it, because an agent that answers anyone who messages it is a liability, not an assistant. On a server, hermes gateway install registers it as a service so it survives reboots. From here the same slash commands work from your phone as from the terminal, and the built in scheduler can deliver cron job results straight into chat. When anything behaves strangely, hermes doctor is the first command the docs will tell you to run, and hermes update keeps the install current.
The cheap seats: free with Ollama
Everything above costs money per token or per month. This route costs electricity. Hermes treats a local Ollama server as a custom endpoint, so the whole setup is three moves.
Move one: install Ollama and pull a model. Grab Ollama from its official site (the Linux route is a one line install script), start it, then pull a model:
ollama pull qwen2.5-coder:32b
That 32B coder is the model the official Hermes docs use as their example, and it earns the spot: agent work is tool calling, and the Qwen coder line calls tools reliably. Nous also ships its own Hermes line for local use, and the current model rankings in our uncensored LLMs guide are a good map of what else is worth pulling.
Move two: fix the context trap. This is the step everyone misses, and the docs call it the number one source of confusion. Hermes refuses to run agent work on less than 64,000 tokens of context, and Ollama quietly defaults far below that: 4,096 tokens on machines with under 24GB of VRAM. The context cannot be raised through the API, so set it on the server before you start it:
OLLAMA_CONTEXT_LENGTH=64000 ollama serve
Move three: point Hermes at it. Run hermes model, choose the custom endpoint option, enter the local address http://localhost:11434/v1, skip the API key, and name your pulled model. Prefer editing files? The same thing in ~/.hermes/config.yaml is provider: custom with that base URL. Verify with ollama ps and check the CONTEXT column shows your 64,000, then start hermes and repeat the folder inspection test.
How much machine does free actually take? Rough planning numbers for 4 bit weights plus that mandatory long context:
RAM to plan on, by local model size
Approximate planning figures for 4 bit weights with 64K context loaded. CPU inference works; a GPU is what makes it pleasant.
The honest trade: a local 32B is a weaker agent than Claude or GPT at their best, slower and occasionally clumsier with tools. What it never does is send your files anywhere, meter your curiosity, or change its price in March. A pattern that works well: set Hermes up on a frontier model first so you learn what good looks like, then move the routine jobs to the local brain.
Make it yours, keep it leashed
Two folders do the personalizing. Memory lives in ~/.hermes as compact files the agent curates itself, and skills live in ~/.hermes/skills, where you will find the ones it writes for you after hard tasks. The /learn command turns almost anything into a skill on demand: a docs page, a folder of notes, a deployment you just finished by hand. Read the skills it writes the way you would read a junior colleague’s runbook, because that is exactly what they are.
And the leash matters, because this is an always on process with shell access. Hermes ships approval modes for risky commands and a hard blocklist for irreversible ones. Start in Blank Slate if you want the cautious build, keep gateway allowlists tight, and consider moving command execution into a container with hermes config set terminal.backend docker. An agent that improves itself is a wonderful tool. An agent that improves itself with your production credentials lying around is a story you tell other people as a warning.
Setup commands, provider routes, and the Ollama context requirement checked against the official Hermes Agent documentation and repository, October 2026.
END OF TRANSMISSION
Stay curious. Question everything.
