---
title: "How to set up Hermes Agent: a step-by-step guide"
canonical: "https://agenticup.dev/posts/how-to-set-up-hermes-agent/"
pubDate: "2026-06-10T00:00:00.000Z"
description: "Hermes Agent is an open-source CLI agent by Nous Research. Here's how to install, configure providers, set up skills, and run your first session — from scratch to a working agent."
tags: [hermes, agent-setup, cli, configuration, open-source, ai-agents]
---

TL;DR: Hermes Agent is an open-source CLI agent from Nous Research. Install it via npm, configure a provider (OpenAI, Anthropic, OpenRouter), and run your first session. Skills and plugins extend what it can do.

Hermes Agent is the open-source CLI agent that powers this very session. It's built by Nous Research and designed to be a general-purpose agent with tool access, skill management, and multi-provider support. Here's how to set it up from scratch.

> **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

## Prerequisites

| 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) |

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "HowTo",
  "name": "How to set up Hermes Agent",
  "description": "A step-by-step guide to installing and configuring Hermes Agent, the open-source CLI agent from Nous Research.",
  "step": [
    {"@type": "HowToStep", "position": 1, "name": "Install Hermes Agent", "text": "Install globally via npm: npm install -g hermes-agent. Verify with hermes --version."},
    {"@type": "HowToStep", "position": 2, "name": "Configure a provider", "text": "Create ~/.hermes/config.yaml with your LLM provider (OpenAI, Anthropic, or OpenRouter) and API key."},
    {"@type": "HowToStep", "position": 3, "name": "Run your first session", "text": "Start an interactive session with hermes chat and test with a simple query."},
    {"@type": "HowToStep", "position": 4, "name": "Install skills", "text": "Skills extend Hermes with domain-specific capabilities. They live in ~/.hermes/skills/."},
    {"@type": "HowToStep", "position": 5, "name": "Configure profiles", "text": "Set up multiple profiles in config.yaml for different provider or workspace configurations."}
  ]
}
</script>

## Step 1: Install Hermes Agent

Install globally via npm:

```bash
npm install -g hermes-agent
```

Verify the installation:

```bash
hermes --version
```

This should print the installed version. If you see a command not found error, ensure your npm global bin directory is in your PATH.

## Step 2: Configure a provider

Hermes needs at least one LLM provider to work. Create the config directory:

```bash
mkdir -p ~/.hermes
```

Edit `~/.hermes/config.yaml`:

```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-20250514
```

You can also set environment variables instead:

```bash
export ANTHROPIC_API_KEY=sk-ant-...
export OPENROUTER_API_KEY=sk-or-...
```

<div class="callout">
  <div class="callout-title">Pro tip</div>
  <p>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.</p>
</div>

## Step 3: Run your first session

Start an interactive session:

```bash
hermes chat
```

You'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.

## Step 4: Install skills

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.

```bash
# List installed skills
hermes skills list

# View a skill's content
cat ~/.hermes/skills/your-skill-name/SKILL.md
```

Skills can be created manually or installed from external sources like Newsjack, which installs skills for content discovery and PR monitoring.

## Step 5: Configure profiles

Hermes supports multiple profiles for different contexts — work, personal, different provider sets:

```yaml
# ~/.hermes/config.yaml
profiles:
  default:
    provider: openrouter
    model: google/gemini-2.5-pro-exp-03-25
  work:
    provider: anthropic
    model: claude-sonnet-4-20250514
```

Switch profiles with:

```bash
hermes chat --profile work
```

Each profile has its own skills directory, so you can keep work and personal skills separate.

## Configuration reference

### 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](https://hermes-agent.nousresearch.com/docs).

For more on AI agent tooling and setup patterns, check out [my comparison of coding agents](/posts/cursor-vs-claude-code-vs-copilot-comparison/) and [how to build your first AI agent](/posts/how-to-build-first-ai-agent-2026/).

## Related Posts

- [How to build your first AI agent in 2026](/posts/how-to-build-first-ai-agent-2026/) — A step-by-step tutorial from scratch, building the core loop and tools
- [Best AI coding agents in 2026](/posts/best-ai-coding-agents-2026/) — Comparing Claude Code, Cursor, Copilot, and OpenCode for development workflows
- [Best open source AI tools for indie hackers in 2026](/posts/best-open-source-ai-tools-indie-hackers-2026/) — A curated list of production-ready open source AI tools for solo developers
- [AI agent web app vocabulary](/posts/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.