Hermes Agent — Ecosystem Guide
Author
DW
Date Published
# Hermes Agent — Complete Configuration & Ecosystem Guide
> **Source basis:** Official Nous Research docs, canonical GitHub repo (`NousResearch/hermes-agent`), community awesome list (`0xNyk/awesome-hermes-agent`), and the `researchwang13.space/hermes/` tool reference (image-sourced, April 2026). All region-specific access notes removed — global supply chain assumed throughout.
---
## What Is Hermes Agent?
Hermes is an open-source, self-improving AI agent built by [Nous Research](https://nousresearch.com) — the lab behind the Hermes, Nomos, and Psyche model families. MIT-licensed. [github.com/NousResearch/hermes-agent](https://github.com/NousResearch/hermes-agent) (23k+ stars, April 2026).
The core proposition differs from typical agent wrappers: Hermes has a **closed learning loop**. It creates skills from experience, improves them during use, maintains persistent cross-session memory, and builds a progressively deeper model of its user. The longer it runs, the more capable it becomes on your specific workload — without manual fine-tuning.
It is not a coding copilot tied to an IDE, nor a chatbot wrapper around a single API. It is a persistent autonomous agent designed to live on infrastructure you control, reachable from any messaging platform, capable of running fully unattended.
---
## Architecture at a Glance
```
┌─────────────────────────────────────────────────────────┐
│ Messaging Gateway │
│ Telegram · Discord · Slack · WhatsApp · Signal · │
│ Matrix · Mattermost · Email · SMS · DingTalk · │
│ Feishu · WeCom · BlueBubbles · Home Assistant │
└────────────────────────┬────────────────────────────────┘
│
┌────────────────────────▼────────────────────────────────┐
│ Core Agent Loop │
│ Prompt building → LLM call → tool dispatch → loop │
│ Context window management (summarisation + caching) │
└──────┬────────────────┬────────────────┬────────────────┘
│ │ │
┌──────▼──────┐ ┌──────▼──────┐ ┌─────▼───────────────┐
│ Tools (47) │ │ Memory │ │ Skills System │
│ web search │ │ MEMORY.md │ │ ~/.hermes/skills/ │
│ browser │ │ USER.md │ │ agentskills.io std │
│ file I/O │ │ FTS5 DB │ │ hub install + scan │
│ terminal │ │ Honcho │ │ │
│ delegation │ │ Mem0 etc │ │ │
└──────┬──────┘ └─────────────┘ └──────────────────────┘
│
┌──────▼──────────────────────────────────────────────────┐
│ Terminal Backends (6) │
│ Local · Docker · SSH · Daytona · Singularity · Modal │
└─────────────────────────────────────────────────────────┘
```
---
## Installation
### Requirements
The only hard prerequisite is **Git**. The installer manages everything else:
| Dependency | Version | Notes |
|---|---|---|
| Python | 3.11 | Installed via `uv`, no sudo required |
| Node.js | 22 | Browser automation and WhatsApp bridge |
| ripgrep | latest | Fast file search |
| ffmpeg | latest | Audio processing for TTS and voice mode |
### Linux / macOS / WSL2
```bash
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
source ~/.bashrc # or ~/.zshrc
hermes
```
### Android (Termux)
Same installer script — Termux is detected automatically. Uses `pkg` for system dependencies and a curated `.[termux]` pip extra. Browser and WhatsApp bootstrapping skipped by default.
```bash
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
```
### Windows
Native Windows is **not supported**. Install [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install) (`wsl --install`), then run the Linux installer from within WSL2.
### Nix / NixOS
Dedicated Nix flake and declarative NixOS module available. See the [Nix & NixOS Setup guide](https://hermes-agent.nousresearch.com/docs/getting-started/nix-setup).
### Post-install Configuration Commands
```bash
hermes model # Choose LLM provider and model
hermes tools # Enable / disable tool groups
hermes gateway setup # Connect messaging platforms
hermes config set # Set individual config values
hermes setup # Full interactive setup wizard
hermes doctor # Diagnose missing dependencies
```
---
## LLM Providers
Hermes works with any OpenAI-compatible endpoint. Switch without code changes via `hermes model`. You pay only for API usage — Hermes itself is free.
### Frontier / Cloud Providers
| Provider | Key Models | Notes |
|---|---|---|
| **OpenRouter** | 200+ models | One API key for everything — recommended starting point |
| **Nous Portal** | Nous-native models | Nous Research's own inference endpoint |
| **OpenAI** | GPT-4o, o1, o3 | Direct API |
| **Anthropic** | Claude 3.5 / 4 series | Via OpenRouter or compatible proxy |
| **Google** | Gemini 2.0 / 2.5 series | Via OpenRouter or compatible proxy |
| **xAI** | Grok-3 | Via OpenRouter |
| **Mistral** | Mistral Large, Codestral | Via OpenRouter |
| **NVIDIA NIM** | Nemotron, Llama-3.1-Nemotron | Direct NIM endpoint |
| **Groq** | Llama 3.3 70B | Ultra-low latency — good for fast subagent tasks |
| **Together AI** | Open model hosting | Budget-friendly inference |
| **Fireworks AI** | Open model hosting | Fast inference, generous free tier |
### Local / Self-hosted
| Provider | Notes |
|---|---|
| **Ollama** | Point at `http://127.0.0.1:11434/v1` — zero ongoing cost |
| **LM Studio** | GUI-based local model runner |
| **vLLM** | Production-grade local serving |
| **Any OpenAI-compat** | Custom endpoints fully supported |
### Subagent Model Routing
Route subagents to a different model than your primary orchestrator:
```yaml
# ~/.hermes/config.yaml
delegation:
model: "google/gemini-2-flash-preview"
provider: "openrouter"
```
Common pattern: powerful frontier model as orchestrator → fast/cheap model for subagent tasks (summarisation, formatting, classification).
---
## Core Features
### Closed Learning Loop
Four mechanisms working together:
- **Autonomous skill creation** — After completing a novel task, Hermes generates a reusable skill document. Next time, it loads the skill rather than reasoning from scratch.
- **Skill self-improvement** — Detects when a skill underperforms and refines it during use.
- **FTS5 cross-session recall** — Every conversation is indexed in a full-text-search SQLite database. Hermes retrieves and summarises relevant past exchanges on demand.
- **Dialectic user modeling** — Via [Honcho](https://github.com/plastic-labs/honcho), Hermes maintains `USER.md`: a structured, continuously-updated model of your preferences, working patterns, and environment.
### Persistent Memory
Two files persist across all sessions in `~/.hermes/`:
- `MEMORY.md` — Curated facts: tech stack, project state, recurring preferences.
- `USER.md` — Deeper model of you as a collaborator.
Context window management is automatic: at ~50% fill, oldest exchanges are replaced with a compact summary. Anthropic prompt caching is applied when Claude is the backend, reducing cost on long sessions.
### Skills System
Skills are on-demand knowledge documents in `~/.hermes/skills/`, following the [agentskills.io](https://agentskills.io/specification) open standard — portable across Hermes, Claude Code, Cursor, and Codex.
**Progressive disclosure** — only the section currently needed is loaded into context, minimising token cost.
Hub-installed skills pass a security scanner (data exfiltration, prompt injection, destructive command checks) before installation.
### Tool System (47 built-in)
| Toolset | Capabilities |
|---|---|
| Web | Search, extract, browse, vision |
| Terminal | Shell execution, file read/write/edit |
| Memory | Read/write memory, search past conversations |
| Delegation | Spawn subagents, `execute_code` RPC |
| Media | Image generation, TTS, voice transcription |
| MCP | Connect any MCP server |
### Subagent Delegation
`delegate_task` spawns child agent instances with isolated context, restricted toolsets, and their own terminal sessions. Default: 3 concurrent subagents (configurable). Use for parallel workstreams — research, writing, and verification running simultaneously.
`execute_code` lets Hermes write Python scripts that call Hermes tools programmatically via sandboxed RPC, collapsing multi-step pipelines into a single LLM inference call.
### Scheduled Automations (Cron)
Natural language or standard cron expressions. Jobs can attach skills, deliver results to any connected platform, and support pause/resume/edit. Typical uses:
- Daily briefing delivered to Telegram
- Nightly server backup with status report
- Hourly monitoring with threshold alerts
### Context Files
Auto-discovered and loaded at session start:
| File | Purpose |
|---|---|
| `.hermes.md` | Hermes-specific project instructions |
| `AGENTS.md` | Cross-agent shared instructions (Claude Code, Codex compatible) |
| `CLAUDE.md` | Claude Code compatibility |
| `SOUL.md` | Personality override for this project |
| `.cursorrules` | Cursor compatibility |
### Context References
Inject content inline with `@`:
```
@src/main.py → file content
@./ → directory listing
@HEAD~3 → git diff
@https://example.com → page content
```
### Checkpoints and Rollback
Working directory is snapshotted before every file change. `/rollback` restores the previous state. No manual git commits needed as a safety net.
### Voice Mode
Full voice interaction across CLI and messaging platforms. Microphone input, spoken replies. Discord voice channel support for live group conversations.
---
## Memory Providers
Beyond the built-in `MEMORY.md` system, external backends are pluggable:
| Provider | Characteristic |
|---|---|
| **Honcho** | Dialectic user modeling — bundled as default |
| **Mem0** | Graph-based memory with entity relationships |
| **OpenViking** | Vector-search memory |
| **Hindsight** | Retrospective learning from outcomes |
| **Holographic** | Distributed memory representation |
| **RetainDB** | SQL-backed structured memory |
| **ByteRover** | Lightweight embedded memory |
---
## Browser Automation
Multiple backends, configured via `hermes tools`:
| Backend | Type | Notes |
|---|---|---|
| **Browserbase** | Cloud | Managed headless browsers — most reliable for production |
| **Browser Use** | Cloud | Alternative managed option |
| **Local Chrome (CDP)** | Local | Attach to a running Chrome instance via DevTools Protocol |
| **Local Chromium** | Local | Hermes manages its own Chromium instance |
| **vessel-browser** | Community | AI-native Linux browser built for agents from the ground up |
| **hermes-cloudflare** | Plugin | Browser rendering through Cloudflare's infrastructure |
---
## Messaging Gateway
15+ platforms from a single gateway process:
| Category | Platforms |
|---|---|
| Real-time messaging | Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Mattermost |
| Email / SMS | Email (SMTP/IMAP), SMS |
| Enterprise | DingTalk, Feishu (Lark), WeCom |
| Other | BlueBubbles (iMessage bridge), Home Assistant |
Start on one platform, pick up on another — unified context across all gateways.
---
## Terminal Backends (6)
| Backend | Best for |
|---|---|
| **Local** | Development, testing |
| **Docker** | Isolated container execution with namespace hardening |
| **SSH** | Remote server execution |
| **Daytona** | Serverless — hibernates when idle, near-zero cost |
| **Singularity** | HPC / research clusters |
| **Modal** | Serverless GPU workloads |
Recommended production pattern: **Daytona or Modal backend + Telegram gateway**. Agent runs in the cloud; you talk to it from your phone.
---
## Voice / TTS / STT
Five TTS providers, selectable via `hermes tools`:
| Provider | Cost | Notes |
|---|---|---|
| **Edge TTS** | Free | Microsoft-backed, good quality, zero cost |
| **ElevenLabs** | Paid | Highest quality, voice cloning support |
| **OpenAI TTS** | Paid | Consistent, well-integrated |
| **MiniMax** | Paid | Strong multilingual support |
| **NeuTTS** | Paid | Alternative option |
STT uses model-native transcription capabilities or platform audio processing.
---
## Image Generation
Eight models via FAL.ai, configured with `hermes tools`:
| Model | Characteristic |
|---|---|
| FLUX 2 Klein | Fast, efficient |
| FLUX 2 Pro | High quality |
| GPT-Image 1.5 | OpenAI-aligned style |
| Nano Banana Pro | Speed-optimised |
| Ideogram V3 | Strong text-in-image |
| Recraft V4 Pro | Design-oriented output |
| Qwen | Multilingual context awareness |
| Z-Image Turbo | Ultra-fast generation |
---
## Web Search Backends
Configurable via `hermes tools`. The community `hermes-web-search-plus` plugin adds intelligent multi-provider routing:
| Provider | Notes |
|---|---|
| **Tavily** | Recommended default — purpose-built for LLM integration |
| **Serper** | Google results via API |
| **Exa** | Neural search — strong for research queries |
| **Brave Search** | Privacy-respecting, no personalisation bias |
| **SerpAPI** | Broad engine support |
---
## Advanced Integrations
### MCP (Model Context Protocol)
Connect any MCP server via stdio or HTTP transport. Per-server tool filtering and sampling support included. Hermes gains access to GitHub, databases, file systems, and internal APIs without writing native tools.
### API Server (OpenAI-compatible)
Expose Hermes as an OpenAI-compatible HTTP endpoint. Connect any frontend: Open WebUI, LobeChat, LibreChat, and others.
### IDE Integration (ACP)
Use Hermes inside ACP-compatible editors: VS Code, Zed, JetBrains. Chat, tool activity, file diffs, and terminal commands render natively inside the editor.
### RL Training (Research)
Trajectory data generation in ShareGPT format. Integrated with [Atropos](https://github.com/NousResearch/tinker-atropos) for RL and model fine-tuning. Batch processing runs the agent across thousands of prompts in parallel.
### Provider Resilience
- **Fallback providers** — Automatic failover on error, including independent fallback for vision and compression.
- **Credential pools** — Rotate across multiple API keys per provider; automatic rotation on rate limit or failure.
- **Provider routing** — Cost/speed/quality sorting, whitelists, blacklists, priority ordering.
---
## Customisation
### Personality (SOUL.md)
`SOUL.md` is the first content in the system prompt — defines Hermes's default voice. Swap presets per session with `/personality`, or place a custom `SOUL.md` in any project directory.
### Plugins
Three types, managed via `hermes plugins`:
- **General plugins** — Custom tools and lifecycle hooks.
- **Memory providers** — Alternative cross-session knowledge backends.
- **Context engines** — Alternative context management strategies.
### Event Hooks
- **Gateway hooks** — Logging, alerts, webhooks on message events.
- **Plugin hooks** — Tool interception, metrics, guardrails.
### Skins / Themes
CLI visual customisation: banner colors, spinner animations, response-box labels, branding text.
---
## Tips and Productivity Patterns
| Pattern | How |
|---|---|
| Resume last session | `hermes -c` |
| Resume by name | `hermes -r "my research project"` |
| Interrupt and redirect mid-response | `Ctrl+C` once |
| Force exit | `Ctrl+C` twice within 2 seconds |
| Paste clipboard image | `Ctrl+V` in CLI — agent uses vision directly |
| Tab-complete slash commands | `/` then `Tab` |
| Inject file into message | `@path/to/file` |
| Persist project instructions | `AGENTS.md` in project root — auto-loaded every session |
---
## Ecosystem: Notable Community Projects
### GUIs and Dashboards
| Project | Stars | Description |
|---|---|---|
| [hermes-workspace](https://github.com/outsourc-e/hermes-workspace) | 500+ | Native web workspace: chat, terminal, memory browser, skills manager |
| [mission-control](https://github.com/outsourc-e/mission-control) | 3.7k+ | Agent orchestration dashboard: fleet management, task dispatch, cost tracking |
| [hermes-webui](https://github.com/sanchomuzax/hermes-webui) | — | Lightweight process monitoring and config dashboard |
| [hermes-neurovision](https://github.com/Tranquil-Flow/hermes-neurovision) | — | Terminal neurovisualizer with 42 animated themes |
### Skills Libraries
| Project | Stars | Description |
|---|---|---|
| [wondelai/skills](https://github.com/wondelai/skills) | 380+ | Cross-platform skills (Hermes, Claude Code, agentskills.io-compatible) |
| [Anthropic-Cybersecurity-Skills](https://github.com/mukul975/Anthropic-Cybersecurity-Skills) | 3.6k+ | 734+ cybersecurity skills mapped to MITRE ATT&CK |
| [chainlink-agent-skills](https://github.com/smartcontractkit/chainlink-agent-skills) | — | Chainlink blockchain oracle skills on agentskills.io spec |
| [black-forest-labs/skills](https://github.com/black-forest-labs/skills) | — | FLUX image generation skills — by the FLUX authors |
| [hermes-agent-skills](https://github.com/zenc-cp/hermes-agent-skills) | — | 28 general-purpose skills |
| [cognify-skills](https://github.com/Yarmoluk/cognify-skills) | — | 19 business operations skills: CRM, invoicing, project management |
| [traction-skills](https://github.com/farosud/traction-skills) | — | 19 growth channel playbooks as agent skills |
| [hermes-incident-commander](https://github.com/Lethe044/hermes-incident-commander) | — | Autonomous SRE agent for production incident detection and healing |
| [hermes-life-os](https://github.com/Lethe044/hermes-life-os) | — | Personal OS agent: detects patterns, learns routines |
### Plugins
| Project | Description |
|---|---|
| [hermes-plugins](https://github.com/42-evey/hermes-plugins) | Goal management, inter-agent bridge, model selection, cost control |
| [hermes-web-search-plus](https://github.com/robbyczgw-cla/hermes-web-search-plus) | Multi-provider search routing: Serper, Tavily, Exa, and more |
| [hermes-weather-plugin](https://github.com/FahrenheitResearch/hermes-weather-plugin) | NWS-grade model imagery, NEXRAD radar, meteorological calculations |
| [hermes-cloudflare](https://github.com/raulvidis/hermes-cloudflare) | Headless browsing via Cloudflare infrastructure |
| [hermes-plugin-chrome-profiles](https://github.com/anpicasso/hermes-plugin-chrome-profiles) | Switch browser tools between Chrome profiles via CDP |
| [hermes-payguard](https://github.com/nativ3ai/hermes-payguard) | USDC and x402 payment integration |
| [evey-bridge-plugin](https://github.com/42-evey/evey-bridge-plugin) | Claude Code + Hermes side-by-side with shared context |
### Multi-Agent and Orchestration
| Project | Description |
|---|---|
| [hermes-agent-acp-skill](https://github.com/Rainhoole/hermes-agent-acp-skill) | Multi-agent delegation bridging Hermes, Codex, and Claude Code |
| [opencode-hermes-multiagent](https://github.com/1ilkhamov/opencode-hermes-multiagent) | 17 specialised agents with defined communication interfaces |
| [Ankh.md](https://github.com/Abruptive/Ankh.md) | TAW Agent × Hermes multi-agent swarm framework |
| [zouroboros-swarm-executors](https://github.com/marlandoj/zouroboros-swarm-executors) | Local executor bridge for Claude Code + Hermes handoff |
| [hermes-council](https://github.com/Ridwannurudeen/hermes-council) | Adversarial multi-perspective MCP council — structured debate before committing |
### Deployment
| Project | Description |
|---|---|
| [hermes-agent-docker](https://github.com/xmbshwll/hermes-agent-docker) | Minimal Docker sandbox image |
| [portainer-stack-hermes](https://github.com/ellickjohnson/portainer-stack-hermes) | Docker Compose + Portainer + browser-accessible ttyd terminal |
| [hermes-autonomous-server](https://github.com/JackTheGit/hermes-autonomous-server) | systemd + cron headless Linux server deployment |
| [nix-hermes-agent](https://github.com/0xrsydn/nix-hermes-agent) | Nix package and NixOS module for reproducible deployments |
| [hermes-alpha](https://github.com/kaminocorp/hermes-alpha) | Cloud-deployed Hermes with pre-configured infrastructure templates |
| [evey-setup](https://github.com/42-evey/evey-setup) | Opinionated quickstart: free models + 29 plugins, running in minutes |
### Domain Applications
| Project | Domain |
|---|---|
| [hermes-embodied](https://github.com/bryercowan/hermes-embodied) | Robotics — self-improving via VLA model fine-tuning |
| [hermescraft](https://github.com/bigph00t/hermescraft) | Minecraft — embodied AI companion with persistent memory |
| [hermes-legal](https://github.com/Lethe044/hermes-legal) | Contract risk analysis (English + Turkish) |
| [hermes-startup-architect](https://github.com/dlkakbs/hermes-startup-architect) | Startup to investor-ready kit: market analysis, pitch deck, financials |
| [hermes-ai-infrastructure-monitoring-toolkit](https://github.com/JackTheGit/hermes-ai-infrastructure-monitoring-toolkit) | Infrastructure monitoring, cost forecasting, headless DevOps |
| [hermes-research-agent](https://github.com/Aum08Desai/hermes-research-agent) | Autonomous end-to-end LLM research loops |
| [job-scout-agent](https://github.com/Christabel337/job-scout-agent) | Autonomous job hunting and application tracking |
| [mercury](https://github.com/hxsteric/mercury) | Multi-chain blockchain cash flow analysis with WebGL dashboard |
### Migration
| Project | Description |
|---|---|
| [openclaw-to-hermes](https://github.com/0xNyk/openclaw-to-hermes) | Full migration from OpenClaw: settings, memories, skills, API keys, messaging configs |
---
## Key Links
| Resource | URL |
|---|---|
| GitHub | https://github.com/NousResearch/hermes-agent |
| Official Docs | https://hermes-agent.nousresearch.com/docs/ |
| Skills Hub | https://agentskills.io |
| Community Discord | https://discord.gg/NousResearch |
| Awesome List | https://github.com/0xNyk/awesome-hermes-agent |
| OpenRouter | https://openrouter.ai |
| Nous Portal | https://portal.nousresearch.com |
| Ollama Integration | https://docs.ollama.com/integrations/hermes |
---
*Last verified: April 2026. The ecosystem moves fast — treat star counts and feature lists as approximate. Always check the official docs and repo for the current state.*