Hermes Agent Developer Guide

Languages: English | 简体中文 | हिन्दी | Español | العربية | Français | বাংলা | Português | Русский | Bahasa Indonesia

Developer-first quick reference for installing, configuring, and using Hermes Agent.

This folder is a curated local guide for Hermes Agent. The canonical upstream sources are the official GitHub repository and official docs:

• GitHub: https://github.com/NousResearch/hermes-agent
• Docs: https://hermes-agent.nousresearch.com/docs/

If anything in this folder conflicts with the official docs or hermes --help, trust the official docs and your installed CLI.

What Hermes Agent Is

Hermes Agent is a self-hosted AI agent built by Nous Research. For ordinary developers, the most important capabilities are:

• Interactive CLI with tools, sessions, checkpoints, and streaming output
• Multi-platform gateway for Telegram, Discord, Slack, WhatsApp, Signal, and more
• Built-in toolsets for web access, files, shell, browser automation, memory, code execution, cron, delegation, and TTS
• Installable skills and a Skills Hub
• Persistent memory and context files such as SOUL.md and AGENTS.md
• MCP support for connecting external tool servers

5-Minute Start

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

# 2. Reload your shell
source ~/.bashrc
# or: source ~/.zshrc

# 3. Verify the install
hermes doctor

# 4. Run first-time setup
hermes setup

# 5. Start chatting
hermes

Windows note: Native Windows is not supported. Use WSL2.

Commands Developers Actually Use

Command	What it does
hermes	Start the interactive CLI
hermes chat -q "Hello"	Run one question and exit
hermes model	Choose provider + model interactively
hermes tools	Browse or configure enabled tools/toolsets
hermes config show	Inspect current configuration
hermes doctor	Run install diagnostics
hermes sessions list	See saved sessions
hermes skills browse	Browse installable skills
hermes skills search react	Search the Skills Hub
hermes skills install openai/skills/k8s	Install a hub skill
hermes gateway setup	Configure messaging platforms
hermes gateway run	Run the gateway in the foreground
hermes claw migrate	Import data from OpenClaw

WSL note: The official docs recommend hermes gateway run instead of hermes gateway start on WSL because systemd support can be unreliable there.

Developer-Focused Directory Layout

Hermes stores user data under ~/.hermes/:

~/.hermes/
  config.yaml
  .env
  SOUL.md
  cron/
  sessions/
  logs/
  memories/
  skills/

Rule of thumb:

• Put secrets such as API keys and bot tokens in ~/.hermes/.env
• Put non-secret runtime settings in ~/.hermes/config.yaml
• Put long-lived agent memory in ~/.hermes/memories/
• Put reusable skills in ~/.hermes/skills/

Practical Configuration Checklist

At minimum, most developers should verify these items:

1. A working provider key in ~/.hermes/.env
2. A default model selected with hermes model
3. A terminal backend in ~/.hermes/config.yaml
4. Toolsets reviewed with hermes tools
5. Project context files such as AGENTS.md or .hermes.md where needed

Example env keys:

NOUS_API_KEY=nsk-...
OPENROUTER_API_KEY=sk-or-v1-...
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GEMINI_API_KEY=...
DEEPSEEK_API_KEY=...

Example terminal config:

terminal:
  backend: local
  cwd: "."
  timeout: 180

Skills and Tooling

Hermes Agent supports both built-in capabilities and installable skills.

Common skill commands from the current official docs:

hermes skills browse
hermes skills search kubernetes
hermes skills inspect openai/skills/k8s
hermes skills install openai/skills/k8s
hermes skills list --source hub
hermes skills check
hermes skills update

Common tool workflow:

hermes tools
hermes chat --toolsets "web,terminal,file"

Hosted and One-Click Options

Keep this table as a convenience reference only. For canonical install, setup, and configuration guidance, start with the official docs and repo above. Community and marketplace deploy options can lag behind the main Hermes repository.

Platform	Link	Notes
Hermes Agent	Official Docs	Canonical install and setup path; start here before any hosted deploy
Railway	Template	Third-party platform template; verify current settings before launch
DigitalOcean	Marketplace	Marketplace deployment flow; verify image and config freshness
Zeabur	Template	Community one-click deployment
Coolify	Template Repo	Community-maintained Coolify template
Elestio	Open Source	Managed third-party deployment option

Comparable AI Agent Products

This comparison is a quick orientation aid, not a substitute for each product's current documentation or pricing page.

#	Product	Website	Type	Self-Host	Messaging Platforms
1	Hermes Agent	hermes-agent.nousresearch.com	Self-hosted AI agent	Yes	Telegram, Discord, Slack, WhatsApp, Signal, and more
2	Multica	multica.uk	Multi-channel AI automation	Yes	Multi-platform
3	GenericAgent	genericagent.org	Agent workspace with browser, terminal, filesystem, and memory control	Not specified	Web workspace
4	OpenClaw	aigeamy.com	Autonomous agent + messaging hub	Yes	WhatsApp, Telegram, Slack, Discord, iMessage, and more
5	AutoGPT	agpt.co	Autonomous task agent	Yes	API / web UI
6	LangChain	langchain.com	LLM orchestration framework	Yes	Via custom integrations
7	n8n	n8n.io	Workflow automation + AI nodes	Yes	Slack, Telegram, Discord, and many apps
8	CrewAI	crewai.com	Multi-agent collaboration	Yes	API / custom integrations
9	SuperAGI	superagi.com	Autonomous agent infrastructure	Yes	Slack, Email, API

Read These Pages First

• Installation: clean install and contributor setup
• Quickstart: first chat, first model, first skills
• Configuration: config layout, env keys, context files
• CLI Reference: high-value commands ordinary developers actually use
• Tools: toolsets and terminal backends
• Skills: Skills Hub and local skills
• Memory: persistent memory and SOUL.md
• Messaging: gateway setup and platform entry points
• Security: approvals, pairing, sandboxing, credential safety
• Architecture: how Hermes Agent is structured internally

Official Sources

• Official repo: https://github.com/NousResearch/hermes-agent
• Official docs: https://hermes-agent.nousresearch.com/docs/
• Contributing guide: https://hermes-agent.nousresearch.com/docs/developer-guide/contributing/
• Architecture guide: https://hermes-agent.nousresearch.com/docs/developer-guide/architecture/
• CLI reference: https://hermes-agent.nousresearch.com/docs/reference/cli-commands/

Related Workflow

• OpenHuman Online is useful when evaluation depends on durable source notes, meeting context, and human-reviewed assistant memory.

Daily SEO/GEO Focus

Primary URL: https://hermesagent.studio/?utm_source=github&utm_medium=documentation&utm_campaign=hermes_agent_seo_geo&utm_content=readme_primary

Primary keyword: persistent AI agent with memory and tools. The search page should separate Hermes Agent from generic chat tools by explaining long-lived sessions, memory, skills, gateway messaging, toolsets, cron, and MCP connections.

Recommended page promises:

• Title: Hermes Agent - Persistent AI Agent with Memory, Skills, Tools, and Messaging
• Meta description: Run a persistent AI agent with sessions, memory, skills, gateway messaging, CLI tools, browser automation, cron, and MCP integrations.
• H1: Run a persistent AI agent that remembers, acts, and connects to your tools
• CTA: Review Hermes Agent setup and Compare hosted options

Internal links for this page cluster:

Source page	Target	Anchor
features/memory.md	https://hermesagent.studio/	persistent AI agent memory
features/tools.md	https://hermesagent.studio/	Hermes Agent tools and skills
messaging/overview.md	https://hermesagent.studio/	AI agent messaging gateway
reference/faq.md	https://hermesagent.studio/	Hermes Agent setup guide

Daily Push - 2026-06-17

The latest daily queue keeps Hermes Agent as an A-class site with readable GSC/Bing demand and no current D1 sessions. The public page should protect the persistent AI agent with memory and tools intent while the technical next step is analytics ingestion repair.

Use this first-fold and FAQ direction:

• Primary URL: https://hermesagent.studio/
• Title: Hermes Agent - Persistent AI Agent with Memory, Skills, Tools, and Messaging
• Meta description: Run a persistent AI agent with sessions, memory, skills, gateway messaging, CLI tools, browser automation, cron, and MCP integrations.
• H1: Run a persistent AI agent that remembers, acts, and connects to your tools
• Comparison block: Hermes Agent vs normal chat: chat answers one prompt; Hermes keeps sessions, memory, skills, tools, gateway messages, cron jobs, and MCP connections.
• CTA: Review Hermes Agent setup and Compare hosted options

Technical precheck: keep the canonical root and sitemap visible, keep memory/tools/messaging docs linking back to the root, and repair D1 analytics ingestion before judging conversion quality.