Hermes Agent Tutorial: Build Your Self-Evolving AI Agent from Scratch

Created

Hermes Agent is an open-source AI agent framework by Nous Research with over 150k GitHub stars. It can help you write code, manage systems, and analyze data — but more importantly, it learns from experience, creates skills automatically, and evolves continuously across sessions.

Why Choose Hermes Agent?

In the AI agent landscape, Hermes Agent belongs to the same category as OpenClaw, Claude Code, and Codex — all are AI assistants capable of tool calling and autonomous task execution. However, Hermes Agent has several unique advantages:

Self-Evolving Learning Loop

Hermes Agent has a built-in learning loop — after completing complex tasks, it automatically creates reusable “Skills” that are saved locally and loaded automatically in future sessions. Each time a skill is used, it self-improves. This means the longer you use Hermes, the better it understands your workflow and needs.

Persistent Memory

Hermes remembers your preferences, environment details, and learned experience. Every time you start a new session, it can recall past conversations and build a deep understanding of you.

True Cross-Platform

The same Hermes Agent instance can run simultaneously on CLI terminal, Telegram, Discord, Slack, WhatsApp, Signal, Matrix, and 10+ other platforms. Send a message from your phone via Telegram, and Hermes executes the task on a server, pushing results back in real time.

20+ LLM Provider Support

Hermes is not locked to any specific AI model. You can use OpenRouter (200+ models), Anthropic, OpenAI, DeepSeek, Xiaomi MiMo, Kimi, MiniMax, Hugging Face, and any other provider — or even local models. Switch providers with a single command, no code changes needed.

Key Differences from OpenClaw

Feature Hermes Agent OpenClaw
Language Python TypeScript/Node.js
Learning Loop ✅ Automatic skill creation & evolution ❌ None
Persistent Memory ✅ Cross-session memory ❌ Limited
Multi-Model Support 20+ providers, switch mid-workflow Limited
Terminal Backends 7 types (Local/Docker/SSH/Modal, etc.) Local only
Research Features ✅ Trajectory generation & compression ❌
Mobile Apps ❌ ✅ macOS/iOS/Android
Voice Wake ❌ ✅ Voice Wake
License MIT MIT

In short: Hermes is better suited for developers, researchers, and advanced users who need cross-platform automation; OpenClaw is better for users seeking a “personal assistant” experience with voice and mobile integration.

Prerequisites

Before getting started, make sure you have:

  • A device running Linux, macOS, WSL2, or Termux
  • Python 3.11 or higher
  • One or more LLM API keys (e.g., OpenRouter, Anthropic)
  • Network access (for downloading and calling APIs)

Step 1: Install Hermes Agent

Linux / macOS / WSL2

One-liner installation:

1
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

After installation, reload your shell:

1
source ~/.bashrc    # or source ~/.zshrc

Windows

WSL2 is recommended for the most stable experience. For native Windows, use PowerShell:

1
iex (irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1)

💡 Tip: Native Windows support is in early beta. If you encounter any issues, switch to WSL2.

Step 2: Initial Configuration

Run the setup wizard after installation:

1
hermes setup

The wizard guides you through:

  1. Model Selection — Choose your LLM provider and model
  2. Terminal Setup — Configure the terminal backend
  3. Gateway Configuration — Set up messaging platforms
  4. Tool Enablement — Select which toolsets to use
  5. Agent Settings — Configure agent behavior

You can also run the model selector independently:

1
hermes model

This opens an interactive menu with 20+ supported providers. If you’re unsure, start with OpenRouter — it aggregates 200+ models under a single API key.

Step 3: Start Chatting

After configuration, launch the interactive chat:

1
hermes

You’ll see a fully-featured Terminal User Interface (TUI) supporting:

  • Multi-line editing — Press Ctrl+Enter for multi-line messages
  • Slash command autocomplete — Type / then Tab to see available commands
  • Streaming tool output — Tool results displayed in real time
  • Conversation history — View and manage past sessions anytime

Quick Commands

Use slash commands during chat:

Command Function
/new or /reset Start a new conversation
/model [provider:model] Switch model
/skills Browse skills
/stop Interrupt current work
/usage Check token usage
/compress Compress context
/tools Manage toolsets

Step 4: Configure the Messaging Gateway

Hermes’ real power comes from remote access via messaging platforms. Start the gateway:

1
2
hermes gateway setup    # Configure messaging platforms
hermes gateway start    # Start the gateway

Supported Platforms

Platform Description
Telegram Most popular, easy setup
Discord Great for team collaboration
Slack Enterprise integration
WhatsApp Personal daily use
Signal Privacy-focused users
Email Send and receive emails
Matrix Open-source messaging
Feishu Chinese office scenarios
DingTalk Chinese office scenarios
WeChat Via community bridge

💡 Tip: Telegram is the easiest platform to get started. Just create a Telegram Bot (via @BotFather), get the Bot Token, and enter it in the gateway config.

Step 5: Explore Core Features

Skills System

Skills are Hermes’ most unique feature. After completing a complex task, Hermes automatically saves the workflow as a skill document. These skills load automatically in future sessions, making Hermes increasingly proficient at your specific tasks.

View installed skills:

1
hermes skills list

Browse the skills hub to install new ones:

1
hermes skills browse

Install a skill:

1
hermes skills install <skill-id>

Persistent Memory

Hermes automatically saves your preferences and environment info. View and manage in the config:

1
hermes config edit    # Edit configuration file

Key configuration options:

1
2
3
memory:
  memory_enabled: true          # Enable persistent memory
  user_profile_enabled: true    # Enable user profile

Cron Scheduling

Hermes has a built-in cron scheduler for timed tasks:

1
2
3
4
5
6
7
8
9
10
11
12
# Create a task that runs every 30 minutes
hermes cron create "30m"

# Create a task that runs daily at 9 AM
hermes cron create "0 9 * * *"

# List all scheduled tasks
hermes cron list

# Pause/resume tasks
hermes cron pause <task-id>
hermes cron resume <task-id>

Subagent Delegation

Hermes can spawn isolated subagents for parallel tasks:

1
2
3
4
5
6
7
8
# In a Python script
from hermes_tools import delegate_task

# Parallel delegation of multiple subtasks
delegate_task(tasks=[
    {"goal": "Analyze data file", "context": "Path: /data/report.csv"},
    {"goal": "Generate visualization chart", "context": "Use matplotlib"},
])

7 Terminal Backends

Hermes supports multiple runtime environments:

|| Backend | Use Case |
||———|———-|
|| Local | Local development |
|| Docker | Containerized deployment |
|| SSH | Remote servers |
|| Modal | Serverless GPU |
|| Daytona | Serverless dev environment |
|| Singularity | HPC clusters |
|| Vercel Sandbox | Edge computing |

Web Dashboard

Hermes ships with a browser-based Web Dashboard for managing your installation without touching YAML files. Run it with:

1
hermes dashboard

This starts a local web server at http://127.0.0.1:9119. The dashboard includes:

  • Status Page — Live overview of agent version, gateway status, connected platforms, and active sessions (auto-refreshes every 5 seconds)
  • Chat Tab — Embeds the full Hermes TUI in the browser via WebSocket + PTY. Slash commands, tool-call cards, markdown streaming, and skinning all work identically to the terminal
  • Config Editor — Form-based editor for config.yaml with 150+ fields organized into tabbed categories (model, terminal, display, agent, delegation, memory, approvals). Booleans render as toggles, known values as dropdowns
  • API Keys Manager — Manage .env credentials by category (LLM Providers, Tool API Keys, Messaging Platforms). Each key shows a redacted preview, description, and a link to the provider’s signup page
  • Sessions Browser — Full-text search across all message content using FTS5. Expand any session to view color-coded messages, markdown rendering, and collapsible tool-call blocks
  • Logs Viewer — View and filter agent, gateway, and error logs with live tailing, severity color-coding, and component filtering
  • Analytics — Usage and cost analytics computed from session history: token usage charts, per-model breakdowns, cache hit rates, and daily cost tables
  • Cron Manager — Create, pause, resume, and trigger scheduled jobs from the UI
  • Skills Manager — Browse, search, and toggle skills and toolsets with category filters

Prerequisites: Install the web and PTY extras:

1
pip install 'hermes-agent[web,pty]'

Advanced options:

1
2
3
4
hermes dashboard --port 8080          # Custom port
hermes dashboard --host 0.0.0.0       # Bind to all interfaces (use caution)
hermes dashboard --no-open            # Don't auto-open browser
hermes dashboard --tui                # Enable the in-browser Chat tab

⚠️ Security: The dashboard binds to 127.0.0.1 by default. Binding to 0.0.0.0 exposes your API keys on the network — only do this with a firewall and strong authentication.

After changing API keys via the dashboard, reload them in an active CLI session with:

1
/reload

API Server

Hermes exposes an OpenAI-compatible API endpoint so any OpenAI-compatible frontend (Open WebUI, LobeChat, LibreChat, NextChat, ChatBox, etc.) can connect to it as a backend. Your agent handles requests with its full toolset — terminal, file operations, web search, memory, skills — and returns the final response.

Setup:

  1. Enable the API server in ~/.hermes/.env:
1
2
3
API_SERVER_ENABLED=true
API_SERVER_KEY=change-me-local-dev
# API_SERVER_CORS_ORIGINS=http://localhost:3000  # Optional
  1. Start the gateway:
1
hermes gateway

You’ll see: [API Server] API server listening on http://127.0.0.1:8642

  1. Connect any OpenAI-compatible client at http://localhost:8642/v1:
1
2
3
4
curl http://localhost:8642/v1/chat/completions \
  -H "Authorization: Bearer change-me-local-dev" \
  -H "Content-Type: application/json" \
  -d '{"model": "hermes-agent", "messages": [{"role": "user", "content": "Hello!"}]}'

Features:

  • Standard OpenAI Chat Completions format — Drop-in replacement for OpenAI API
  • Streaming support — Server-Sent Events (SSE) with token-by-token chunks plus custom hermes.tool.progress events for tool UX
  • Inline image input — Support for image_url content parts with remote URLs and data URIs
  • Full toolset access — Unlike standard OpenAI endpoints, Hermes agents can call tools, browse the web, execute code, and access memory
  • Streaming tool progress — When streaming, tool progress indicators appear inline so frontends can show what the agent is doing

Step 6: Security Configuration

Hermes provides multi-layered security controls:

Command Approval

By default, Hermes prompts you before executing dangerous commands like rm -rf or git reset --hard:

1
2
3
4
5
# Smart approval: auto-approve low-risk, prompt on high-risk
hermes config set approvals.mode smart

# Skip all approvals (not recommended)
hermes config set approvals.mode off

Secret Redaction

Enable auto-masking of API keys and sensitive info in tool output:

1
hermes config set security.redact_secrets true

DM Pairing

For messaging platforms, DM pairing is enabled by default — unknown senders need a pairing code before they can interact with Hermes:

1
hermes pairing approve <platform> <code>

FAQ

Q: How do I migrate from OpenClaw to Hermes?

Hermes provides an automatic migration tool:

1
2
hermes claw migrate              # Interactive migration
hermes claw migrate --dry-run    # Preview migration content

This imports: SOUL.md persona file, memories, skills, command allowlists, messaging configs, API keys, and more.

Q: How do I run Hermes on a remote server?

Use the hermes gateway mode. Start the gateway on the server, then use it remotely via Telegram/Discord/etc. The Gateway supports systemd user services for automatic startup.

Q: How do I switch models?

Use the slash command in chat:

1
/model anthropic/claude-sonnet-4

Or via CLI:

1
hermes model

Q: Does Hermes support local models?

Yes. You can use any local model served via an OpenAI-compatible API (e.g., Ollama, vLLM, llama.cpp). Set the base_url in your config to point to your local model endpoint.

Advanced Tips

Customize Behavior with Config File

Hermes’ config file ~/.hermes/config.yaml includes rich options:

1
2
3
4
5
6
7
8
9
10
11
model:
  default: anthropic/claude-sonnet-4
  provider: openrouter

agent:
  max_turns: 90              # Maximum conversation turns
  tool_use_enforcement: true # Force tool usage

compression:
  enabled: true              # Enable context compression
  threshold: 0.50            # Compression trigger threshold

Create Custom Skills

You can manually create skills to solidify specific workflows:

1
2
3
4
# Create skill directory
mkdir -p ~/.hermes/skills/my-custom-skill

# Write SKILL.md

Skill files should include clear step-by-step instructions, prerequisites, and caveats.

Run Multiple Instances with Worktree Mode

When running multiple Hermes instances in parallel, use -w worktree mode to avoid Git conflicts:

1
hermes -w    # Worktree mode

Conclusion

Hermes Agent is a powerful, continuously evolving AI agent framework. Through this tutorial, you’ve learned:

  • ✅ Installing and configuring Hermes Agent
  • ✅ Choosing LLM providers and connecting models
  • ✅ Launching interactive chat and messaging gateway
  • ✅ Using the skills system and persistent memory
  • ✅ Configuring cron jobs and subagent delegation
  • ✅ Using the Web Dashboard for visual management
  • ✅ Connecting OpenAI-compatible frontends via the API Server
  • ✅ Setting up security policies

Hermes’ core value lies in its self-evolving capability — the longer you use it, the better it understands your needs and the more efficient you become. Start your Hermes journey today!

📖 Official Docs: https://hermes-agent.nousresearch.com/docs/
🐛 Issues: https://github.com/NousResearch/hermes-agent/issues
💬 Community Discord: https://discord.gg/NousResearch