Hermes Agent

"Hermes is the world's most powerful AI agent assistant. But if you combine it with Claude Code, you can create a powerful 24/7 AI employee." — Jack Roberts (Source: Hermes Agent just got 10X Better, YouTube, 2026-05-15)

Hermes Agent is an open-source AI assistant by Nous Research — a self-hosted agent that runs on your machine or VPS, connects to messaging platforms like Telegram, remembers across conversations, learns from completed tasks, and runs scheduled work autonomously. It ships with 118 bundled skills, supports 200+ AI models, and is licensed under MIT.

This guide covers the practical operations layer: what Hermes can do, how to set it up, and the patterns that turn it from a chatbot into a 24/7 AI teammate.

What Hermes Agent Does

Hermes is not a chatbot. It's an agent with three architectural capabilities that compound over time:

These three systems interact: a cron job uses skills you've built, applying memory of your preferences to produce output tailored to you. The more you use it, the more tuned it becomes — without manual configuration.

"Skills are self-improving workflows that get 40% faster with use." — Parker Prompts (Source: The Only Hermes Agent Tutorial You'll Need in 2026, YouTube, 2026-05-27)

Quick Setup Walkthrough

Source: NxCode tutorial (2026-04-12) — the simplest linear setup guide available. For desktop GUI users, see Hermes Desktop Setup — Decision Guide.

This is the "just get it running" path. Six steps, each with explicit commands. You'll have a working agent in under 30 minutes.

Step 1: Install

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

That single command detects your OS, installs dependencies (Python 3.11+, Node.js, ripgrep, ffmpeg), clones the repo to ~/.hermes, creates a venv, registers the hermes command globally, and launches the setup wizard. Under 5 minutes on a typical connection.

After install, reload your shell and verify:

source ~/.bashrc      # or source ~/.zshrc on macOS
hermes --version       # Expected: hermes-agent v0.8.0

If anything goes wrong: hermes doctor — it checks your environment, dependencies, API connectivity, and config.

Windows note: Hermes runs on Windows via git-bash/MSYS or WSL2. Native Windows terminal is not supported.

Step 2: Choose Your AI Model

Run hermes model to pick or change your LLM provider. Three main paths:

Ollama local setup (the zero-cost path):

# Install Ollama if you haven't
curl -fsSL https://ollama.com/install.sh | sh

# Pull a model with sufficient context
ollama pull gemma4        # ~16 GB VRAM
# or
ollama pull qwen3.5       # ~11 GB VRAM

# Run with 64K context (REQUIRED)
ollama run gemma4 --ctx-size 65536

In Hermes setup: select "Custom endpoint" → set base URL to http://127.0.0.1:11434/v1 → leave API key blank.

Provider fallback chains: If your primary provider goes down, Hermes auto-switches. Configure in ~/.hermes/config.yaml:

fallback_providers:
  - provider: openrouter
    model: anthropic/claude-sonnet
  - provider: ollama
    model: gemma4

Critical: Hermes requires a model with at least 64,000 tokens of context. Models below this threshold are rejected at startup — multi-step tool workflows need the headroom.

Step 3: Your First Conversation

Start Hermes:

hermes

You're in an interactive chat session. Try something simple:

> What's in my current directory? List files and tell me what this project does.

Hermes uses 40+ built-in tools — file operations, terminal commands, web search, code analysis — to explore and respond.

Essential CLI commands during a session:

/compress is especially important for long sessions — it summarizes conversation history and reduces token usage significantly while preserving context.

Step 4: Set Up a Telegram or Discord Bot

This is where Hermes becomes more than a CLI tool. The gateway lets you interact through messaging platforms from a single background process.

Telegram:

1. Open Telegram → search @BotFather → /newbot → pick a name → copy the token
2. Run hermes gateway setup → select Telegram → paste your token
3. Restrict access: get your user ID from @userinfobot, set TELEGRAM_ALLOWED_USERS=123456789
4. Start the gateway: hermes gateway
5. Install as a persistent service: hermes gateway install (systemd on Linux, launchd on macOS)

Discord:

1. Go to Discord Developer Portal → create app → add bot → copy token
2. Invite the bot to your server
3. hermes gateway setup → select Discord → paste token

The gateway handles Telegram, Discord, Slack, WhatsApp, and Signal simultaneously. Once installed as a service, it auto-restarts on crash and starts at boot.

Step 5: Watch It Learn

This is Hermes' defining feature. After completing a complex task (5+ tool calls), the agent autonomously creates a skill — a structured markdown document capturing the workflow, pitfalls discovered, and verification steps. Skills follow the agentskills.io standard and are portable across agents.

Skills self-improve during use: if the agent discovers a better approach while executing a skill, it updates the skill document automatically.

hermes skills             # List all skills
hermes skills show <name> # View a specific skill

Beyond skills, Hermes maintains persistent memory — facts about you, your preferences, your projects. Session history, memory, and skill metadata are stored in SQLite with FTS5 full-text search for efficient cross-session recall.

hermes memory              # View current memory
hermes memory search "topic" # Search memory

Step 6: Automate with Cron

Hermes has a built-in cron scheduler. Create tasks in natural language:

hermes cron add

When prompted: "Every morning at 9am, check Hacker News for AI news and send me a summary on Telegram."

Or with a cron expression:

hermes cron add --schedule "0 9 * * *" \
  --prompt "Check HN for top 5 AI stories. Summarize each in 2 sentences. Send to Telegram." \
  --deliver telegram

Manage scheduled tasks:

hermes cron list           # Show all tasks
hermes cron remove <id>    # Delete a task
hermes cron logs <id>      # View execution history
hermes cron start          # Start the scheduler daemon

Practical cron ideas: daily GitHub issue summaries, weekly industry digests to Slack, hourly production health checks, morning calendar + task briefings.

Troubleshooting Quick Reference

Config File Layout (~/.hermes/)

Deployment: Where Hermes Lives

Hermes runs where you put it. Three deployment patterns, in order of permanence:

1. Local Machine (your laptop/desktop)

The fastest way to start. Hermes installs via a single command and runs directly on your computer. The gateway process runs in the background; your bot is online as long as your machine is awake.

Setup (Windows): hermes setup runs the full wizard — pick a provider (OpenRouter recommended for 200+ model access), configure Telegram via BotFather, start the gateway.

Key paths: Config at ~/AppData/Local/hermes/config.yaml, API keys at ~/.hermes/.env.

Limitation: Bot goes offline when your computer sleeps. Good for active-use sessions, not for scheduled cron jobs that must fire reliably.

2. VPS via Docker (Hostinger / any Linux server)

For 24/7 uptime. Hostinger offers a one-click Docker template that provisions Hermes in ~10 minutes. Traefik handles networking, Docker handles isolation.

Recommended spec: KVM2 plan (2 vCPU, 8 GB RAM). For Hermes + Claude Code MCP on the same VPS, 4 vCPU / 8 GB RAM minimum.

"The gateway is the single point of failure — verify it's running. If the gateway isn't active, messages go unanswered, cron jobs don't fire, and nothing happens in the background." — Parker Prompts

3. Docker on any infrastructure

Hermes is a standard Docker container. You can deploy it on Proxmox, a Synology NAS, AWS, or any Docker host. The container wraps the gateway, Telegram bot, and cron scheduler.

Core Systems in Detail

Skills

Skills are Hermes' knowledge units — reusable workflows encoded as markdown files with YAML frontmatter. Hermes ships with 118 bundled skills covering web search, code review, image generation, email, GitHub operations, and more.

How they work: When you ask Hermes to do something, it scans available skills for matching descriptions. If a skill applies, it loads the skill's instructions before acting. After completing a complex task, Hermes can save the successful workflow as a new skill — so it doesn't rediscover the process next time.

Skill lifecycle:

1. Bundled skills → loaded automatically when relevant
2. Custom skills → you describe what you want in plain language, Hermes creates the SKILL.md
3. Skill curator → a 7-day review cycle prunes unused skills and suggests improvements

Creating a skill (from Parker Prompts): Just tell Hermes in Telegram: "Save this process as a skill called 'morning briefing' that scrapes my calendar and top HN posts and formats them for Telegram." Hermes writes the skill, tests it, and registers it for future use.

Memory

Hermes builds a persistent profile of you across three files:

• user.md — Who you are: name, role, preferences, projects, communication style
• agents.md — How Hermes should behave: tone, constraints, default tools
• souls.md — Deeper identity: values, principles, "what matters"

Memory is updated continuously through conversation. When you tell Hermes "I prefer concise answers" or "my vault is at this path," it writes that to memory and applies it in every future session. You never re-explain yourself.

Memory is profile-scoped — different Hermes profiles (e.g., work vs personal) maintain separate memory stores.

Cron Jobs

Scheduled autonomous tasks that run without you. Created in plain language from Telegram:

"Every weekday at 7 AM, check my calendar, scrape HN top 5, and send me a briefing"

Hermes parses the schedule, creates the job, and fires it on time. Jobs can be listed, paused, edited, or removed — all via natural language in your Telegram chat.

Model tiering for cron: Assign cheap/free models to routine cron jobs and save expensive models for interactive sessions. Parker Prompts recommends OpenRouter's free models for daily briefings and Claude/Opus-tier models only for complex reasoning tasks.

Configuration: The Tunables

Hermes has deep configuration — far beyond the setup wizard. AI LABS identified four categories of settings that materially improve performance:

Context & Output Limits

Sub-Agents

Hermes can spawn child agents for parallel work. Key settings:

• max_concurrent_children (default 3) — bump to 5 if parallel tasks bottleneck
• max_spawn_depth (default 1) — increase for recursive delegation (child spawns grandchild)
• subagent_auto_approve — set to true for hands-off workflows

Cost Optimization: Auxiliary Models

Hermes uses your main model for everything by default — including trivial background tasks like web extraction, title generation, and context compression. Auxiliary models offload these to cheaper models:

• 9 auxiliary slots available for different task types
• Assign a cheap/free model (e.g., DeepSeek Chat, Gemini Flash) to background slots
• Main model only fires for actual reasoning

Quick command for provider portability: /fix-aux deepseek deepseek-chat repoints all auxiliary slots in one command — useful when switching providers.

Workflow Features

• Quick commands (exec/alias) — Replace repetitive terminal workflows with single slash commands. Example: /fix-aux repoints all auxiliary slots.
• Checkpointing + rollback — Config changes are versioned. If something misbehaves, roll back.
• Background process notifications — Long tasks notify you when they finish.
• YOLO mode (--yolo) — Bypasses all confirmation prompts for fully autonomous operation.
• Personalities — Custom system prompts with separate model assignments (see Pantheon below).

Integration Patterns

Telegram (Primary Interface)

After setup, you manage Hermes entirely through Telegram — no terminal needed. Creating cron jobs, saving skills, updating memory, checking schedules, pausing jobs — all via natural language messages.

Setup: BotFather → create bot → get token → paste into Hermes setup wizard → get your Telegram user ID from @userinfobot → authorize.

Safety: Only authorized user IDs can message your bot. Your token is local; Hermes never sends it anywhere.

Claude Code MCP Bridge

Connect Hermes (orchestration, memory, Telegram) to Claude Code (specialized coding) via MCP:

"Hermes Agent is really good because it has persistent memory across sessions, autonomous task execution, and Telegram integration. But Claude Code is really great at coding. So why don't we use Claude Code when we need to code inside of Hermes Agent?" — Prompt Engineer

The bridge pattern: Hermes reads the MCP server's documentation, self-configures the connection, and then delegates coding tasks to Claude Code from Telegram. You message Hermes on your phone; Hermes spawns Claude Code to do the work.

Cost profile (Prompt Engineer's setup): DeepSeek V4 Pro as Hermes' backbone LLM (~$0.17 for 6 hours of use), Claude Code only invoked for actual coding work.

Obsidian Vault Integration

Hermes can read and write your Obsidian vault, making it a bridge between your knowledge base and your AI workflows. Jack Roberts' setup connects Hermes' memory system to an Obsidian vault for shared context across all AI tools.

Practical pattern: Use Hermes for vault operations (video ingestion, note creation, frontmatter validation) and Claude Code for agentic coding — both reading from and writing to the same Obsidian vault.

Running Hermes with Local Models

Hermes connects to any OpenAI-compatible API endpoint — which means you can point it at a local model server (Ollama, LM Studio, llama.cpp) instead of a cloud provider. Your conversations, memory, and task data never leave your infrastructure.

How it works: Hermes is model-agnostic at the provider level. In config.yaml, you define a provider with a base_url pointing to your local endpoint:

provider: ollama
base_url: http://localhost:11434/v1
model: qwen3:14b

LM Studio exposes the same pattern at http://localhost:1234/v1. Any local server that speaks the OpenAI chat completions API works — no Hermes-specific adapter needed.

Ollama on VPS (the Hostinger pattern): Dr. Firas' guide demonstrates running Ollama inside a Docker container on a Hostinger VPS, then connecting Hermes to it. The stack:

1. Deploy Ollama via Docker on the VPS: docker run -d --gpus all ollama/ollama
2. Pull a model: docker exec ollama ollama pull qwen3:14b
3. Configure Hermes' provider to point at http://<vps-ip>:11434/v1
4. Hermes + Telegram gateway run in separate Docker containers on the same VPS

This gives you a 24/7 Hermes agent backed entirely by local models — no API keys, no per-token billing, no data leaving your server. The tradeoff is hardware cost: you need a VPS or dedicated machine with enough VRAM for your chosen model.

Model selection for Hermes: Local models for Hermes need the same capabilities as cloud models — tool calling (essential for agentic workflows) and preferably reasoning. See the Local AI Coding Workflow page for hardware sizing, quantization strategy, and model recommendations. The key difference for Hermes: because it spawns sub-agents for parallel work, you may need headroom to run multiple model instances simultaneously on the same GPU.

Practical starting point: Qwen 3 14B (Q4 quantization, ~9 GB VRAM) provides good tool-calling capability at a size that fits on mid-range GPUs. For lighter Hermes profiles (simple Telegram Q&A, basic cron jobs), even a 7B model is sufficient.

The Pantheon: Personas with Model Assignment

Jack Roberts introduced the Pantheon concept — custom AI personas that pair a system prompt, a personality, and a specific model:

The principle: model assignment by task type, not by default. "We don't need Albert Einstein to mop our floors."

Cost Management

Model Tiering Strategy

Per-Job Model Assignment

Assign cheaper models to cron jobs and background tasks individually — you don't need to switch the main model globally. Parker Prompts demonstrates: /model deepseek-chat for a morning briefing cron job while keeping Claude Opus as the main interactive model.

Getting Started: Minimum Viable Setup

For the full step-by-step walkthrough with commands, see #Quick Setup Walkthrough above.

1. Install: One command — hermes setup (or Hostinger one-click Docker template for 24/7)
2. Pick a provider: OpenRouter gives access to 200+ models including free tier options
3. Connect Telegram: Create a bot via BotFather, paste the token, authorize your user ID
4. Start the gateway: hermes gateway — this is the single point of failure; confirm it's running
5. First conversation: Message your bot on Telegram — Hermes is now online
6. Create your first cron job: "Every morning at 8 AM, tell me my calendar for today"

From zero to working assistant in ~10 minutes (Docker) to ~20 minutes (local install with provider setup).

Caveats and Open Questions

• Gateway reliability: The gateway process is the single point of failure. If it stops, your bot goes silent and cron jobs don't fire. Run it as a service/daemon, not manually.
• Cost accumulates: Even with free models for background tasks, OpenRouter API costs add up with heavy use. Monitor your usage dashboard.
• Skill sprawl: With 118 bundled skills plus self-created ones, skill relevance matching can become noisy. The 7-day curator review helps but requires attention.
• Config complexity: The config.yaml has dozens of tunables. Start with defaults; tune only when a bottleneck surfaces (AI LABS' recommended approach).
• Open source dependency: Hermes Agent evolves rapidly. Skills and workflows that work today may need updating as the project changes.

See Also

• Hermes Desktop Setup — Decision Guide — Step-by-step decision guide for desktop app setup
• Local AI Coding Workflow — Run AI models on your own hardware alongside Hermes
• Claude Code — The coding specialist that Hermes delegates to via MCP
• The Agentic Loop — The conceptual foundation: goal-driven agent loops
• Master-Agent-Comparison-Matrix — How Hermes compares to other agentic tools
• Open-Source-AI-Model-Comparison — Model selection guide (which models to use with Hermes)
• Obsidian — Local-first knowledge management that Hermes can read and write
• NxCode — Hermes Agent Tutorial Install Setup First Agent 2026 — Source analysis for the Quick Setup Walkthrough above