How to Set Up Hermes Agent: Complete Guide by Nous Research
By Braincuber Team
Published on April 18, 2026
Hermes Agent is an open-source AI agent developed by Nous Research, the lab behind Hermes models. It has gained significant popularity as an OpenClaw alternative, accumulating over 30K stars. What sets Hermes apart is its ability to create skills from experience, improve itself, and persist knowledge across sessions.
What You'll Learn:
- Install Hermes Agent with one-line installer
- Configure API keys and model selection
- Set up Telegram gateway
- Create multi-profile agents
- Configure offline运行 with Ollama
- Troubleshoot common issues
What Is Hermes Agent?
Hermes Agent is an open-source AI agent by Nous Research that serves as a powerful alternative to OpenClaw. Unlike standard AI assistants, Hermes Agent can create skills from experience, improve itself over time, and persist knowledge across sessions through its unique memory system.
Closed Learning Loop
Agent-curated memory with periodic nudges. Creates skills automatically after complex tasks and improves them over time.
SQLite Memory Storage
Stores sessions in SQLite database with FTS5 full-text search. Retrieve memories from weeks ago, even if not currently in memory.
Context Compression
Dual compression and Anthropics prompt caching manage context usage, preventing API failures with large context.
Multi-Platform Gateway
Supports Telegram, Discord, Slack, Signal, and WhatsApp. Continue conversations across platforms seamlessly.
Key Capabilities
Self-Improving Memory
Hermes Agent has a closed learning loop meaning it has agent-curated memory with periodic nudges, creates skills automatically after performing complex tasks, and improves skills as it uses them.
It also stores messaging sessions in a SQLite database with FTS5 full-text search, enabling retrieval of memories from weeks ago. The Honcho memory provides persistent understanding of users across sessions.
Skills System
Like OpenClaw, Hermes Agent supports skills that follow a progressive disclosure pattern to minimize token utilization. It ships with bundled skills and also saves its own skills as you use the agent.
All skills are stored in ~/.hermes/skills/, but you can also point to external skills.
Subagents and Parallel Workstreams
The Hermes Agent has a delegate_task tool to start multiple subagents. Agents have restricted toolsets and terminal sessions. Use this to research multiple topics simultaneously, code review, or refactor files in parallel.
MCP Support
For any missing tools, you can connect to MCPs (Model Context Protocols). This allows connecting to APIs, databases, or company systems without changing Hermes code. Install MCP support, add an MCP server, and whitelist/blacklist activities.
Supported Models
Hermes Agent is model agnostic and supports:
| Provider | Description |
|---|---|
| Nous Portal | Models from Nous Portal |
| OpenRouter | Via API key |
| Anthropic | Auth and API key |
| OpenAI | Subscription or API key |
| Gemini | Google Gemini API |
| Ollama | Local models |
Prerequisites
Hermes runs on Linux, macOS, and WSL2. It requires Python 3.11 and Node.js, though most dependencies are installed automatically during setup.
Step 1: Install Hermes Agent
Open your terminal and run the one-line installer:
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
Step 2: Get Your Telegram Token
For the Telegram gateway, open Telegram and search for @BotFather. Send it /newbot, follow the prompts to name your bot, and it will give you a bot token.
Create Bot
Message @BotFather and send /newbot to create your bot.
Get User ID
Message @userinfobot to get your Telegram user ID so your bot only talks to you.
Step 3: Initialize Hermes
Run the setup wizard to configure everything:
hermes setup
When you choose Full Setup, you will configure API keys and the Telegram bot. If you have an existing OpenClaw installation, it allows migration.
hermes doctor
Step 4: Configure Model Selection
Change the model anytime by running:
hermes model
Step 5: Set Up Telegram Gateway
The gateway lets Hermes reach you on Telegram. Set it up by running:
hermes gateway setup
Creating Multi-Profile Agents
Run multiple independent Hermes agents on the same machine, each with its own config, API keys, memory, and gateway.
hermes profile create work --clone
You can create profiles for different purposes: coding agent, personal assistant, research agent. Each gets its own .env file and Telegram bot.
Running Hermes Agent Offline
Run Hermes Agent offline by setting up a model via Ollama:
ollama pull qwen2.5-coder:32b
ollama serve
Context Window Note
Increase the context window because the model needs to load the system prompt, tools, and return a response. Set OLLAMA_CONTEXT_LENGTH=32768 before running ollama serve.
Common Issues and Troubleshooting
Connection Refused Errors
Run hermes doctor first to check for missing config or broken environment variables.
Context Window Limits
Type /compress to trigger manual context compression, or edit ~/.hermes/config.yaml.
Gateway Not Receiving Messages
Run hermes gateway status to check status, and hermes gateway start if stopped.
Best Practices for Deployment
When deploying on a VPS, follow these best practices:
| Practice | Description |
|---|---|
| Use container backend | Isolate the agent environment |
| Set explicit allowlists | Control what the agent can access |
| Use pairing codes | Instead of user ID for authentication |
| Store secrets securely | Use proper file permissions |
| Set resource limits | CPU, disk, and memory limits |
| Never run as root | Security best practice |
Frequently Asked Questions
What makes Hermes Agent different from OpenClaw?
Hermes can create skills from experience, improve itself over time, and persist knowledge across sessions. It also offers better open-source model support and stores sessions in SQLite for full-text search.
Can I run Hermes Agent offline?
Yes, use Ollama to run local models like qwen2.5-coder. Set OLLAMA_CONTEXT_LENGTH=32768 before running to handle large system prompts.
How do multi-profile agents work?
Each profile gets its own config, API keys, memory, sessions, gateway, and skills. Create profiles with hermes profile create name --clone to clone existing settings.
What platforms does Hermes support?
Hermes supports Telegram, Discord, Slack, Signal, and WhatsApp. Start a conversation on your terminal and continue on any messaging platform.
What models can I use with Hermes?
Hermes is model agnostic. It supports Nous Portal, OpenRouter, Anthropic, OpenAI, Gemini, and local models via Ollama.
Need Help Setting Up AI Agents?
Our experts can help you configure Hermes Agent, set up multi-profile systems, and integrate with your existing workflows.