DEV Community

Cover image for How to Use Hermes Agent
Wanda
Wanda

Posted on • Originally published at apidog.com

How to Use Hermes Agent

TL;DR: Hermes Agent is an open-source AI assistant that learns and remembers as you work. Install it with a single command, configure your LLM provider, and start chatting via CLI, Telegram, Discord, or your IDE. This guide provides actionable steps for installation, setup, usage, advanced features, and maximizing productivity with Hermes.

Try Apidog today

What Is Hermes Agent?

Hermes Agent is a personal AI assistant by NousResearch designed for persistent, contextualized assistance. Unlike ChatGPT or Claude, Hermes keeps a persistent model of your work, projects, and preferences.

Hermes Agent Features

Key capabilities:

  • Remembers: Stores conversations, decisions, and code.
  • Learns: Converts repeated workflows into reusable skills.
  • Multi-platform: Use via CLI, Telegram, Discord, Slack, WhatsApp, or IDE.
  • Self-hosted: Deploy locally, on a $5 VPS, or in the cloud.
  • Model agnostic: Supports 200+ models via OpenRouter or direct providers.
  • Extensible: Add plugins for custom tools and commands.

Best for:

  • Developers wanting an AI pair programmer aware of their codebase.
  • Teams who need a shared AI assistant.
  • Power users automating with cron scheduling.
  • Researchers training custom AI models.

Installation: Step-by-Step

Prerequisites

  • OS: macOS, Linux, or Windows (WSL recommended)
  • Python: 3.10+
  • Git: For cloning repositories
  • API Key: OpenRouter, Anthropic, OpenAI, etc.

Quick Install (Recommended)

Install Hermes with:

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
Enter fullscreen mode Exit fullscreen mode

This script:

  1. Clones the Hermes repo
  2. Installs uv (Python package manager)
  3. Creates a virtualenv
  4. Installs dependencies
  5. Adds Hermes to your PATH

Reload your shell:

source ~/.bashrc  # bash
source ~/.zshrc   # zsh
Enter fullscreen mode Exit fullscreen mode

Verify install:

hermes --version
# Output: Hermes Agent v0.5.0
Enter fullscreen mode Exit fullscreen mode

Manual Install (For Developers) 

# Clone repo
git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent

# Install uv if needed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Virtualenv setup
uv venv venv --python 3.11
source venv/bin/activate    # Linux/macOS
# .\venv\Scripts\activate   # Windows

# Install all features
uv pip install -e ".[all,dev]"

# Run tests
python -m pytest tests/ -q
Enter fullscreen mode Exit fullscreen mode

Install with RL Training Support

If training custom models:

git submodule update --init tinker-atropos
uv pip install -e "./tinker-atropos"
Enter fullscreen mode Exit fullscreen mode

Initial Setup and Configuration

Run the Setup Wizard

For first-time setup:

hermes setup
Enter fullscreen mode Exit fullscreen mode

The wizard configures:

  1. LLM provider (OpenRouter, Anthropic, OpenAI, etc.)
  2. API keys (stored at ~/.hermes/.env)
  3. Memory (persistent or not)
  4. Terminal backend (local, Docker, SSH, cloud)
  5. Messaging gateways (Telegram, Discord, Slack)

Manual Configuration

Edit the config file:

hermes config edit
Enter fullscreen mode Exit fullscreen mode

Or use CLI commands:

hermes config set model anthropic/claude-opus-4
hermes config set terminal.backend local
hermes config set OPENROUTER_API_KEY sk-or-...
hermes config set ANTHROPIC_API_KEY sk-ant-...
Enter fullscreen mode Exit fullscreen mode

Configuration File Location

Hermes stores config at ~/.hermes/:

~/.hermes/
├── config.yaml      # Main config
├── .env            # API keys
├── memory/         # Persistent storage
├── skills/         # Installed skills
└── plugins/        # Custom plugins
Enter fullscreen mode Exit fullscreen mode

Verify Your Setup

Run diagnostics:

hermes doctor
Enter fullscreen mode Exit fullscreen mode

Checks configuration, API keys, memory, gateways, and terminal backend.

Choosing Your LLM Provider

Hermes supports 200+ models across providers.

OpenRouter (Recommended for Beginners)

Single API key, 200+ models, free tier available.

hermes config set model openrouter
hermes config set OPENROUTER_API_KEY sk-or-...
Enter fullscreen mode Exit fullscreen mode

Popular models:

Model Use Case Cost
anthropic/claude-opus-4 Complex coding, reasoning $$$
anthropic/claude-sonnet-4 Balanced performance $$
openai/gpt-4o General purpose $$
google/gemini-pro-1.5 Long context windows $
meta/llama-3-70b Open source, fast $

Anthropic Direct

Best-in-class coding/reasoning.

hermes config set model anthropic
hermes config set ANTHROPIC_API_KEY sk-ant-...
hermes config set model.default claude-opus-4
Enter fullscreen mode Exit fullscreen mode

OpenAI Direct

For GPT-4o and o1.

hermes config set model openai
hermes config set OPENAI_API_KEY sk-...
Enter fullscreen mode Exit fullscreen mode

Local Models (Ollama)

Free, private, offline:

# Install Ollama first: https://ollama.ai
hermes config set model ollama
hermes config set model.default qwen2.5-coder:32b
Enter fullscreen mode Exit fullscreen mode

Model Config Examples

Smart routing:

model:
  provider: openrouter
  default: anthropic/claude-opus-4
  fallback:
    - anthropic/claude-haiku-4-5
    - openai/gpt-4o-mini
Enter fullscreen mode Exit fullscreen mode

Cost control:

model:
  budget:
    daily_limit: 5.00   # USD
    monthly_limit: 100.00
Enter fullscreen mode Exit fullscreen mode

Basic Usage: CLI Mode

Starting Hermes 

hermes
Enter fullscreen mode Exit fullscreen mode

Start chatting directly in your terminal.

Basic Commands

Chat:

> Hey, can you help me write a Python function to parse JSON?
Enter fullscreen mode Exit fullscreen mode

Slash commands:

> /help          # All commands
> /skills        # List skills
> /memory        # Check memory
> /config        # View/edit config
> /clear         # Clear conversation
> /history       # Past conversations
Enter fullscreen mode Exit fullscreen mode

File-based tasks:

> Look at ./src/main.py and refactor the database connection
Enter fullscreen mode Exit fullscreen mode

Run terminal commands:

> Run: npm install && npm run build
Enter fullscreen mode Exit fullscreen mode

Hermes asks for confirmation before execution.

Persistent Shell

Hermes keeps shell state across commands:

> cd /my/project && source venv/bin/activate
> python src/main.py
Enter fullscreen mode Exit fullscreen mode

Virtual environments stay active.

Working with Files

  • Read: > Show me config.yaml
  • Edit: > In main.py change DB port 5432 to 5433
  • Create: > Create utils.py with date formatting helpers

Multi-Step Workflows

Hermes executes complex workflows:

> I need to add user authentication to my Flask app. Can you:
> 1. Set up database models
> 2. Create login/logout endpoints
> 3. Add JWT token generation
> 4. Write tests for auth flow
Enter fullscreen mode Exit fullscreen mode

Hermes confirms each step.

Messaging Gateway: Telegram, Discord, Slack

Interact with Hermes via chat platforms.

Telegram Setup

  1. Create bot:
    • Message @botfather /newbot, follow prompts, copy token.
  2. Configure: 
   hermes config set TELEGRAM_BOT_TOKEN 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
Enter fullscreen mode Exit fullscreen mode
  1. Start gateway: 
   hermes gateway setup telegram
   hermes gateway start
Enter fullscreen mode Exit fullscreen mode
  1. Chat:
    • Open your bot in Telegram, /start, chat as usual.

Discord Setup

  1. Create application:
  2. Invite bot:
    • Use "OAuth2 → URL Generator", scope: bot, open link.
  3. Configure: 
   hermes config set DISCORD_BOT_TOKEN MTIzNDU2...
   hermes gateway setup discord
   hermes gateway start
Enter fullscreen mode Exit fullscreen mode
  1. Use:
    • Mention bot in channels or DM.

Slack Setup

  1. Create app:
  2. Install app and copy token
  3. Configure: 
   hermes config set SLACK_BOT_TOKEN xoxb-...
   hermes gateway setup slack
   hermes gateway start
Enter fullscreen mode Exit fullscreen mode

Multi-Platform Usage

Run multiple gateways:

hermes gateway start --all
Enter fullscreen mode Exit fullscreen mode

Hermes syncs state across platforms.

IDE Integration: VS Code, JetBrains

Hermes integrates with editors via Agent Communication Protocol (ACP).

VS Code Integration

  1. Install ACP extension:
    • Extensions (Ctrl+Shift+X), search "Agent Communication Protocol".
  2. Start Hermes ACP server: 
   hermes acp start
Enter fullscreen mode Exit fullscreen mode
  1. Use in VS Code:
    • Open ACP sidebar, select Hermes, chat or use slash commands.

JetBrains (IntelliJ, PyCharm, etc.)

  1. Install ACP plugin:
    • Settings → Plugins → Search "ACP", install, restart IDE.
  2. Start ACP server: 
   hermes acp start
Enter fullscreen mode Exit fullscreen mode
  1. Configure in JetBrains:
    • Settings → Tools → AI Agents → Add Hermes as ACP backend.

Zed Editor

Native ACP support:

  1. Configure: 
{
  "agent": {
    "provider": "acp",
    "endpoint": "hermes"
  }
}
Enter fullscreen mode Exit fullscreen mode
  1. Start Hermes: 
hermes acp start
Enter fullscreen mode Exit fullscreen mode

Memory and Learning System

Hermes leverages persistent memory for smarter assistance.

Memory Types

  • Episodic: Stores conversations/sessions. 
  > /memory search "database migration"
Enter fullscreen mode Exit fullscreen mode
  • Semantic: Knowledge graphs of projects, preferences. 
  > /memory projects
Enter fullscreen mode Exit fullscreen mode
  • Procedural (Skills): Automates repeated workflows. 
  > /skills list
Enter fullscreen mode Exit fullscreen mode

Session Search

Semantic search across history:

> /memory search "How did we handle JWT expiration last week?"
Enter fullscreen mode Exit fullscreen mode

Memory Nudges

Hermes proactively surfaces context:

[Hermes]: I noticed you're working on the auth system. Last Tuesday you mentioned a problem with JWT expiration. Want to revisit that?
Enter fullscreen mode Exit fullscreen mode

Context Compression

  • Gateway compresses at 85% context usage
  • Agent compresses at 50% (configurable)

Allows long, uninterrupted conversations.

Export and Backup

Export:

hermes memory export ~/backup/hermes-memory.json
Enter fullscreen mode Exit fullscreen mode

Import:

hermes memory import ~/backup/hermes-memory.json
Enter fullscreen mode Exit fullscreen mode

Skills and Plugins

What Are Skills?

Reusable, macro-like workflows for frequent tasks.

Built-in skills:

  • code_review — Code QA
  • debug_session — Debugging
  • api_tester — API testing
  • git_workflow — Git ops
  • documentation — Generate docs

Browse and Install Skills

List skills:

> /skills list
Enter fullscreen mode Exit fullscreen mode

Install:

> /skills install code_review
Enter fullscreen mode Exit fullscreen mode

Use:

> /skills run code_review ./src/auth.py
Enter fullscreen mode Exit fullscreen mode

Custom Skills

Define in ~/.hermes/skills/:

# ~/.hermes/skills/my_skill.py
from hermes.skills import Skill

class MyCustomSkill(Skill):
    name = "my_custom_skill"
    description = "Does something useful"

    def execute(self, context):
        # Your logic here
        return "Skill executed successfully"
Enter fullscreen mode Exit fullscreen mode

Plugin System

Extend Hermes with custom tools, commands, or hooks.

# ~/.hermes/plugins/my_tool.py
from hermes.tools import Tool

class MyCustomTool(Tool):
    name = "my_tool"
    description = "A custom tool for specific tasks"

    def run(self, **kwargs):
        return {"result": "success"}
Enter fullscreen mode Exit fullscreen mode

Plugin types:

  • Tools: New agent capabilities
  • Commands: Slash commands
  • Hooks: Event handlers

Advanced Features

Cron Scheduling

Automate tasks:

> Set up a daily digest of my GitHub notifications at 9am
Enter fullscreen mode Exit fullscreen mode

Or configure in config.yaml:

cron:
  - name: "Daily digest"
    schedule: "0 9 * * *"
    command: "/skills run github_digest"
    model: "anthropic/claude-haiku-4-5"
Enter fullscreen mode Exit fullscreen mode

Subagent Delegation

Hermes can run parallel subtasks:

> I need you to review all the PRs in my repo and summarize the changes
Enter fullscreen mode Exit fullscreen mode

Voice Mode

  • CLI: 
  hermes --voice
Enter fullscreen mode Exit fullscreen mode
  • Telegram/Discord: Send a voice note, Hermes transcribes and replies.
  • Discord voice channels: Join, speak, and listen in real time.

Browser Control

Automate the web:

> Go to github.com and find the top 5 trending Python repos
Enter fullscreen mode Exit fullscreen mode

Or with Chrome CDP:

hermes browser connect --cdp
Enter fullscreen mode Exit fullscreen mode

MCP Integration

Support for Model Context Protocol servers:

mcp:
  servers:
    filesystem:
      command: "npx"
      args: ["-y", "@modelcontextprotocol/server-filesystem", "~/projects"]
    git:
      command: "npx"
      args: ["-y", "@modelcontextprotocol/server-git"]
Enter fullscreen mode Exit fullscreen mode

Worktree Mode

Run in an isolated git worktree:

hermes -w
Enter fullscreen mode Exit fullscreen mode

Enables parallel agents on the same repo.

Run Other Agents Inside Hermes

Delegate tasks to other AI agents:

> Use claude-code to review this pull request
Enter fullscreen mode Exit fullscreen mode

Troubleshooting

Common Issues

"API key not found"

hermes config get OPENROUTER_API_KEY
hermes config set OPENROUTER_API_KEY sk-or-...
Enter fullscreen mode Exit fullscreen mode

"Model not available"

hermes models list
hermes config set model anthropic/claude-opus-4
Enter fullscreen mode Exit fullscreen mode

"Gateway failed to start"

hermes gateway status
hermes gateway stop
hermes gateway start
Enter fullscreen mode Exit fullscreen mode

"Memory corruption detected"

hermes memory export ~/backup/memory-backup.json
hermes memory reset
hermes memory import ~/backup/memory-backup.json
Enter fullscreen mode Exit fullscreen mode

Getting Help

  • Built-in help: /help
  • Logs: 
  hermes logs tail --follow
Enter fullscreen mode Exit fullscreen mode
  • Diagnostics: 
  hermes doctor
Enter fullscreen mode Exit fullscreen mode

FAQ

How much does Hermes cost to run?

Hermes is free. LLM usage costs:

  • Light use: $5-15/month (OpenRouter)
  • Moderate: $20-50/month
  • Heavy (24/7): $50-200/month

Local models (Ollama) are free, need hardware.

Can Hermes run 24/7?

Yes, on a VPS:

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
hermes service install
hermes service start
Enter fullscreen mode Exit fullscreen mode

Is Hermes suitable for enterprise use?

Yes. Supports:

  • Multi-user gateway with isolation
  • PII redaction
  • Supply chain security
  • Self-hosted deployment
  • Audit logging

How do I migrate from OpenClaw? 

hermes claw migrate --dry-run  # Preview
hermes claw migrate            # Full migration
hermes doctor                  # Verify
Enter fullscreen mode Exit fullscreen mode

Can I use Hermes without internet?

Yes, use local models:

curl -fsSL https://ollama.ai/install.sh | sh
ollama pull qwen2.5-coder:32b
hermes config set model ollama
hermes config set model.default qwen2.5-coder:32b
Enter fullscreen mode Exit fullscreen mode

What's the difference between Hermes and ChatGPT?

Feature Hermes ChatGPT
Memory Persistent, searchable Session-only
Deployment Self-hosted, 24/7 Cloud-only
Model choice 200+ models GPT only
Extensibility Plugins, skills Limited
Cost Pay for usage only Subscription
Privacy You control data OpenAI stores data

How do I backup my Hermes data? 

hermes export --all ~/backup/hermes-full-backup.tar.gz
Enter fullscreen mode Exit fullscreen mode

Can Hermes access my local files?

Only files/directories you reference or grant permission. No default file access.

💡 Want to test APIs as part of your AI-powered development workflow? Check out Apidog, the all-in-one API development platform for designing, testing, and documenting APIs.

Top comments (0)