How to set up Hermes Agent: a step-by-step guide
A complete guide to installing and configuring Hermes Agent. the open-source CLI agent from Nous Research. Configure providers, set up skills, and run your first agent session.
TL;DR: I switched from Claude Code to Hermes Agent when I needed an open-source agent I could modify. It took 5 minutes to install and configure. Here is the exact setup.
Hermes Agent is the open-source CLI agent powering this session. It’s built by Nous Research: general-purpose agent with tool access, skills, and multi-provider support. I switched because I needed an agent I could inspect, modify, and extend without depending on a closed-source vendor.
Key takeaways:
- Install globally via npm:
npm install -g hermes-agent- Configure at least one LLM provider in
~/.hermes/config.yaml- Skills add capabilities: installed to
~/.hermes/skills/- MCP servers connect external tools (web search, file system, databases)
- Profile system lets you switch between config sets
What do I need before setting up Hermes Agent?
| Requirement | Minimum |
|---|---|
| Node.js | 18.x or higher |
| npm | 9.x or higher |
| Operating system | macOS, Linux, Windows (WSL2) |
| RAM | 512 MB (agent only, not for local models) |
How do I install Hermes Agent?
Install globally via npm:
npm install -g hermes-agentVerify the installation:
hermes --versionThis should print the installed version. If you see a command not found error, ensure your npm global bin directory is in your PATH.
How do I configure an LLM provider?
Hermes needs at least one LLM provider to work. Create the config directory:
mkdir -p ~/.hermesEdit ~/.hermes/config.yaml:
defaultProvider: openrouter
providers:
openrouter:
apiKey: your-openrouter-api-key
baseUrl: https://openrouter.ai/api/v1
models:
default: google/gemini-2.5-pro-exp-03-25
anthropic:
apiKey: your-anthropic-api-key
models:
default: claude-sonnet-4-20250514You can also set environment variables instead:
export ANTHROPIC_API_KEY=sk-ant-..
export OPENROUTER_API_KEY=sk-or-..Start with OpenRouter: it gives you access to dozens of models with a single API key. You can test different models before committing to a specific provider.
How do I run my first Hermes Agent session?
Start an interactive session:
hermes chatYou’ll see the agent initialize, load skills, and present a prompt. Try asking it something simple:
What tools do you have available?Hermes will list its available tools: web search, file operations, terminal access, and any skills you’ve installed.
How do I install skills in Hermes Agent?
Skills extend Hermes with domain-specific capabilities. They live in ~/.hermes/skills/. Each skill is a directory with a SKILL.md file that describes when and how to use it.
# List installed skills
hermes skills list
# View a skill's content
cat ~/.hermes/skills/your-skill-name/SKILL.mdSkills can be created manually or installed from external sources like Newsjack, which installs skills for content discovery and PR monitoring.
How do I configure Hermes Agent profiles?
Hermes supports multiple profiles for different contexts: work, personal, different provider sets:
# ~/.hermes/config.yaml
profiles:
default:
provider: openrouter
model: google/gemini-2.5-pro-exp-03-25
work:
provider: anthropic
model: claude-sonnet-4-20250514Switch profiles with:
hermes chat --profile workEach profile has its own skills directory, so you can keep work and personal skills separate.
What configuration options does Hermes Agent support?
Key environment variables
| Variable | Purpose |
|---|---|
ANTHROPIC_API_KEY | Anthropic Claude access |
OPENAI_API_KEY | OpenAI GPT access |
OPENROUTER_API_KEY | Multi-model provider access |
HERMES_HOME | Override config directory (default: ~/.hermes) |
Key config paths
| Path | Purpose |
|---|---|
~/.hermes/config.yaml | Main configuration |
~/.hermes/skills/ | Skill directories |
~/.hermes/plugins/ | Plugin modules |
~/.hermes/profiles/<name>/ | Profile-specific config |
The official documentation is at hermes-agent.nousresearch.com.
For more on AI agent tooling and setup patterns, check out my comparison of coding agents and how to build your first AI agent.
FAQ
What is Hermes Agent? Hermes Agent is an open-source CLI-based AI agent developed by Nous Research. It supports multiple LLM providers, has a plugin system, and runs as a terminal-based agent with tools for web search, file operations, and code execution.
What providers does Hermes Agent support? Hermes supports OpenAI, Anthropic, OpenRouter, Google Gemini, MiniMax, and custom providers. You configure the provider and model in config.yaml or set environment variables.
Does Hermes Agent require a GPU? No. Hermes Agent is a CLI tool that calls LLM APIs. It runs on any machine with Node.js and an internet connection. The models run on the provider’s servers, not locally.
Can Hermes Agent use local models? Yes, through custom providers like Ollama or llama.cpp. You can configure a local endpoint as a custom provider in config.yaml.
Related Posts
- How to build your first AI agent in 2026. A step-by-step tutorial from scratch, building the core loop and tools
- Best AI coding agents in 2026. Comparing Claude Code, Cursor, Copilot, and OpenCode for development workflows
- Best open source AI tools for indie hackers in 2026. A curated list of production-ready open source AI tools for solo developers
- AI agent web app vocabulary. A scannable reference of terms for steering agents and shipping web apps
This article was published on Agentic Up (https://agenticup.dev): practical guides for developers and founders building with AI agents. Reach me at hello@agenticup.dev
