Hermes Agent Guide: Install, Model Integration, Skills, MCP, Message Gateway

Overview

Hermes Agent is an open‑source AI‑agent framework released by Nous Research in 2026, positioned as “the agent that grows with you”. It differs from Claude Code, OpenClaw and Cursor by supporting self‑evolving skills, persistent memory and multi‑platform automation.

Key Features

Supports 20+ model providers and live model switching.

Skill system that can persist complex workflows.

Persistent memory for user preferences and project context.

MCP client/server dual mode.

Integration with 17 messaging platforms (Telegram, Discord, Slack, Feishu, WeCom, QQBot, etc.).

Multiple execution back‑ends (local, Docker, SSH, Modal, Daytona, Singularity).

Version v0.11.0

Released 2026‑04‑23, adds a React/Ink TUI, Transport architecture unifying Anthropic, OpenAI, AWS Bedrock, new providers (NVIDIA NIM, Arcee AI, Step Plan, Gemini CLI OAuth, Vercel AI Gateway), GPT‑5.5 support, QQBot, enhanced plugin system and the /steer command for mid‑task correction.

Installation

One‑click script installs Python, Node.js, ripgrep, ffmpeg, clones the repository, creates a virtual environment and registers the hermes command.

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

After installation run source ~/.zshrc (or source ~/.bashrc) and verify with hermes version and hermes doctor.

Initial Configuration

Run hermes setup to configure the main model provider, API key, default model, tool switches, gateway platform, execution environment, memory and skill system. Individual steps can be performed with hermes model for model selection.

Model Provider Configuration

Hermes supports providers such as Nous Portal, OpenRouter, OpenAI, Anthropic, Google Gemini, DeepSeek, Z‑AI/GLM, Kimi/Moonshot, MiniMax, NVIDIA NIM, AWS Bedrock, Vercel AI Gateway and custom OpenAI‑compatible endpoints. Example OpenAI config:

provider: openai
model: gpt-5.5

API key stored in ~/.hermes/.env as OPENAI_API_KEY=sk‑…. Similar files exist for other providers.

Auxiliary Models and Cost Reduction

Because each request carries a large tool definition (6‑8 k tokens for CLI, 15‑20 k for gateway), it is recommended to use a strong model for the primary task and a cheaper model for auxiliary tasks such as compression or delegation. DeepSeek‑v4‑pro is suggested for main tasks, DeepSeek‑v4‑flash for compression.

auxiliary:
  compression:
    provider: deepseek
    model: deepseek-v4-flash
  delegation:
    provider: deepseek
    model: deepseek-v4-flash

Execution Environment

Supported back‑ends:

local – run on the host machine.

docker – sandboxed container (recommended for code execution).

ssh – remote server.

modal, daytona, singularity – cloud or HPC options.

Docker configuration example:

terminal:
  backend: docker
  docker_image: nikolaik/python-nodejs:python3.11-nodejs20
  docker_forward_env:
    - GITHUB_TOKEN
  docker_volumes:
    - /home/user/projects:/workspace/projects
    - /home/user/data:/data:ro
  container_cpu: 2
  container_memory: 8192
  container_disk: 51200

Personality (SOUL.md)

The SOUL.md file defines the agent’s persona and is injected as a system prompt for every session. Example content includes concise communication style, risk‑aware behavior, and execution preferences. Personality can be switched at runtime with slash commands such as /personality technical.

Skill System

Skills are stored under ~/.hermes/skills/ as a directory containing a SKILL.md front‑matter file. The file describes name, description, version, platforms, metadata and a step‑by‑step procedure. Skills can be listed, installed from GitHub or ClawHub, and created on the fly.

hermes skills list
hermes skills install github:username/repo/skills/my-skill

Memory

Two memory files – MEMORY.md (project facts) and USER.md (user preferences) – are loaded each turn. Configuration controls size limits and enables/disables each store.

memory:
  memory_enabled: true
  user_profile_enabled: true
  memory_char_limit: 2200
  user_char_limit: 1375

MCP Integration

Hermes can act as an MCP client (connecting to external services such as GitHub, Filesystem, Context7, Figma, PostgreSQL, Firecrawl) or as an MCP server exposing its own session, memory and skill APIs via hermes mcp serve. Clients like Claude Desktop or Cursor can call these endpoints.

Message Gateway

Gateway enables the agent to send and receive messages on platforms including Telegram, Discord, Slack, WhatsApp, Signal, Email, Matrix, DingTalk, Feishu/Lark, WeCom, WeChat, iMessage, QQBot, Mattermost, Home Assistant, Webhook and SMS. Setup is performed with hermes gateway setup and started with hermes gateway start. Security advice: keep the gateway port private, use Tailscale or Nginx with IP whitelist.

Cron Scheduler

Recurring tasks are added with hermes cron add "CRON_EXPRESSION" "DESCRIPTION". Example daily AI‑news summary at 08:30 and hourly service health check.

Security Configuration

Key settings include secret redaction, Tirith policy enforcement, website blocklist, approval modes (smart, manual, off), code‑execution sandbox, and limits on tool calls. Recommended practices: store API keys only in .env, keep gateway non‑public, run production tasks in Docker, enable redact_secrets and limit max_tool_calls.

Troubleshooting

Command not found – source the shell rc file.

Model context window too small – switch to a model with ≥64 k token window.

429 rate limit – change provider, lower concurrency, or configure fallback provider.

Gateway not receiving messages – verify webhook URL, app secret, group @‑bot, working directory.

Skill not working – ensure SKILL.md exists, directory structure correct, front‑matter valid, required tools enabled.

Full Configuration Template

A complete ~/.hermes/config.yaml example is provided, covering provider, terminal, agent behavior, memory, compression, auxiliary models, approvals, security, code execution, gateway and display options.

Recommended Configurations

Four scenarios are outlined:

Low‑cost long‑running (DeepSeek primary, DeepSeek‑flash auxiliary).

High‑quality complex tasks (OpenAI Claude‑opus primary, OpenAI gpt‑5.4‑mini auxiliary via HongMaCC).

MiniMax Token‑Plan (MiniMax‑M2.7).

OpenRouter “all‑in‑one” (OpenRouter provider with Claude‑sonnet).

Conclusion

Hermes Agent is best suited for users who need a persistent personal AI assistant, want to turn repetitive workflows into reusable Skills, require multi‑platform messaging, and wish to switch freely among Claude, GPT, DeepSeek, Kimi or MiniMax models. It is less appropriate for pure coding without messaging needs, for users unwilling to manage API keys and YAML, or for strict enterprise production where stability is paramount.