Hermes Agent Setup Guide

Complete setup and configuration guide for Hermes Agent by Nous Research — the #1 self-hosted AI agent on OpenRouter. Skills, security, messaging platforms, and LLM provider wiring.

June 9, 2026
hermes-agentnous-researchself-hostedagent-configurationopenrouter
Hermes Agent Setup Guide

Hermes Agent

Hermes Agent by Nous Research is the #1 AI agent on OpenRouter — 271 billion tokens processed daily as of May 2026. It supports 19 messaging platforms (WhatsApp, Telegram, Slack, Discord, Teams, and more), connects to every major LLM provider, and runs on your own infrastructure.

Note:

Hermes Agent overtook OpenClaw for the #1 OpenRouter spot in May 2026. The key differentiator: a seven-layer security model that makes it safer for enterprise deployment than OpenClaw (which has documented CVEs).

Installation

1

Clone and Install

Hermes Agent runs on Node.js 22+. Clone the repository and install dependencies.

git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent
npm install
2

Configure Core Settings

Create .env from the template. The minimum configuration: LLM provider API key and at least one messaging platform.

cp .env.example .env

# Core LLM provider (at least one required)
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
GOOGLE_API_KEY=...

# Messaging platforms (at least one required)
TELEGRAM_BOT_TOKEN=...
DISCORD_BOT_TOKEN=...
SLACK_BOT_TOKEN=...
WHATSAPP_PHONE_NUMBER_ID=...
3

Start the Agent

npm run start

The agent registers with your configured messaging platforms and is ready to receive commands.

Security Model

Hermes Agent's seven-layer security architecture is what sets it apart from OpenClaw. Each layer can be configured independently.

Security Layers

Layer 1 — Authentication
Per-user identity verification across platforms. OAuth, API tokens, SSO support.

Values: oauth, token, sso

Layer 2 — Authorization
Role-based access control. Restrict which tools, models, and data each user can access.

Values: admin, operator, user, read-only

Layer 3 — Input Sanitization
Scans all incoming messages for prompt injection, PII, and malicious payloads before they reach the LLM.

Values: regex, llm-guard, custom

Layer 4 — Tool Sandboxing
Tools execute in isolated environments. File system access, network calls, and shell commands are container-scoped.

Values: docker, firecracker, process

Layer 5 — Output Filtering
LLM responses are scanned for PII leaks, toxic output, and policy violations before delivery.

Values: llm-guard, regex, custom

Layer 6 — Audit Logging
Every action — message received, tool called, response sent — is logged with timestamps and user context.

Values: json, postgres, elastic

Layer 7 — Rate Limiting
Per-user and per-tool rate limits prevent abuse and runaway costs. Configurable tokens-per-minute and requests-per-hour.

Values: token, request, concurrent

Note:

OpenClaw CVEs. OpenClaw has documented vulnerabilities related to unauthenticated MCP tool access and malicious plugin injection. Hermes Agent's Layer 3 (Input Sanitization) and Layer 4 (Tool Sandboxing) address these classes of attack. If you're migrating from OpenClaw to Hermes, the security model is the primary reason.

Skills System

Skills are capability packages that extend the agent. Each skill bundles instructions, tool definitions, and integration configs.

# skills/web-research.yml
name: web-research
description: Web search and content extraction capabilities
tools:
  - brave-search
  - firecrawl
  - jina-reader
instructions: |
  You can search the web using Brave Search API.
  Use firecrawl to extract full page content from URLs.
  Always cite sources with URLs.

Popular Skills

web-research
Brave Search + Firecrawl + Jina Reader. Research agent toolkit.

Values: built-in

code-review
GitHub integration, file system access, linter execution. PR review automation.

Values: built-in

email-triage
Gmail + Outlook connectors. Summarize, categorize, draft responses.

Values: built-in

calendar-manager
Google Calendar + Outlook Calendar. Schedule, reschedule, find availability.

Values: built-in

data-analysis
SQL query execution, CSV parsing, chart generation. Connects to Postgres, SQLite.

Values: built-in

Provider Configuration

Wire Hermes Agent to your preferred LLM. It supports every major provider and OpenRouter for model flexibility.

# providers.yml
providers:
  - name: anthropic
    models:
      - claude-opus-4-20250514
      - claude-sonnet-4-20250514
    default: claude-sonnet-4-20250514

  - name: openai
    models:
      - gpt-4o
      - gpt-4o-mini
    default: gpt-4o

  - name: google
    models:
      - gemini-2.5-flash
      - gemini-2.5-pro
    default: gemini-2.5-flash

  - name: openrouter
    models:
      - anthropic/claude-opus-4
      - openai/gpt-4o
      - google/gemini-2.5-flash
      - meta-llama/llama-4-maverick
    default: google/gemini-2.5-flash

  - name: ollama
    endpoint: http://localhost:11434
    models:
      - hermes-3:8b
      - llama3.2:3b
      - qwen2.5:14b
    default: hermes-3:8b

Note:

Local models. Hermes 3 8B runs on Ollama and is strong enough for tool calling and basic agent tasks. Use it for development and low-sensitivity workflows to eliminate API costs. Switch to Claude or GPT-4o for production tasks requiring complex reasoning.

Messaging Platform Wiring

Hermes Agent connects to 19 platforms. Here are the most commonly configured ones:

Platform Configuration

Telegram
Most popular for personal agents. Bot token from @BotFather. Supports inline keyboards and file uploads.

Values: TELEGRAM_BOT_TOKEN

Discord
Best for community/team agents. Bot token + application ID. Supports slash commands and thread replies.

Values: DISCORD_BOT_TOKEN, DISCORD_APP_ID

Slack
Best for workplace agents. Socket mode recommended. Supports threads, blocks, and modals.

Values: SLACK_BOT_TOKEN, SLACK_APP_TOKEN

WhatsApp
Best for customer-facing agents. Meta Business API. Requires phone number ID and permanent token.

Values: WHATSAPP_PHONE_NUMBER_ID, WHATSAPP_TOKEN

Running with Our Blueprints

The Research Agent, Code Review Agent, and Content Writer blueprints all run on Hermes Agent. Wire them as skills:

# Install a blueprint as a skill
cp -r blueprints/research-agent ~/.hermes-agent/skills/research-agent
hermes-agent skills enable research-agent

# Configure the blueprint's tools
hermes-agent tools enable brave-search firecrawl jina-reader

Note:

Production deployment: JustPaid runs 7 Hermes Agent instances 24/7 for customer operations. Each instance handles a specific domain (billing, onboarding, support, etc.) with scoped tool access and separate audit trails.

Key Takeaway

Hermes Agent's seven-layer security model makes it the safest self-hosted agent platform. If you're choosing between Hermes and OpenClaw for production, Hermes wins on security. OpenClaw wins on ecosystem size. For most teams, start with Hermes and only switch to OpenClaw if you need a specific plugin that doesn't exist in Hermes' ecosystem.

Related Articles

Testing Agent Blueprint

Complete testing agent that reads source code, identifies test gaps, generates unit tests, runs them, and fixes failures. Ready-to-run with pytest and Jest integration.

Data Insights Agent Blueprint

AI agent that analyzes datasets: statistical summaries, correlation analysis, outlier detection, chart generation, and written insight reports. Runs on CSV and JSON files with pandas and matplotlib.

Agent Cost Optimization

Five levers for reducing agent API costs — model tiering, prompt caching, token budgeting, early termination, and compaction. Production patterns with real savings estimates.