Nous Hermes Agent Tutorial: Self-Host the Open-Source Coding Agent (2026)

Introduction

Claude Code proved that developers want an agent that edits real code, runs real commands, and keeps working while they get coffee. Nous Research’s Hermes Agent is the open-source answer to that idea: an MIT-licensed, model-agnostic agent you can install with one command and run on your own machine, your own VPS, or your company’s servers. This tutorial walks the full self-hosting loop. You will install Hermes, choose a model (including a fully local Ollama model that keeps every token on your hardware), put the agent on messaging apps through its gateway, and learn the five real problems the community has already hit, with fixes taken from the project’s own issue tracker. It is written for developers and technical operators who want a coding agent they can inspect, modify, and keep.

Quick answer

To self-host Nous Research’s Hermes Agent, run the one-line Linux installer from the official docs, then launch it with hermes. Pick any model with hermes model, including Ollama endpoints on your own hardware, and manage secrets in ~/.hermes/.env.

Evidence

The timing of this tutorial is not accidental. On October 7, 2026, TechCrunch confirmed that Nous Research had closed a $90 million Series B at a $1.5 billion valuation, led by Robot Ventures with participation from Nvidia, Union Square Ventures, Menlo Ventures, Samsung, and 1789 Capital, bringing the three-year-old startup’s total funding to $158 million. The same report puts numbers on the agent’s reach: the company estimates Hermes has been cloned more than 24 million times and drives roughly 2.5% of global AI token usage. Those are company estimates, not independent measurements, but they explain why the open-source agent has become infrastructure rather than a demo. The Wall Street Journal, cited by TechCrunch, reported that Nous was at roughly $36 million in annualized revenue by mid-September 2026 and expects to pass $100 million before the end of 2026, a company forecast rather than realized revenue.

On the code side, the project lives at the official Hermes Agent repository, MIT-licensed since its February 2026 release. ToolPilot observed more than 250,000 GitHub stars on the repository page on October 10, 2026. The project’s own framing is ambitious: the README calls it “The self-improving AI agent built by Nous Research,” and the company states its mission as “We are on a mission to create and proliferate open access to intelligence.” The Series B money is aimed at the enterprise tier: “Hermes for Businesses,” allowing companies to deploy customized AI agents that can handle multi-step workflows while keeping their data private and secure. If you are choosing between agents, note the honest contrast. Our Claude Code MCP setup guide covers Anthropic’s proprietary agent, which is tied to Claude models. Hermes is the model-agnostic, self-hostable alternative: it runs on Nous Portal, OpenRouter, OpenAI, Anthropic, DeepSeek, xAI, or your own local endpoint, and it keeps the same skills, memory, and tool access whether it drives a cloud model or a model running on your laptop. One more data point for the n8n side of the world: Hermes ships an ACP server for IDE integration (VS Code, Zed, JetBrains), so it slots into the same editor workflows where n8n and Claude Code already meet.

Prerequisites

• A machine running Linux, macOS, Windows, or WSL2. For the agent paired with a hosted model API, a small VPS is enough. For fully local models, see the hardware note in Step 3.
• An LLM provider API key (OpenRouter is the simplest single key covering many providers), or a local model served by Ollama.
• Basic comfort with the terminal: you will run installer commands and edit a config file.
• Optional: a Telegram or Discord bot token if you want the messaging gateway in Step 4.

Step-by-step guide

Step 1: Install Hermes with the one-line installer

On Linux, macOS, or WSL2, the official README documents a single install command: a curl pipe to bash against the project’s install script on the official docs domain.

On native Windows, open PowerShell and run the documented irm/iex equivalent from the same install page.

After installation, reload your shell configuration (source ~/.bashrc or source ~/.zshrc), then type hermes to start an interactive conversation. ToolPilot verified the Linux installer URL returns HTTP 200 on October 10, 2026. If the installer is killed partway on a small VPS, do not rerun it blindly: see Troubleshooting issue 1, because the cause is usually memory, not a bad download.

Step 2: Run the setup wizard and choose your model

First launch the full setup wizard:

hermes setup

The wizard walks through provider selection and credentials. There is also a one-command OAuth path for Nous’s own hosted option:

hermes setup --portal

Model choice is where Hermes earns its keep. Run hermes model any time to switch providers and models with no code changes and no lock-in, exactly as the README promises: “Use any model you want, Nous Portal, OpenRouter, OpenAI, your own endpoint… Switch with hermes model, no code changes, no lock-in.” API keys are stored in ~/.hermes/.env, and agent configuration lives in ~/.hermes/config.yaml. Useful companion commands: hermes tools to configure tools, hermes config set and hermes config get to inspect settings, and hermes doctor to diagnose a sick installation. If you are coming from OpenClaw, hermes claw migrate exists for exactly that move.

Step 3: Go fully local with Ollama (the point of self-hosting)

The strongest reason to self-host is keeping every token on your own hardware. Hermes supports self-hosted endpoints like Ollama and vLLM through its Custom Endpoint flow, documented in the official providers documentation.

Install Ollama on the machine that will serve the model, pull a coding-capable model, and start the server:

ollama pull qwen2.5-coder:32b
ollama serve

Ollama listens on port 11434. In Hermes, add it as a Custom Endpoint with base URL http://localhost:11434/v1 and no API key. The same providers page documents vLLM (with --max-model-len), LM Studio, SGLang, and llama.cpp as local options, so you are not locked to Ollama’s runtime either. Our Ollama with n8n AI Agent tutorial covers the same local-model plumbing from the workflow-automation side, and the concepts transfer directly.

Two gotchas from the official docs will save you an afternoon. First, Ollama does not use your model’s full context window by default, and you cannot fix this through the OpenAI-compatible API; the docs call this “the #1 source of confusion when integrating Ollama with tools like Hermes.” Set it server-side before starting Ollama:

OLLAMA_CONTEXT_LENGTH=64000 ollama serve

A systemd unit can carry the same setting as Environment="OLLAMA_CONTEXT_LENGTH=64000", or you can bake num_ctx into a Modelfile. Second, if Ollama runs on the Windows host while Hermes runs in WSL2, the two cannot see each other’s localhost. Start Ollama with OLLAMA_HOST=0.0.0.0 and confirm reachability from WSL2 with curl http://localhost:11434/v1/models before pointing Hermes at it.

Step 4: Put the agent on messaging with the gateway

Hermes is not only a terminal tool. Start the messaging gateway and the same agent core, with full tool access rather than a chat-only wrapper, becomes reachable from your messaging apps:

hermes gateway

The gateway covers Telegram, Discord, Slack, WhatsApp, Signal, and more. This is the self-hosted answer to the always-on assistant: approvals and long-running tasks reach you where you already are, while the agent keeps running on your machine. If WhatsApp is your target surface, our WhatsApp Business automation guide walks the platform-side setup that pairs well with this step. Since the agent runs MCP servers and custom tools, the gateway is also how you get phone-side access to everything Hermes can do on your infrastructure, a pattern the Model Context Protocol tutorial explains from the protocol side.

Step 5: Make it yours, skills, memory, profiles, and updates

Hermes improves with use. It writes reusable skills from experience, so procedures it figures out once become loadable skills in future sessions, and it keeps persistent memory across sessions: who you are, your preferences, your environment, and lessons learned. Run multiple isolated instances with profiles, each with its own config, sessions, skills, and memory, which is the clean way to separate work projects from personal experiments.

For day-to-day operation, three commands matter. hermes doctor diagnoses common problems before you start guessing. hermes update pulls the latest release, but read Troubleshooting issue 2 first if your server is small, because the update restarts the gateway. And the built-in cron scheduler lets Hermes run recurring tasks on its own, which is what turns a chat agent into infrastructure. If you want the same persistent-memory idea inside workflow automation, our n8n AI agent tutorial shows the equivalent architecture on the n8n side.

Troubleshooting

1. Installer dies with “Out of memory” on a small VPS

Symptom. During installation, the process is killed and dmesg shows something like:

Out of memory: Killed process ... (uv)

This is GitHub issue #17897 on the Hermes repository: the bundled uv package manager spikes memory hard during setup, and the kernel OOM killer fires on machines with little free RAM.

Fix. Do not just rerun the installer. Free up RAM first (stop other services), or add swap as a buffer, or run the install on a machine with more memory and copy the result. Once the spike passes, the installed agent itself is light.

2. hermes update OOMs a 1.6 GB server because the gateway restarts

Symptom. An update on a small server triggers the OOM killer even though Hermes normally fits. Issue #26770 documents the mechanism: “On a 1.6 GB server, the combined memory usage exceeds physical RAM and triggers OOM,” because the update restarts the gateway while the new binaries are being installed.

Fix. Stop the gateway before updating, then start it again after:

systemctl --user stop hermes-gateway
hermes update
systemctl --user start hermes-gateway

3. The dashboard’s memory grows until the kernel kills it

Symptom. The web dashboard starts around 340 MB of RSS and climbs to 4.8 to 5.3 GB over time, at which point the kernel OOM-kills it. This is issue #46082.

Fix. Cap it with systemd so the leak cannot take the machine down. Add to the unit:

MemoryMax=4G

Then systemctl --user daemon-reload and restart the dashboard. The cap turns a crash into a restart, which is the right trade until the underlying leak is fixed upstream.

4. Windows Defender quarantines the installer

Symptom. On Windows, the install fails or the binary disappears, and Defender history shows a quarantine event for %LOCALAPPDATA%\hermes\bin\uv.exe.

Fix. The official README’s troubleshooting section calls this out explicitly: it is a false positive. The file is Astral’s uv, the Rust Python package manager Hermes bundles. Whitelist the directory and rerun:

Add-MpPreference -ExclusionPath "$env:LOCALAPPDATA\hermes\bin"

5. Local model gives short or confused answers through Ollama

Symptom. Hermes works fine with a hosted API but gives truncated, forgetful, or confused answers when pointed at your Ollama endpoint.

Fix. This is the context-length default from Step 3: Ollama does not use the model’s full context window unless configured server-side, which the official providers documentation calls “the #1 source of confusion when integrating Ollama with tools like Hermes.” Restart Ollama with an explicit context length:

OLLAMA_CONTEXT_LENGTH=64000 ollama serve

Then reconnect Hermes and retry the same task before changing anything else.

FAQ

See the front matter for the full FAQ entries. In short: Hermes Agent is MIT-licensed and free to self-host, with Nous monetizing hosted and enterprise tiers. It can drive Claude models through its Anthropic provider, so it complements rather than replaces Claude at the model layer. The agent itself runs on modest hardware, while local models need whatever Ollama requires for your chosen model. Windows and WSL2 are both documented install targets. And self-hosting with a local model is the strongest privacy posture available, since no prompt leaves your machine.

Conclusion

Self-hosting Hermes Agent is a fifteen-minute job with a long tail of good decisions: one installer command, model freedom through hermes model, a fully local option via Ollama for data that must never leave the building, and a messaging gateway that makes the agent reachable from your phone. The Series B funding tells you where the project is going, with Hermes for Businesses taking the same agent into enterprises that need private multi-step automation, but the MIT-licensed core you just installed is the same one the community is building on. Next, compare surfaces directly with our Claude Code MCP setup guide, or take the workflow-automation angle with our AI support chatbot tutorial.

Frequently asked questions