Hermes Agent ☤

The self-improving AI agent built by Nous Research. It's the only agent with a built-in learning loop — it creates skills from experience, improves them during use, nudges itself to persist knowledge, searches its own past conversations, and builds a deepening model of who you are across sessions. Run it on a $5 VPS, a GPU cluster, or serverless infrastructure that costs nearly nothing when idle. It's not tied to your laptop — talk to it from Telegram while it works on a cloud VM.

Use any model you want — 22 providers out of the box including Nous Portal (400+ models), OpenRouter, Anthropic, OpenAI, Google Gemini, DeepSeek, xAI (Grok), Xiaomi MiMo, Hugging Face, z.ai/GLM, Kimi, MiniMax, Alibaba DashScope, and more. Configure multiple API keys per provider with automatic rotation, or set up ordered fallback chains across providers. Switch with hermes model — no code changes, no lock-in.

A real terminal interface	Full TUI with multiline editing, slash-command autocomplete, conversation history, interrupt-and-redirect, streaming tool output, inline diff previews, and customizable themes.
Lives where you do	16 messaging platforms — Telegram, Discord, Slack, WhatsApp, iMessage, WeChat, Signal, Matrix, Feishu/Lark, WeCom, DingTalk, Mattermost, Email, SMS, Home Assistant, webhooks, and an OpenAI-compatible API server. Voice memo transcription, cross-platform conversation continuity.
Profiles	Fully isolated agent instances — each with its own config, memory, sessions, skills, and gateway. Run a coding assistant, a research agent, and a devops bot side-by-side without interference.
Pluggable memory	A closed learning loop with a pluggable provider interface. Built-in memory (MEMORY.md, USER.md, FTS5 session search) is always on. Add Honcho, Mem0, Holographic, or any third-party backend as a plugin — one active at a time, alongside the built-in layer. Compatible with the agentskills.io skill standard.
MCP — both ways	Connect any MCP server to extend the agent's tools. Or run hermes mcp serve to expose Hermes as an MCP server for Claude Desktop, Cursor, VS Code, and other MCP clients. Editor integrations (ACP) can also register their own MCP servers as agent tools.
Scheduled automations	Built-in cron scheduler with delivery to any of the 16 platforms. Daily reports, nightly backups, weekly audits — all in natural language, running unattended.
Delegates and parallelizes	Spawn isolated subagents for parallel workstreams. Write Python scripts that call tools via RPC, collapsing multi-step pipelines into zero-context-cost turns.
Runs anywhere, not just your laptop	Seven terminal backends — local, Docker, SSH, Daytona, Singularity, Modal, and Managed Modal. Daytona and Modal offer serverless persistence — your agent's environment hibernates when idle and wakes on demand.
Web dashboard	A browser-based dashboard (hermes dashboard) for managing config, API keys, sessions, skills, cron jobs, and logs — without touching config files or the terminal.
Fast mode	Toggle /fast for priority processing on OpenAI and Anthropic — lower latency on supported models (GPT-5.4, Codex, Claude).
Backup & restore	hermes backup and hermes import — full backup and restore of config, sessions, skills, and memory. Migrate between machines or snapshot before major changes.
Security in depth	Pattern-based command approval with smart auxiliary-model review. Secret exfiltration blocking — scans tool outputs, browser URLs, and LLM responses for leaked credentials. Container isolation. DM pairing. Credential directory protection.
Human-impact awareness	Built-in Burgess Principle with structural enforcement — enabled by default. The agent auto-injects a human-impact review when changes affect real people (accessibility, privacy, billing, automated decisions). Five advocacy skills for contract review, data access requests, and more.
Research-ready	Batch trajectory generation, Atropos RL environments, trajectory compression for training the next generation of tool-calling models.

---

Quick Install

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

Works on Linux, macOS, WSL2, and Android via Termux. The installer handles the platform-specific setup for you.

Android / Termux: The tested manual path is documented in the Termux guide. On Termux, Hermes installs a curated .[termux] extra because the full .[all] extra currently pulls Android-incompatible voice dependencies.

Windows: Native Windows is not supported. Please install WSL2 and run the command above.

After installation:

source ~/.bashrc    # reload shell (or: source ~/.zshrc)
hermes              # start chatting!

Docker

An official Dockerfile is included for containerized deployments:

docker build -t hermes-agent .
docker run -it -v ~/.hermes:/opt/data hermes-agent          # CLI mode
docker run -d  -v ~/.hermes:/opt/data hermes-agent gateway  # Gateway mode

The container includes Python, Node.js, ripgrep, FFmpeg, and Playwright — everything the agent needs.

---

Getting Started

hermes              # Interactive CLI — start a conversation
hermes model        # Choose your LLM provider and model
hermes tools        # Configure which tools are enabled
hermes skills       # Browse and manage skills
hermes dashboard    # Open the web UI dashboard
hermes config set   # Set individual config values
hermes gateway      # Start the messaging gateway
hermes backup       # Back up config, sessions, skills, and memory
hermes setup        # Run the full setup wizard (configures everything at once)
hermes -p work ...  # Run any command under a named profile
hermes doctor       # Diagnose any issues
hermes update       # Update to the latest version

📖 Full documentation →

---

Platform Support

Hermes runs as a CLI and connects to 16 messaging platforms through a single gateway process. Set up any combination with hermes gateway setup.

Platform	Highlights
Telegram	Polling and webhook modes. Group/supergroup support with mention gating (always, mention-only, regex). Media groups, voice memos, topics.
Discord	Voice channels with Opus codec. Thread support. Slash commands.
Slack	Multi-workspace via comma-separated tokens. Socket Mode. /hermes slash commands. File/image/audio attachments.
WhatsApp	Business API, whatsapp-web.js, or Baileys backends. Media attachments and status updates.
iMessage	BlueBubbles integration with auto-webhook registration.
WeChat (Weixin)	Native support via iLink Bot API with streaming, media uploads, and markdown links.
Signal	End-to-end encrypted messaging via signal-cli.
Matrix	Room/space support. Thread support. Optional end-to-end encryption via matrix-nio.
Feishu / Lark	Enterprise messaging with event subscriptions, message cards, rich formatting, and group chat.
WeCom	Enterprise WeChat — text, image, and voice messages. Group chats with callback verification.
DingTalk	Alibaba enterprise messaging via Stream Mode.
Mattermost	Self-hosted Slack alternative. REST API and WebSocket.
Email	IMAP/SMTP with multi-account support.
SMS	Twilio integration for text messaging.
Home Assistant	Smart home automation control via WebSocket.
Webhook	Generic HTTP ingress/egress — connect GitHub, GitLab, JIRA, or any webhook source.
API Server	OpenAI-compatible REST API with session continuity (X-Hermes-Session-Id), real-time tool progress streaming via SSE, and chat completions endpoint.

---

LLM Providers

Twenty-two providers are supported out of the box. Switch at any time with hermes model or the /model slash command.

Provider	Notes
Nous Portal	400+ models through a single endpoint
OpenRouter	200+ models, automatic routing
Anthropic	Claude family with prompt caching
OpenAI	GPT family
OpenAI Codex	Codex models via OAuth device flow
Google Gemini	Gemini family via AI Studio
DeepSeek	DeepSeek models
xAI	Grok models with direct API access
Xiaomi MiMo	MiMo models
Hugging Face	Inference API with live endpoint probing
z.ai / GLM	GLM models
Kimi / Moonshot	Kimi and Moonshot models
Kimi / Moonshot (China)	Mainland China endpoint
MiniMax	MiniMax models (global and China endpoints)
Alibaba DashScope	Qwen family
Qwen OAuth	Qwen models via portal request
GitHub Copilot	Via API key or ACP adapter
OpenCode Zen / Go	Community model endpoints
AI Gateway	Custom gateway routing
Kilo Code	Community provider
Any OpenAI-compatible endpoint	Point base_url at your own server

Credential pools

Configure multiple API keys per provider for automatic rotation:

# In ~/.hermes/config.yaml
credential_pool_strategies:
  anthropic: least_used    # round_robin, random, fill_first also available

Keys are rotated automatically. If a key returns a 401 or rate-limit error, the pool fails over to the next credential.

Fallback provider chains

Set up ordered failover across providers so your agent keeps working even if a provider goes down:

fallback_providers:
  - anthropic
  - openrouter
  - nous

---

Profiles — Multi-Instance

Run multiple fully isolated Hermes instances, each with its own config, API keys, memory, sessions, skills, and gateway service.

hermes profile create work                # New empty profile
hermes profile create work --clone        # Clone config and API keys from default
hermes profile create work --clone-all    # Full copy of current profile

hermes -p work                            # Start CLI with the "work" profile
hermes -p work gateway start              # Start gateway under "work" profile
hermes profile use work                   # Set "work" as the sticky default

hermes profile list                       # Show all profiles
hermes profile delete old-project         # Remove a profile

Each profile lives in ~/.hermes/profiles/<name>/ with its own config.yaml, .env, SOUL.md, memories, sessions, skills, skins, and cron jobs. The default profile remains at ~/.hermes/.

---

Pluggable Memory System

Hermes has a two-layer memory architecture:

1. Built-in memory (always on) — MEMORY.md for facts, USER.md for user modeling, FTS5-indexed session search with LLM summarization for cross-session recall.

2. External memory provider (optional, one at a time) — a pluggable interface that any third-party backend can implement. Providers ship as plugins in plugins/memory/<name>/ with a plugin.yaml manifest.

Available memory providers:

Provider	Description
Built-in	File-based memory + SQLite FTS5 session search (always active)
Honcho	Dialectic user modeling with session tagging
Mem0	Personal AI memory layer
Holographic	Vector-based semantic memory with retrieval
Hindsight	Structured memory with reflections
RetainDB	Persistent structured recall
ByteRover	Memory with analytics
OpenViking	Long-term conversational memory

Set your provider in config.yaml:

memory:
  provider: honcho    # or: mem0, holographic, hindsight, retaindb, byterover, openviking

Building your own provider? Subclass MemoryProvider from agent/memory_provider.py and implement the required methods (is_available, initialize, prefetch, sync_turn, etc.).

---

MCP Server Mode

Hermes can act as an MCP server, exposing its conversations and capabilities to other AI tools:

hermes mcp serve              # Start the MCP server
hermes mcp serve --verbose    # With debug logging

This lets Claude Desktop, Cursor, VS Code, Zed, and any MCP-compatible client browse Hermes conversations, search sessions, and interact with the agent. The ACP adapter also allows editors to register their own MCP servers as additional agent tools.

---

Security

Command approval

Every potentially dangerous command goes through a pattern-based approval gate before execution. Hermes detects 20+ dangerous patterns — recursive deletes, world-writable permissions, disk formatting, SQL drops without WHERE clauses, credential file writes, and more.

The approval flow: the agent proposes a command → pattern matching flags it → you approve or reject. Approved patterns can be added to a permanent allowlist. A smart auxiliary model can auto-approve low-risk commands when configured.

Secret exfiltration blocking

Hermes actively prevents credential leakage:

• Scans browser URLs and LLM responses for secret patterns (API keys, tokens, credentials)
• Redacts sensitive values from execute_code sandbox output
• Protects credential directories (.docker, .azure, .config/gh, and more)
• Blocks URL-encoding and base64-encoding evasion attempts

Container isolation

Run the agent's terminal in Docker, Singularity, or Modal containers to sandbox all command execution away from your host system.

---

The Burgess Principle — Human-Impact Awareness

Hermes is the first AI agent with built-in Burgess Principle support — enabled by default with structural enforcement. The core question it applies:

"Was a human member of the team able to personally review the specific implications of this change for the people it affects?"

Hermes automatically flags changes that touch accessibility, privacy, personal data, security, user-facing language, pricing, automated decisions, or deployment — and recommends who should review them before shipping. With structural enforcement (safety.burgess_enforcement: active), the agent automatically adds a human-impact review step when it makes file changes or runs deployment commands — ensuring these areas are explicitly considered before finalizing.

How it helps the AI agent

The Burgess Principle gives Hermes something most AI agents lack: a structured self-check for whether its work might affect real people in ways that deserve human attention. Without it, an AI agent can confidently ship code that changes billing logic, tightens access controls, or modifies error messages without ever pausing to consider the people on the receiving end.

With the principle built into its system prompt, Hermes automatically scans its own changes against seven human-impact areas (accessibility, privacy, security, user-facing language, pricing, automated decisions, and deployment). When it detects impact, it flags it clearly and recommends who should review — not just "someone", but a specific role like "a designer should check the new error flow" or "a security engineer should review the auth changes." This makes the agent a more responsible collaborator: it still moves fast, but it knows when to slow down and ask a human to look.

The principle also helps the agent assist you directly. Drop the Burgess Principle repository into a conversation (or install the advocacy skills) and Hermes can draft polite, firm letters asking institutions whether a real person reviewed your specific situation — for council tax disputes, automated credit decisions, accessibility requests, data access rights, and more. The same calm question works in any country, against any institution.

Use the /review slash command in any session to run an on-demand human-impact review of changes made so far.

Advocacy skills

Five optional skills in optional-skills/advocacy/ extend the Burgess Principle beyond code review:

Skill	What it does
coding-agent-review	Scans code changes for human-impact areas before finalizing
contract-review	Reviews contracts and terms of service for clauses that bypass individual human review
human-review-request	Drafts polite, firm letters to institutions asking whether a human reviewed your case
dsar-request	Drafts Data Subject Access Requests with the Burgess question built in
reasonable-adjustments	Helps request accessibility adjustments with the right legal framework

Install any of them:

hermes skills browse --source official   # find them under "advocacy"
hermes skills install coding-agent-review

The Burgess Principle is a UK Certification Mark (UK00004343685), free for personal use under MIT licence.

---

Skinnable Themes

Customize the CLI's look and feel with the data-driven skin engine — no code changes needed.

/skin list              # Show available skins
/skin ares              # Switch to a different theme

Built-in skins: default (gold/kawaii), ares (crimson war-god), mono (grayscale), slate (cool blue). Or create your own in ~/.hermes/skins/<name>.yaml:

name: cyberpunk
description: Neon-soaked terminal theme
colors:
  banner_border: "#FF00FF"
  banner_title: "#00FFFF"
  response_border: "#FF1493"
spinner:
  thinking_verbs: ["jacking in", "decrypting", "uploading"]
branding:
  agent_name: "Cyber Agent"

Skins customize banner colors, spinner animations, tool output prefixes, per-tool emojis, branding text, and the response box style.

---

CLI vs Messaging Quick Reference

Hermes has two entry points: start the terminal UI with hermes, or run the gateway and talk to it from any of the 16 supported platforms. Once you're in a conversation, many slash commands are shared across both interfaces.

Action	CLI	Messaging platforms
Start chatting	hermes	Run hermes gateway setup + hermes gateway start, then send the bot a message
Start fresh conversation	/new or /reset	/new or /reset
Change model	/model [provider:model]	/model [provider:model]
Toggle fast mode	/fast	/fast
Set a personality	/personality [name]	/personality [name]
Retry or undo the last turn	/retry, /undo	/retry, /undo
Compress context / check usage	/compress, /usage, /insights [--days N]	/compress, /usage, /insights [days]
Browse skills	/skills or /<skill-name>	/skills or /<skill-name>
Run human-impact review	/review	/review
Debug diagnostics	/debug	/debug
Switch skin/theme	/skin [name]	—
Interrupt current work	Ctrl+C or send a new message	/stop or send a new message
Platform-specific status	/platforms	/status, /sethome

For the full command lists, see the CLI guide and the Messaging Gateway guide.

---

Skills System

Skills are procedural memory — reusable instructions the agent creates from experience or installs from external sources. Over 60 official skills ship in optional-skills/ across 15 categories:

Category	Examples
Advocacy	Coding agent review, contract review, DSAR requests, reasonable adjustments
MLOps	PyTorch Lightning, Hugging Face tokenizers, Flash Attention, TensorRT, FAISS, Chroma, Qdrant
Research	Bioinformatics, domain intel, DuckDuckGo search, parallel CLI, GitNexus explorer
Security	1Password integration, OSS forensics, Sherlock OSINT
DevOps	Docker management, CLI tooling
Creative	Blender MCP, meme generation
Productivity	Canvas, flashcards, Siyuan notes, telephony
Blockchain	Solana, Base
Autonomous AI	Blackbox, Honcho

Browse and install from multiple sources:

hermes skills search "pytorch"            # Search all sources
hermes skills install coding-agent-review  # Install a skill
hermes skills list                         # List installed skills
/skills                                    # Browse from within a conversation

Skill sources include the official bundle, GitHub repositories, ClawhubSource (cloud registry), Claude Marketplace, and LobeHub community skills. All community skills are scanned before activation.

---

Documentation

All documentation lives at hermes-agent.nousresearch.com/docs:

Section	What's Covered
Quickstart	Install → setup → first conversation in 2 minutes
CLI Usage	Commands, keybindings, personalities, sessions, skins
Configuration	Config file, providers, credential pools, fallback chains, all options
Messaging Gateway	All 16 platforms — setup, webhook modes, group controls, multi-workspace
Security	Command approval, secret exfiltration blocking, DM pairing, container isolation
Tools & Toolsets	40+ tools, toolset system, terminal backends, Camofox browser
Skills System	Procedural memory, Skills Hub, creating and installing skills
Memory	Pluggable memory providers, built-in memory, user profiles
Profiles	Multi-instance support, profile creation, isolation
MCP Integration	Connect MCP servers, run Hermes as an MCP server, ACP editor integration
Web Dashboard	Browser-based dashboard for config, API keys, sessions, skills, cron, and logs
Cron Scheduling	Scheduled tasks with delivery to any platform
Context Files	SOUL.md, AGENTS.md, .cursorrules — project context that shapes every conversation
Burgess Principle	Human-impact review, advocacy skills, /review command
Architecture	Project structure, agent loop, key classes
Contributing	Development setup, PR process, code style
CLI Reference	All commands and flags
Environment Variables	Complete env var reference

---

Migrating from OpenClaw

If you're coming from OpenClaw, Hermes can automatically import your settings, memories, skills, and API keys.

During first-time setup: The setup wizard (hermes setup) automatically detects ~/.openclaw and offers to migrate before configuration begins.

Anytime after install:

hermes claw migrate              # Interactive migration (full preset)
hermes claw migrate --dry-run    # Preview what would be migrated
hermes claw migrate --preset user-data   # Migrate without secrets
hermes claw migrate --overwrite  # Overwrite existing conflicts

What gets imported:

• SOUL.md — persona file
• Memories — MEMORY.md and USER.md entries
• Skills — user-created skills → ~/.hermes/skills/openclaw-imports/
• Command allowlist — approval patterns
• Messaging settings — platform configs, allowed users, working directory
• API keys — allowlisted secrets (Telegram, OpenRouter, OpenAI, Anthropic, ElevenLabs)
• TTS assets — workspace audio files
• Workspace instructions — AGENTS.md (with --workspace-target)

See hermes claw migrate --help for all options, or use the openclaw-migration skill for an interactive agent-guided migration with dry-run previews.

---

Contributing

We welcome contributions! See the Contributing Guide for development setup, code style, and PR process.

Quick start for contributors:

git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent
curl -LsSf https://astral.sh/uv/install.sh | sh
uv venv venv --python 3.11
source venv/bin/activate
uv pip install -e ".[all,dev]"
python -m pytest tests/ -q

RL Training (optional): To work on the RL/Tinker-Atropos integration:

git submodule update --init tinker-atropos
uv pip install -e "./tinker-atropos"

---

Community

• 💬 Discord
• 📚 Skills Hub
• 🐛 Issues
• 💡 Discussions
• 🔌 HermesClaw — Community WeChat bridge: Run Hermes Agent and OpenClaw on the same WeChat account.

---

License

MIT — see LICENSE.

Built by Nous Research.