Overview

Learn the Hermes Agent AI platform by doing. This by-example tutorial teaches Hermes Agent — the open-source, self-improving AI agent by Nous Research — through 80 heavily annotated, self-contained examples achieving 95% coverage. Master CLI usage, YAML configuration, persistent memory, skill authoring, messaging gateway integration, subagent delegation, security hardening, and production deployment patterns.

What is By Example?

By Example is a code-first learning approach designed for experienced developers who want to master Hermes Agent efficiently. Instead of lengthy explanations followed by examples, you'll see complete, runnable configurations and commands with inline annotations explaining what each element does and why it matters.

Target audience: Developers and DevOps engineers with command-line experience who want to deploy and orchestrate self-improving AI agents using Hermes Agent.

What is Hermes Agent?

Hermes Agent is a free, open-source, self-improving AI agent built by Nous Research. It connects large language models (Claude, GPT, Gemini, DeepSeek, Llama, and 200+ models via OpenRouter) to messaging platforms (Telegram, Discord, Slack, WhatsApp, Signal, and more) and enables AI to take real actions — shell commands, file management, browser automation, web scraping, scheduling, delegation, and more.

Key differentiator: Hermes Agent has a built-in learning loop — it creates skills from experience, improves them during use, persists knowledge across sessions, and builds a deepening model of who you are.

Key architectural components:

• CLI: Python-based terminal UI (hermes) with multiline editing, autocomplete, streaming, and token/cost tracking
• Gateway: Multi-platform messaging server connecting Telegram, Discord, Slack, WhatsApp, Signal, Email, and more
• Tools: 70+ built-in capabilities organized into pluggable toolsets (terminal, file, browser, web, vision, delegation, memory, cron, and more)
• Memory: Persistent MEMORY.md and USER.md files injected into every session, with FTS5 session search
• Skills: Self-improving procedural memory (SKILL.md format) — agent autonomously creates and refines skills after complex tasks
• Delegation: Spawn isolated subagents for parallel workstreams (up to 3 concurrent, depth limit 2)
• Terminal Backends: 6 execution environments — local, Docker, SSH, Modal, Daytona, Singularity

How This Tutorial Works

Structure

• Beginner (Examples 1-27): Installation, CLI commands, YAML configuration, basic tools, memory fundamentals — 0-40% coverage
• Intermediate (Examples 28-54): Skills system, messaging channels, delegation, scheduling, browser automation, code execution — 40-75% coverage
• Advanced (Examples 55-80 plus four deep-dive hardening patterns): Terminal backends, security hardening (OWASP LLM Top 10 threat model, indirect prompt-injection defense, MCP supply-chain vetting, link-preview exfiltration prevention, network egress isolation), MCP integration, voice mode, production deployment, scaling — 75-95% coverage

Example Format

Each example follows a five-part structure:

1. Brief explanation (2-3 sentences) — What is this pattern and why does it matter?
2. Diagram (when appropriate) — Visual representation of architecture or data flow
3. Heavily annotated configuration/commands — Complete, runnable examples with inline # => annotations
4. Key takeaway (1-2 sentences) — The essential insight distilled
5. Why it matters (50-100 words) — Production relevance and real-world impact

Example: Annotation Style

# ~/.hermes/config.yaml — Main configuration file
model:
  provider:
    "anthropic" # => LLM provider selection
    # => Options: anthropic, openrouter, nous, copilot, custom
  model:
    "claude-sonnet-4-6" # => Model identifier within provider
    # => Format varies by provider

What You'll Learn

Coverage: 95% of Hermes Agent for Production Work

Included:

• Core CLI commands (hermes, hermes model, hermes tools, hermes setup, hermes doctor)
• YAML configuration (model, terminal, memory, compression, security, TTS)
• Built-in tools (terminal, read_file, write_file, patch, search_files, web_search, web_extract, browser, vision, delegation)
• Memory system (MEMORY.md, USER.md, session_search, external providers)
• Skill authoring (SKILL.md format, progressive disclosure, autonomous creation, Skills Hub)
• Messaging gateway (Telegram, Discord, Slack, WhatsApp, Signal, Email)
• Delegation and subagents (delegate_task, batch parallelism)
• Scheduling (cronjob tool, natural language, multi-platform delivery)
• Terminal backends (local, Docker, SSH, Modal, Daytona, Singularity)
• Security (approvals, secret redaction, Tirith scanning, checkpoints)
• MCP server integration
• Voice mode (TTS, STT, push-to-talk)
• Production deployment (daemon management, monitoring, scaling)

Excluded (the 5% edge cases):

• Atropos RL training environment internals
• Third-party memory provider plugin development
• ACP IDE integration protocol details
• Internal AIAgent class Python API
• WhatsApp Baileys protocol implementation

Prerequisites

• Required: Command-line proficiency (terminal, shell basics)
• Required: Git installed (only system prerequisite — installer handles everything else)
• Required: Basic understanding of YAML syntax
• Helpful: Familiarity with at least one LLM API (Anthropic, OpenAI, etc.)
• Helpful: Experience with messaging platform bots (Telegram, Slack, Discord)
• Not required: Prior Hermes Agent or OpenClaw experience — this tutorial starts from zero

Learning Path Comparison

Installation Quick Start

# Install Hermes Agent (Linux/macOS/WSL2/Termux)
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
                                        # => Only prerequisite: Git
                                        # => Auto-installs: Python 3.11, Node.js v22,
                                        # =>   uv, ripgrep, ffmpeg
 
# Reload shell
source ~/.bashrc                        # => Makes `hermes` command available
 
# Run first-time setup
hermes setup                            # => Interactive wizard
                                        # => Configures model provider and API key
                                        # => Creates ~/.hermes/ directory structure
 
# Verify installation
hermes doctor                           # => Checks system requirements
                                        # => Validates config, connectivity

Migrating from OpenClaw

If you're currently using OpenClaw, Hermes Agent provides a built-in migration tool:

hermes claw migrate --dry-run           # => Preview what will be migrated
hermes claw migrate --preset full       # => Full migration including API keys
                                        # => Converts JSON5 config to YAML
                                        # => Imports memory, skills, sessions

See Example 27 for the complete migration guide.

Next Steps

Start with Beginner Examples (1-27) to learn CLI fundamentals and YAML configuration.

Examples by Level

Beginner (Examples 1–27)

• Example 1: Installing Hermes Agent
• Example 2: First-Time Setup Wizard
• Example 3: Starting an Interactive Session
• Example 4: One-Shot Messages
• Example 5: Reasoning Effort Levels
• Example 6: Doctor and Diagnostics
• Example 7: Configuration File Structure
• Example 8: Model Provider Configuration
• Example 9: API Key Management
• Example 10: Display and Output Settings
• Example 11: Agent Behavior Configuration
• Example 12: Human Delay Settings
• Example 13: Quick Commands
• Example 14: Terminal Tool
• Example 15: File Operations (read_file, write_file, patch)
• Example 16: Web Search and Extraction
• Example 17: Process Management
• Example 18: Todo Management
• Example 19: Vision and Image Analysis
• Example 20: Toolset Management
• Example 21: MEMORY.md -- Agent's Persistent Notes
• Example 22: USER.md -- User Profile
• Example 23: Memory Operations
• Example 24: Context Files (.hermes.md)
• Example 25: Agent Identity (SOUL.md)
• Example 26: Slash Commands Reference
• Example 27: Migrating from OpenClaw

Intermediate (Examples 28–54)

• Example 28: Skills System Overview
• Example 29: Viewing Skills
• Example 30: SKILL.md Format
• Example 31: Creating Skills Manually
• Example 32: Autonomous Skill Creation
• Example 33: Skill Conditional Activation
• Example 34: Skills Hub Integration
• Example 35: Gateway Architecture
• Example 36: Telegram Channel Setup
• Example 37: Discord Channel Setup
• Example 38: Slack Channel Setup
• Example 39: WhatsApp Channel Setup
• Example 40: Signal and Email Channels
• Example 41: Multi-Platform Message Delivery
• Example 42: DM Policies and Access Control
• Example 43: Subagent Delegation
• Example 44: Batch Delegation
• Example 45: Delegation Model Override
• Example 46: Cron Job Creation
• Example 47: Cron with Multi-Platform Delivery
• Example 48: Session Search
• Example 49: Browser Navigation
• Example 50: Browser Interaction
• Example 51: Browser Vision and Screenshots
• Example 52: Code Execution Tool
• Example 53: Clarify Tool
• Example 54: Mixture of Agents

Advanced (Examples 55–80)

• Example 55: Docker Terminal Backend
• Example 56: SSH Terminal Backend
• Example 57: Modal Serverless Backend
• Example 58: Daytona Managed Backend
• Example 59: Singularity HPC Backend
• Example 60: Terminal Environment Passthrough
• Example 61: Approval Modes
• Example 62: Secret Redaction
• Example 63: Tirith Security Scanning
• Example 64: Website Blocklist
• Example 65: Checkpoint and Rollback
• Example 66: File Read Limits
• Example 67: Privacy Controls
• Example 67.1: Indirect Prompt Injection Defense (Tool Output Isolation)
• Example 67.2: Supply Chain — Vetting MCP Servers and Skills
• Example 67.3: Link-Preview Exfiltration Prevention
• Example 67.4: Network Egress Isolation for the Hermes Gateway
• Example 68: MCP Server Configuration
• Example 69: MCP Tool Filtering
• Example 70: Hermes as MCP Server
• Example 71: Voice Mode Setup
• Example 72: Text-to-Speech Configuration
• Example 73: Personality System
• Example 74: Daemon Installation
• Example 75: Gateway Authentication
• Example 76: Context Compression
• Example 77: Smart Model Routing
• Example 78: Profiles for Isolation
• Example 79: Webhook Subscriptions
• Example 80: Monitoring and Cost Tracking