hermes-agent Documentation

Technical Documentation: NousResearch/hermes-agent

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (README.md) Copy Section

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 — Nous Portal, OpenRouter, OpenAI, your own endpoint, and many others. Switch with hermes model — no code changes, no lock-in.

Quick Install Copy Chapter

Linux, macOS, WSL2 Copy Section

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

Windows (native, PowerShell) Copy Section

Heads up: Native Windows runs Hermes without WSL — CLI, gateway, TUI, and tools all work natively. If you'd rather use WSL2, the Linux/macOS one-liner above works there too. Found a bug? Please file issues.

Run this in PowerShell:

iex (irm https://hermes-agent.nousresearch.com/install.ps1)

The source installer delegates Python 3.14, Node.js, npm, ripgrep, FFmpeg,
and Python dependencies to PM. If Git is absent, it stages the verified Git
for Windows archive in Hermes' tool store. It does not replace your system Git.
See installation methods
for the separate MSIX/App Installer package and its update ownership.

Android / Termux: A signed APT repository is available for aarch64 devices, with a stable channel (tagged releases) and a prerelease canary channel. The package includes Python, Node.js, and the TUI. Use the Termux guide, not the desktop/server installer script.

Windows: Native Windows is fully supported — the PowerShell one-liner above installs everything. If you'd rather use WSL2, the Linux command works there too. Native Windows install lives under %LOCALAPPDATA%\hermes; WSL2 installs under ~/.hermes as on Linux.

After installation:

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

Troubleshooting Copy Section

Windows Defender or antivirus flags `uv.exe` as malware

If your antivirus (Bitdefender, Windows Defender, etc.) quarantines uv.exe from the Hermes bin folder (%LOCALAPPDATA%\hermes\bin\uv.exe), this is a false positive. The file is Astral's uv — the Rust Python package manager Hermes bundles to manage its Python environment. ML-based antivirus engines commonly flag unsigned Rust binaries that download and install packages.

To verify your copy is authentic:

# Install GitHub CLI if needed
winget install --id GitHub.cli

# Login to GitHub
gh auth login

# Run verification
$uv = "$env:LOCALAPPDATA\hermes\bin\uv.exe"
$ver = (& $uv --version).Split(' ')[1]
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
$zip = "$env:TEMP\uv.zip"
Invoke-WebRequest "https://github.com/astral-sh/uv/releases/download/$ver/uv-x86_64-pc-windows-msvc.zip" -OutFile $zip -UseBasicParsing
gh attestation verify $zip --repo astral-sh/uv
Expand-Archive $zip "$env:TEMP\uv_x" -Force
(Get-FileHash "$env:TEMP\uv_x\uv.exe").Hash -eq (Get-FileHash $uv).Hash

If attestation says "Verification succeeded" and the last line prints True, you're good.

To whitelist Hermes:

• Windows Defender: Run PowerShell as Admin → Add-MpPreference -ExclusionPath "$env:LOCALAPPDATA\hermes\bin"
• Bitdefender: Add an exception in the Bitdefender console (Protection > Antivirus > Settings > Manage Exceptions)
• Whitelist the folder, not the file hash — Hermes updates uv and the hash changes every version

For more context, see the upstream Astral reports: astral-sh/uv#13553, astral-sh/uv#15011, astral-sh/uv#10079.

Getting Started Copy Chapter

hermes              # Interactive CLI — start a conversation
hermes model        # Choose your LLM provider and model
hermes tools        # Configure which tools are enabled
hermes config set   # Set individual config values
hermes config get   # Print individual config values
hermes gateway      # Start the messaging gateway (Telegram, Discord, etc.)
hermes setup        # Run the full setup wizard (configures everything at once)
hermes claw migrate # Migrate from OpenClaw (if coming from OpenClaw)
hermes update       # Update to the latest version
hermes doctor       # Diagnose any issues

📖 Full documentation →

Skip the API-key collection — Nous Portal Copy Chapter

Hermes works with whatever provider you want — that's not changing. But if you'd rather not collect five separate API keys for the model, web search, image generation, TTS, and a cloud browser, Nous Portal covers all of them under one subscription:

• 300+ models — pick any of them with /model <name>
• Tool Gateway — web search, image generation (FAL), text-to-speech (OpenAI), cloud browser (Browser Use), all routed through your sub. No extra accounts.

One command from a fresh install:

hermes setup --portal

That logs you in via OAuth, sets Nous as your provider, and turns on the Tool Gateway. Check what's wired up any time with hermes portal info. Full details on the Tool Gateway docs page.

You can still bring your own keys per-tool whenever you want — the gateway is per-backend, not all-or-nothing.

CLI vs Messaging Quick Reference Copy Chapter

Hermes has two entry points: start the terminal UI with hermes, or run the gateway and talk to it from Telegram, Discord, Slack, WhatsApp, Signal, or Email. Once you're in a conversation, many slash commands are shared across both interfaces.

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

Documentation Copy Chapter

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

Migrating from OpenClaw Copy Chapter

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 Copy Chapter

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

Start with the PM developer workflow
for activation, daily use, dependency changes, and leaving the environment.
Development Setup covers the separate test environment and verification commands.

Community Copy Chapter

• 💬 Discord
• 📚 Skills Hub
• 🐛 Issues
• 🔌 computer-use-linux — Linux desktop-control MCP server for Hermes and other MCP hosts, with AT-SPI accessibility trees, Wayland/X11 input, screenshots, and compositor window targeting.
• 🔌 HermesClaw — Community WeChat bridge: Run Hermes Agent and OpenClaw on the same WeChat account.

License Copy Chapter

MIT — see LICENSE.

Built by Nous Research.

Index (`website/docs/index.mdx`) Copy Section

slug: / sidebar_position: 0 title: "Hermes Agent Documentation" hide_table_of_contents: true displayed_sidebar: docs Copy Chapter

import Link from "@docusaurus/Link";

Hermes Agent

The self-improving AI agent built by Nous Research. The only agent with a built-in learning loop — it creates skills from experience, improves them during use, nudges itself to persist knowledge, and builds a deepening model of who you are across sessions.

Install Copy Chapter

Windows or macOS Copy Section

To easily install the command-line and desktop applications, download the Hermes Desktop installer from our website and run it.

Without Hermes Desktop: Copy Section

For a command-line only install without Hermes Desktop, run:

For aarch64 Android devices, use the separate Termux APT guide.

Linux / macOS / WSL2

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

Windows (native)

Run in powershell:

iex (irm https://hermes-agent.nousresearch.com/install.ps1)

See the full Installation Guide for what the installer does, installation ownership and data locations, and Windows-specific notes. For the complete platform support matrix, see Platform Support.

:::tip Fastest path to a working agent
After installing, run hermes setup --portal — one OAuth covers a model plus all four Tool Gateway tools (web search, image generation, TTS, browser). See Nous Portal.
:::

What is Hermes Agent? Copy Chapter

It's not a coding copilot tethered to an IDE or a chatbot wrapper around a single API. It's an autonomous agent that gets more capable the longer it runs. It lives wherever you put it — a $5 VPS, a GPU cluster, or serverless infrastructure (Daytona, Modal) that costs nearly nothing when idle. Talk to it from Telegram while it works on a cloud VM you never SSH into yourself. It's not tied to your laptop.

Quick Links Copy Chapter

Key Features Copy Chapter

• A closed learning loop — Agent-curated memory with periodic nudges, autonomous skill creation, skill self-improvement during use, FTS5 cross-session recall with LLM summarization, and Honcho dialectic user modeling
• Runs anywhere, not just your laptop — 7 terminal backends: local, Docker, SSH, Daytona, Singularity, Modal, Vercel Sandbox. Daytona and Modal offer serverless persistence — your environment hibernates when idle, costing nearly nothing
• Lives where you do — CLI, Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Mattermost, Email, SMS, DingTalk, Feishu, WeCom, Weixin, QQ Bot, Yuanbao, BlueBubbles, Home Assistant, Microsoft Teams, Google Chat, and more — 20+ platforms from one gateway
• Built by model trainers — Created by Nous Research, the lab behind Hermes, Nomos, and Psyche. Works with Nous Portal, OpenRouter, OpenAI, or any endpoint
• Scheduled automations — Built-in cron with delivery to any platform
• Bot Mode — Build a durable team of specialist Bots that work together in group chats and through @mentions
• Delegates & parallelizes — Spawn isolated subagents for parallel workstreams. Programmatic Tool Calling via execute_code collapses multi-step pipelines into single inference calls
• Open standard skills — Compatible with agentskills.io. Skills are portable, shareable, and community-contributed via the Skills Hub
• Full web control — Search, extract, browse, vision, image generation, TTS — one subscription via Nous Portal bundles all of them
• MCP support — Connect to any MCP server for extended tool capabilities
• Research-ready — Batch processing, trajectory export, RL training with Atropos. Built by Nous Research — the lab behind Hermes, Nomos, and Psyche models

For LLMs and coding agents Copy Chapter

Machine-readable entry points to this documentation:

• /llms.txt — curated index of every doc page with short descriptions. ~17 KB, safe to load into an LLM context.
• /llms-full.txt — every doc page concatenated into a single markdown file for one-shot ingestion. ~1.8 MB.

Both files also resolve at /docs/llms.txt and /docs/llms-full.txt. Generated fresh on every deploy.

Getting Started Quickstart (`website/docs/getting-started/quickstart.md`) Copy Section

sidebar_position: 1 title: "Hermes Agent Quickstart" Copy Chapter

Hermes Agent Quickstart

Python dependency commands on this page use a
PM-prepared source checkout.
After a dependency change, reactivate the checkout and restart Hermes.

This guide gets you from zero to a working Hermes setup that survives real use. Install, choose a provider, verify a working chat, and know exactly what to do when something breaks.

Prefer to watch? Copy Chapter

Onchain AI Garage put together a Masterclass walkthrough of installation, setup, and basic commands — a good companion to this page if you'd rather follow along on video. For more, see the full Hermes Agent Tutorials & Use Cases playlist.

Who this is for Copy Chapter

• Brand new and want the shortest path to a working setup
• Switching providers and don't want to lose time to config mistakes
• Setting up Hermes for a team, bot, or always-on workflow
• Tired of "it installed, but it still does nothing"

The fastest path Copy Chapter

Pick the row that matches your goal:

Rule of thumb: if Hermes cannot complete a normal chat, do not add more features yet. Get one clean conversation working first, then layer on gateway, cron, skills, voice, or routing.

1. Install Hermes Agent Copy Chapter

With the Hermes Desktop installer on macOS or Windows (recommended) Copy Section

To easily install the command-line and desktop applications, download the Hermes Desktop installer from our website and run it.

Without Hermes Desktop: Copy Section

For a command-line only install without Hermes Desktop, run:

For aarch64 Android devices, use the separate Termux APT guide.

Linux / macOS / WSL2

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

Windows (native)

Run in powershell:

iex (irm https://hermes-agent.nousresearch.com/install.ps1)

After it finishes, reload your shell:

source ~/.bashrc   # or source ~/.zshrc

For detailed installation options, prerequisites, and troubleshooting, see the Installation guide.

2. Choose a Provider Copy Chapter

The single most important setup step. Use hermes model to walk through the choice interactively:

hermes model

:::tip Easiest path: Nous Portal
One subscription covers 300+ models plus the Tool Gateway (web search, image generation, TTS, cloud browser). On a fresh install:

hermes setup --portal

That logs you in, sets Nous as your provider, and turns on the Tool Gateway in one command.
:::

:::info Setup modes
On a fresh install, hermes setup offers three modes:

• Quick Setup (Nous Portal) — OAuth login, no API keys to manage; sets up a model plus the Tool Gateway tools, billed to your Nous Portal subscription. The recommended fast path.
• Full Setup — walk through every provider, tool, and option yourself (bring your own keys).
• Blank Slate — everything starts off except the bare minimum needed to run an agent: provider & model, the File Operations toolset, and the Terminal toolset. No web, browser, code execution, vision, memory, delegation, cron, skills, plugins, or MCP servers — and compression, checkpoints, smart routing, and memory capture are all disabled. After the minimal baseline is applied, you choose one of two paths: start with everything disabled (finish now with the minimal agent), or walk through all configurations (opt in to tools, skills, plugins, MCP, and messaging). Pick this when you want a minimal, fully-controlled agent and intend to enable only exactly what you need.

Blank Slate writes an explicit platform_toolsets.cli list plus agent.disabled_toolsets, so nothing you didn't choose ever loads — not even after hermes update. Re-enable anything later with hermes tools, seed skills with hermes skills opt-in --sync, or tune settings with hermes setup agent.
:::

Good defaults:

For most first-time users: choose a provider, accept the defaults unless you know why you're changing them. The full provider catalog with env vars and setup steps lives on the Providers page.

:::caution Minimum context: 64K tokens
Hermes Agent requires a model with at least 64,000 tokens of context. Models with smaller windows cannot maintain enough working memory for multi-step tool-calling workflows and will be rejected at startup. Most hosted models (Claude, GPT, Gemini, Qwen, DeepSeek) meet this easily. If you're running a local model, set its context size to at least 64K (e.g. --ctx-size 65536 for llama.cpp or -c 65536 for Ollama).
:::

:::tip
You can switch providers at any time with hermes model — no lock-in. For a full list of all supported providers and setup details, see AI Providers.
:::

How settings are stored Copy Section

Hermes separates secrets from normal config:

• Secrets and tokens → ~/.hermes/.env
• Non-secret settings → ~/.hermes/config.yaml

The easiest way to set values correctly is through the CLI:

hermes config set model anthropic/claude-opus-4.6
hermes config set terminal.backend docker
hermes config set OPENROUTER_API_KEY sk-or-...

The right value goes to the right file automatically.

3. Run Your First Chat Copy Chapter

hermes            # classic CLI
hermes --tui      # modern TUI (recommended)

You'll see a welcome banner with your model, available tools, and skills. Use a prompt that's specific and easy to verify:

:::tip Pick your interface
Hermes ships with two terminal interfaces: the classic prompt_toolkit CLI and a newer TUI with modal overlays, mouse selection, and non-blocking input. Both share the same sessions, slash commands, and config — try each with hermes vs hermes --tui.
:::

Summarize this repo in 5 bullets and tell me what the main entrypoint is.

Check my current directory and tell me what looks like the main project file.

Help me set up a clean GitHub PR workflow for this codebase.

What success looks like:

• The banner shows your chosen model/provider
• Hermes replies without error
• It can use a tool if needed (terminal, file read, web search)
• The conversation continues normally for more than one turn

If that works, you're past the hardest part.

4. Verify Sessions Work Copy Chapter

Before moving on, make sure resume works:

hermes --continue    # Resume the most recent session
hermes -c            # Short form

That should bring you back to the session you just had. If it doesn't, check whether you're in the same profile and whether the session actually saved. This matters later when you're juggling multiple setups or machines.

5. Try Key Features Copy Chapter

Use the terminal Copy Section

❯ What's my disk usage? Show the top 5 largest directories.

The agent runs terminal commands on your behalf and shows results.

Slash commands Copy Section

Type / to see an autocomplete dropdown of all commands:

Multi-line input Copy Section

Press Alt+Enter, Ctrl+J, or Shift+Enter to add a new line. Shift+Enter requires a terminal that sends it as a distinct sequence (Kitty / foot / WezTerm / Ghostty by default; iTerm2 / Alacritty / VS Code terminal once the Kitty keyboard protocol is enabled). Alt+Enter and Ctrl+J work in every terminal.

Interrupt the agent Copy Section

If the agent is taking too long, type a new message and press Enter — it interrupts the current task and switches to your new instructions. Ctrl+C also works.

6. Add the Next Layer Copy Chapter

Only after the base chat works. Pick what you need:

Bot or shared assistant Copy Section

hermes gateway setup    # Interactive platform configuration

Connect Telegram, Discord, Slack, WhatsApp, Signal, Email, Home Assistant (plugin), or Microsoft Teams.

Automation and tools Copy Section

• hermes tools — tune tool access per platform
• hermes skills — browse and install reusable workflows
• Cron — only after your bot or CLI setup is stable

Sandboxed terminal Copy Section

For safety, run the agent in a Docker container or on a remote server:

hermes config set terminal.backend docker    # Docker isolation
hermes config set terminal.backend ssh       # Remote server

For Docker sandboxes, you can also enable the egress credential-injection proxy so the sandbox never sees your real API keys — only opaque proxy tokens that work exclusively from behind a local TLS-intercepting daemon. See Egress proxy. Setup is hermes egress setup && hermes egress start; hermes setup terminal also points Docker users at it. Modal, SSH, Daytona, and Singularity are not wired yet.

Voice mode Copy Section

Run hermes tools and configure the Voice providers. Then enable /voice on
in the CLI and press Ctrl+B to record. PM handles missing supported
requirements; a dependency change can require a restart. Local Faster-Whisper
is not available on every architecture. See Voice Mode.

Skills Copy Section

Skills are on-demand instruction documents that teach Hermes how to do a specific task — deploy to Kubernetes, open a GitHub PR, fine-tune a model, search for GIFs. Each is a SKILL.md file with a name, a description, and a step-by-step procedure. The agent reads the short descriptions for free and only loads a skill's full content when a task actually calls for it, so adding skills doesn't bloat every request.

Hermes ships with a catalog of bundled skills already installed in ~/.hermes/skills/. You can add more from the Skills Hub, or write your own.

Browse and install from the hub:

hermes skills browse                      # list everything available
hermes skills search kubernetes           # find skills by keyword
hermes skills install openai/skills/k8s   # install one (runs a security scan first)

The install argument is a source/path slug from the hub — openai/skills/k8s means the k8s skill from OpenAI's catalog. hermes skills browse shows the exact slugs to use.

Use a skill — every installed skill becomes a slash command automatically:

/k8s deploy the staging manifest          # run the skill with a request
/k8s                                       # load it and let Hermes ask what you need

This works in the CLI and in any connected messaging platform. You don't have to install everything up front — the agent picks the right bundled skill on its own during normal conversation when a task matches one.

See Skills System for writing your own, external skill directories, and the full hub source list.

MCP servers Copy Section

# Add to ~/.hermes/config.yaml
mcp_servers:
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxx"

Editor integration (ACP) Copy Section

ACP support ships with the standard [all] extras, so the curl installer already includes it. Just run:

hermes acp

(If you installed without [all], run cd ~/.hermes/hermes-agent && python -c "import pm; pm.sync_venv(['acp'], explicit=True)" first.)

See ACP Editor Integration.

Common Failure Modes Copy Chapter

These are the problems that waste the most time:

Recovery Toolkit Copy Chapter

When something feels off, use this order:

1. hermes doctor
2. hermes model
3. hermes setup
4. hermes sessions list
5. hermes --continue
6. hermes gateway status

That sequence gets you from "broken vibes" back to a known state fast.

Quick Reference Copy Chapter

Next Steps Copy Chapter

• User Stories: real setups from the community, a good place to start if you're not sure what to hand Hermes first
• CLI Guide — Master the terminal interface
• Configuration — Customize your setup
• Messaging Gateway — Connect Telegram, Discord, Slack, WhatsApp, Signal, Email, Home Assistant, Teams, and more
• Tools & Toolsets — Explore available capabilities
• AI Providers — Full provider list and setup details
• Skills System — Reusable workflows and knowledge
• Tips & Best Practices — Power user tips
• Moving to another machine — hermes backup migrates your whole setup (or a single profile); no need to rebuild from scratch

Integrations Index (`website/docs/integrations/index.md`) Copy Section

title: "Integrations" sidebar_label: "Overview" sidebar_position: 0 Copy Chapter

Integrations

Hermes Agent connects to external systems for AI inference, tool servers, IDE workflows, programmatic access, and more. These integrations extend what Hermes can do and where it can run.

:::tip Start here
If you only have time to set up one integration, set up Nous Portal — a single OAuth login covers 300+ models plus the four Tool Gateway tools (web search, image generation, TTS, and browser automation).
:::

AI Providers & Routing Copy Chapter

Hermes supports multiple AI inference providers out of the box. Use hermes model to configure interactively, or set them in config.yaml.

• AI Providers — OpenRouter, Anthropic, OpenAI, Google, and any OpenAI-compatible endpoint. Hermes auto-detects capabilities like vision, streaming, and tool use per provider.
• Provider Routing — Fine-grained control over which underlying providers handle your OpenRouter requests. Optimize for cost, speed, or quality with sorting, whitelists, blacklists, and explicit priority ordering.
• Fallback Providers — Automatic failover to backup LLM providers when your primary model encounters errors. Includes primary model fallback and independent auxiliary task fallback for vision, compression, and web extraction.

Tool Servers (MCP) Copy Chapter

• MCP Servers — Connect Hermes to external tool servers via Model Context Protocol. Access tools from GitHub, databases, file systems, browser stacks, internal APIs, and more without writing native Hermes tools. Supports both stdio and SSE transports, per-server tool filtering, and capability-aware resource/prompt registration.

Web Search Backends Copy Chapter

The web_search and web_extract tools support eight backend providers, configured via config.yaml or hermes tools:

Quick setup example:

web:
  backend: firecrawl    # firecrawl | searxng | brave-free | ddgs | tavily | perplexity | keenable | exa | parallel | xai

If web.backend is not set, the backend is auto-detected from whichever API key is available. Self-hosted Firecrawl is also supported via FIRECRAWL_API_URL.

Browser Automation Copy Chapter

Hermes includes full browser automation with multiple backend options for navigating websites, filling forms, and extracting information:

• Browser Use Cloud — Managed Chromium with stealth, residential proxies, CAPTCHA solving, and reusable browser profiles
• Browserbase — Alternative cloud browser provider with managed browsers, anti-bot tooling, CAPTCHA solving, and residential proxies
• Local Chromium-family CDP — Connect to your running Chrome, Brave, Chromium, or Edge browser using /browser connect
• Local Chromium — Headless local browser via the agent-browser CLI

See Browser Automation for setup and usage.

Voice & TTS Providers Copy Chapter

Text-to-speech and speech-to-text across all messaging platforms:

Speech-to-text supports eight providers: local faster-whisper (free, runs on-device), a local command wrapper, Groq, OpenAI Whisper API, Mistral, xAI, ElevenLabs Scribe, and DeepInfra. Voice message transcription works across Telegram, Discord, WhatsApp, and other messaging platforms. See Voice & TTS and Voice Mode for details.

IDE & Editor Integration Copy Chapter

• IDE Integration (ACP) — Use Hermes Agent inside ACP-compatible editors such as VS Code, Zed, and JetBrains. Hermes runs as an ACP server, rendering chat messages, tool activity, file diffs, and terminal commands inside your editor.

Programmatic Access Copy Chapter

• API Server — Expose Hermes as an OpenAI-compatible HTTP endpoint. Any frontend that speaks the OpenAI format — Open WebUI, LobeChat, LibreChat, NextChat, ChatBox — can connect and use Hermes as a backend with its full toolset.

Memory & Personalization Copy Chapter

• Built-in Memory — Persistent, curated memory via MEMORY.md and USER.md files. The agent maintains bounded stores of personal notes and user profile data that survive across sessions.
• Memory Providers — Plug in external memory backends for deeper personalization. Two providers ship with Hermes: RetainDB (hybrid search) and ByteRover (CLI-based); Honcho (dialectic reasoning), Hindsight (knowledge graphs), Supermemory (semantic recall), Mem0 (cloud extraction), OpenViking (tiered retrieval) and Holographic (local SQLite) are available from the plugin catalog via hermes plugins install <name>.

Messaging Platforms Copy Chapter

Hermes runs as a gateway bot on 27+ messaging platforms, all configured through the same gateway subsystem:

• Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Mattermost, Email, SMS, DingTalk, Feishu/Lark, WeCom, WeCom Callback, Weixin, BlueBubbles, Buzz, QQ Bot, Yuanbao, Home Assistant (plugin), Microsoft Teams, Microsoft Teams Meetings, Microsoft Graph Webhook, Google Chat, LINE, ntfy, SimpleX, Open WebUI, Webhooks

See the Messaging Gateway overview for the platform comparison table and setup guide.

Quick connect links Copy Section

The big platforms have a canonical "create your bot/app" URL, and some accept parameters that pre-open the right form. Skip the console-hunting and go straight there:

Each platform's setup page walks through what to do once you're there.

Collaboration Workspaces Copy Chapter

• Buzz — Block's Nostr-based human+agent workspace. Three integration paths: Buzz Desktop spawns Hermes as a managed ACP runtime, the buzz-acp relay bridge hosts a Hermes identity server-side, or the native gateway platform joins Buzz channels with full Hermes memory/skills/approvals/cron. The overview page compares all three.

Home Automation Copy Chapter

• Home Assistant — Control smart home devices via four dedicated tools (ha_list_entities, ha_get_state, ha_list_services, ha_call_service) and react to real-time state changes through the gateway. Ships as the homeassistant catalog plugin (hermes plugins install homeassistant); its toolset activates automatically when HASS_TOKEN is configured.

Plugins Copy Chapter

• Plugin System — Extend Hermes with custom tools, lifecycle hooks, and CLI commands without modifying core code. Plugins are discovered from ~/.hermes/plugins/, project-local .hermes/plugins/, and pip-installed entry points.
• Build a Plugin — Step-by-step guide for creating Hermes plugins with tools, hooks, and CLI commands.

Training & Evaluation Copy Chapter

• Batch Processing — Run the agent across hundreds of prompts in parallel, generating structured ShareGPT-format trajectory data for training data generation or evaluation.

User Guide Windows Wsl Quickstart (`website/docs/user-guide/windows-wsl-quickstart.md`) Copy Section

title: "Windows (WSL2) Guide" sidebar_label: "Windows (WSL2)" sidebar_position: 2 Copy Chapter

Windows (WSL2) Guide

Hermes Agent now supports both native Windows and WSL2. This page covers the WSL2 path; for the native PowerShell install see the dedicated Windows (Native) Guide.

When to pick WSL2 over native:

• You want to use the dashboard's embedded terminal (/chat tab) — that pane requires a POSIX PTY and is WSL2-only.
• You're doing POSIX-heavy development work and want your Hermes sessions to share the same filesystem / paths as your dev tools.
• You already have a WSL2 environment and don't want to maintain a second install.

When native is fine (or better):

• Interactive chat, gateway (Telegram/Discord/etc.), cron scheduler, browser tool, MCP servers, and most Hermes features all run natively on Windows.
• You don't want to think about crossing the WSL↔Windows boundary every time you reference a file or open a URL.

In WSL2 there are effectively two computers in play: your Windows host, and a Linux VM managed by WSL. Most confusion comes from not being sure which one you're on at any moment.

This guide covers the parts of that split that specifically affect Hermes: installing WSL2, getting files back and forth between Windows and Linux, networking in both directions, and the pitfalls people actually hit.

:::info 简体中文
A Chinese-language walkthrough of the minimum install path is maintained on this same page — switch via the language menu (top right) and select 简体中文.
:::

Why WSL2 (vs. native Windows) Copy Chapter

The native Windows install runs in Windows directly: your Windows terminal (PowerShell, Windows Terminal, etc.), Windows filesystem paths (C:\Users\…), and Windows processes. Hermes uses Git Bash to run shell commands, which is how Claude Code and other agents handle Windows today — it sidesteps the POSIX-vs-Windows gap without a full rewrite.

WSL2 runs a real Linux kernel in a lightweight VM, so Hermes inside it is essentially identical to running on Ubuntu. That's valuable when you want a real POSIX environment: fork, /tmp, UNIX sockets, signal semantics, PTY-backed terminals, shells like bash/zsh, and tools like rg, git, ffmpeg that behave the way they do on Linux.

Practical consequences of WSL2:

• The Hermes CLI, gateway, sessions, memory, skills, and tool runtimes all live inside the Linux VM.
• Windows programs (browsers, native apps, Chrome with your logged-in profile) live outside it.
• Every time you want the two to talk — share files, open URLs, control Chrome, hit a local model server, expose the Hermes gateway to your phone — you cross a boundary. Those boundaries are what this guide is about.

Install WSL2 Copy Chapter

From an Admin PowerShell or Windows Terminal:

wsl --install

On a fresh Windows 10 22H2+ or Windows 11 box this installs the WSL2 kernel, the Virtual Machine Platform feature, and a default Ubuntu distro. Reboot when prompted. After reboot Ubuntu will open and ask for a Linux username + password — this is a new Linux user, unrelated to your Windows account.

Verify you're actually on WSL2 (not legacy WSL1):

wsl --list --verbose

You should see VERSION 2. If a distro shows VERSION 1, convert it:

wsl --set-version Ubuntu 2
wsl --set-default-version 2

Hermes does not work reliably on WSL1 — WSL1 translates Linux syscalls on the fly and some behaviors (procfs, signals, network) diverge from real Linux.

Distro choice Copy Section

Ubuntu (LTS) is what we test against. Debian works. Arch and NixOS work for people who want them, but the one-line installer assumes a Debian-derived apt system — see the Nix setup guide for that path.

Enable systemd (recommended) Copy Section

The hermes gateway (and anything else you want to keep running) is easier to manage with systemd. On modern WSL, enable it once inside your distro:

sudo tee /etc/wsl.conf >/dev/null <<'EOF'
[boot]
systemd=true

[interop]
enabled=true
appendWindowsPath=true

[automount]
options = "metadata,umask=22,fmask=11"
EOF

Then from PowerShell:

wsl --shutdown

Reopen your WSL terminal. ps -p 1 -o comm= should print systemd.

The metadata mount option above is important — without it, files on /mnt/c/... can't store real Linux permission bits, which breaks things like chmod +x on scripts under Windows paths.

Install Hermes inside WSL Copy Section

Once you have a WSL2 shell open:

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
source ~/.bashrc
hermes

The installer treats WSL2 as plain Linux — nothing WSL-specific is needed. See Installation for the full layout.

Filesystem: crossing the Windows ↔ WSL2 boundary Copy Chapter

This is the part that trips up the most people. There are two filesystems, and where you put your files matters — for performance, correctness, and what tools can see.

The two directions Copy Section

Both are real, both work, but they are not the same filesystem — they're bridged by a 9P network protocol under the hood. That has real performance and semantic consequences.

Where to put Hermes and your projects Copy Section

Rule of thumb: keep everything Linux-ish inside the Linux filesystem.

• Your Hermes install (~/.hermes/) — Linux side. The installer already does this.
• Your git repos that you work on from WSL — Linux side (~/code/..., ~/projects/...).
• Your models, datasets, venvs — Linux side.

What you get by following this rule:

• Fast I/O. Operations on /mnt/c/... go through 9P and are 10–100× slower than native ext4. git status on a 10k-file repo that feels instant under ~/code can take 15+ seconds under /mnt/c.
• Correct permissions. Linux permission bits are a best-effort emulation on /mnt/c. Things like ssh refusing a key with "bad permissions" or chmod +x silently failing are common.
• Reliable file watchers. inotify across 9P is flaky — file watchers (dev servers, test runners) routinely miss changes on /mnt/c.
• No case-sensitivity surprises. Windows paths are case-insensitive by default; Linux is case-sensitive. Projects with both Readme.md and README.md behave differently depending which side you're on.

Put things on /mnt/c only when you need a file to live on the Windows side — e.g., you want to open it from a Windows GUI app, or Windows Chrome's DevTools MCP needs the current directory to be a Windows-reachable path.

Getting files back and forth Copy Section

From Windows → into WSL: easiest is to open Explorer and type \\wsl.localhost\Ubuntu in the address bar. You can then drag-drop into \home\<you>\.... Or from PowerShell:

wsl cp /mnt/c/Users/you/Downloads/file.pdf ~/incoming/

From WSL → into Windows: copy to /mnt/c/Users/<you>/... and it shows up in Windows Explorer immediately:

cp ~/reports/output.pdf /mnt/c/Users/you/Desktop/

Open a WSL file in a Windows app (GUI editor, browser, etc.): use explorer.exe or wslview:

sudo apt install wslu     # once — gives you wslview, wslpath, wslopen, etc.
wslview ~/reports/output.pdf    # opens with the Windows default handler
explorer.exe .                  # opens the current WSL dir in Windows Explorer

Convert paths between the two universes:

wslpath -w ~/code/project        # → \\wsl.localhost\Ubuntu\home\you\code\project
wslpath -u 'C:\Users\you'        # → /mnt/c/Users/you

Line endings, BOMs, and git Copy Section

If you edit files on the Windows side with a Windows editor, they may get CRLF line endings. When bash or Python on the Linux side reads them, shell scripts break with bad interpreter: /bin/bash^M and Python can fail on BOM'd .env files.

The fix is a sane git config inside WSL (not on Windows):

git config --global core.autocrlf input
git config --global core.eol lf

For files that already have CRLF:

sudo apt install dos2unix
dos2unix path/to/script.sh

"Clone inside WSL or on `/mnt/c`?" Copy Section

Clone inside WSL. Always, unless you have a specific reason not to. A typical Hermes workflow (hermes chat, tool calls that rg/ripgrep the repo, file watchers, background gateway) will be dramatically faster and more reliable against ~/code/myrepo than /mnt/c/Users/you/myrepo.

One exception: MCP bridges that launch Windows binaries. If you're using chrome-devtools-mcp through cmd.exe (see MCP guide: WSL → Windows Chrome), Windows may complain with a UNC warning if Hermes's current working directory is ~. In that case, start Hermes from somewhere under /mnt/c/ so the Windows process has a drive-letter cwd.

Networking: WSL ↔ Windows Copy Chapter

WSL2 runs in a lightweight VM with its own network stack. That means localhost inside WSL is not the same as localhost on Windows — they're two separate hosts from the network's point of view. You need to decide, for each service, which direction traffic flows and pick the right bridge.

Two cases come up constantly.

Case 1 — Hermes in WSL talks to a service on Windows Copy Section

Most common: you're running Ollama, LM Studio, or a llama-server on Windows, and Hermes (inside WSL) needs to hit it.

The canonical how-to for this lives in the providers guide: WSL2 Networking for Local Models →

Short version:

• Windows 11 22H2+: turn on mirrored networking mode (networkingMode=mirrored in %USERPROFILE%\.wslconfig, then wsl --shutdown). localhost then works in both directions.
• Windows 10 or older builds: use the Windows host IP (the default gateway of WSL's virtual network) and make sure the server on Windows binds to 0.0.0.0, not just 127.0.0.1. Windows Firewall usually also needs a rule for the port.

For the full table (Ollama / LM Studio / vLLM / SGLang bind addresses, firewall rule one-liners, dynamic IP helpers, Hyper-V firewall workaround), follow the link above — don't duplicate it.

Case 2 — Something on Windows (or your LAN) talks to Hermes in WSL Copy Section

This is the reverse direction and is less documented elsewhere, but it's what you need for:

• Using the Hermes web dashboard from a Windows browser.
• Using the OpenAI-compatible API server (exposed by hermes gateway when API_SERVER_ENABLED=true) from a Windows-side tool. See the API Server feature page.
• Testing a messaging gateway (Telegram, Discord, etc.) where the platform pings a local webhook URL — usually you'd use cloudflared/ngrok rather than raw port forwarding.

Subcase 2a: from the Windows host itself

On Windows 11 22H2+ with mirrored mode enabled, there is nothing to do. A process in WSL that binds to 0.0.0.0:8080 (or even 127.0.0.1:8080) is reachable from a Windows browser at http://localhost:8080. WSL publishes the bind back to the host automatically.

On NAT mode (Windows 10 / older Windows 11), the default "localhost forwarding" in WSL2 will generally forward Linux-side 127.0.0.1 binds to Windows localhost, so a Hermes service started with --host 127.0.0.1 is usually reachable as http://localhost:PORT from Windows. If it isn't:

• Bind to 0.0.0.0 explicitly inside WSL.
• Find the WSL VM's IP with ip -4 addr show eth0 | grep inet and hit that from Windows.

Subcase 2b: from another device on your LAN (phone, tablet, another PC)

This is the real pain. Traffic flows LAN device → Windows host → WSL VM, and you have to set up both hops:

1. Bind on all interfaces inside WSL. A process listening on 127.0.0.1 will never be reachable from outside the VM. Use 0.0.0.0.

2. Port-forward Windows → WSL VM. In mirrored mode this is automatic. In NAT mode you have to do it yourself, per port, in Admin PowerShell:

   powershell Copy

   # Grab the WSL VM's current IP (it changes on every WSL restart under NAT)
   $wslIp = (wsl hostname -I).Trim().Split(' ')[0]
   
   # Forward Windows port 8080 → WSL:8080
   netsh interface portproxy add v4tov4 `
     listenaddress=0.0.0.0 listenport=8080 `
     connectaddress=$wslIp connectport=8080
   
   # Allow it through Windows Firewall
   New-NetFirewallRule -DisplayName "Hermes WSL 8080" `
     -Direction Inbound -Protocol TCP -LocalPort 8080 -Action Allow

   Remove later with netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=8080.

3. Point the LAN device at http://<windows-lan-ip>:8080.

Because the WSL VM IP drifts on each restart in NAT mode, a one-shot rule survives only until the next wsl --shutdown. For anything persistent, either use mirrored mode or put the port-proxy step in a script that runs at Windows login.

For webhooks from cloud messaging providers (Telegram setWebhook, Slack events, etc.), don't fight port-forwarding — use cloudflared tunnels. See the webhooks guide.

Running Hermes services long-term on Windows Copy Chapter

The Hermes Tool Gateway and the API server are long-lived processes. In WSL2 you have a few options for keeping them up.

Desktop shortcut for opening Hermes quickly Copy Section

If you just want a double-click launcher for an interactive Hermes shell, create
it on the Windows side and have it jump into WSL for you:

1. Right-click the Windows desktop and choose New -> Shortcut.

2. For the target, use your distro name (replace Ubuntu if needed):

   text Copy

   wt.exe -w 0 -p "Ubuntu" wsl.exe -d Ubuntu --cd ~ -- bash -ic "hermes"

3. Name it something obvious like Hermes.

That opens Windows Terminal, starts your WSL distro, drops you in your Linux
home directory, and launches Hermes. If hermes is not on PATH yet, open WSL
once manually and run source ~/.bashrc, or replace the command with
python hermes inside your PM-activated project checkout.

Optional polish:

• Custom icon: open Properties -> Change Icon and point it at an .ico
  file, such as the Hermes favicon from the repo.
• Pinned launcher: once the shortcut works, pin it to Start or Taskbar so
  you do not have to browse for it again.

Inside WSL with systemd (recommended) Copy Section

If you enabled systemd per the setup section above, hermes gateway and the API server work the way they do on any Linux machine. Use the gateway setup wizard:

hermes gateway setup

It will offer to install a systemd user unit so the gateway comes up automatically when WSL starts.

Making WSL itself start on Windows login Copy Section

WSL's VM only stays alive while something is using it. To keep your gateway reachable without a terminal window open, boot a WSL process at Windows login via Task Scheduler:

• Trigger: At log on (your user).
• Action: Start a program
  • Program: C:\Windows\System32\wsl.exe
  • Arguments: -d Ubuntu --exec /bin/sh -c "sleep infinity"

That keeps the VM alive so the systemd-managed gateway stays running. On Windows 11, the newer wsl --install --no-launch + auto-start flows also work; the sleep infinity trick is the portable version.

GPU passthrough (local models) Copy Chapter

WSL2 supports NVIDIA GPUs natively since WSL kernel 5.10.43+ — install the standard NVIDIA driver on Windows (do not install a Linux NVIDIA driver inside WSL), and nvidia-smi inside WSL will see the GPU. From there, CUDA toolkits, torch, vllm, sglang, and llama-server build against the real GPU as usual.

AMD ROCm and Intel Arc support inside WSL2 is still evolving and outside Hermes's test matrix — it may work with current drivers but we don't have a recipe to recommend.

If you're running a Windows-native local-model server (Ollama for Windows, LM Studio) that already uses your GPU through Windows drivers, you don't need WSL GPU passthrough at all — just follow Case 1 above and hit it over the network from WSL.

Common pitfalls Copy Chapter

"Connection refused" to my Windows-hosted Ollama / LM Studio.
See WSL2 Networking. Ninety percent of the time the server is bound to 127.0.0.1 and needs 0.0.0.0 (Ollama: OLLAMA_HOST=0.0.0.0), or you're missing a firewall rule.

Massive slowness on git status / hermes chat in a repo.
You're probably working under /mnt/c/.... Move the repo to ~/code/... (Linux side). Order-of-magnitude faster.

bad interpreter: /bin/bash^M on scripts.
CRLF line endings from a Windows editor. dos2unix script.sh, and set core.autocrlf input in your WSL git config.

"UNC paths are not supported" warning from Windows binaries launched via MCP.
Hermes's cwd is inside the Linux filesystem, and Windows cmd.exe doesn't know what to do with it. Start Hermes from /mnt/c/... for that session, or use a wrapper that cds to a Windows-reachable path before invoking the Windows executable.

Clock drift after sleep/hibernate.
WSL2's clock can lag by minutes after the host resumes from sleep, which breaks anything cert-based (OAuth, HTTPS APIs). Fix it on demand:

sudo hwclock -s

Or install ntpdate and run it at login.

DNS stops working after enabling mirrored mode, or when a VPN is connected.
Mirrored mode proxies host network settings into WSL — if Windows DNS is funky (VPN split-tunnel, corporate resolver), WSL inherits that. Workaround: override resolv.conf manually (set generateResolvConf=false in /etc/wsl.conf, then write your own /etc/resolv.conf with 1.1.1.1 or your VPN's DNS).

hermes not found after running the installer.
The installer adds ~/.local/bin to your shell's PATH via ~/.bashrc. You need to source ~/.bashrc (or open a new terminal) for it to take effect in the current session.

Windows Defender is slow on WSL files.
Defender scans files via the 9P bridge when accessed from Windows, which magnifies the slowness of /mnt/c-style cross-boundary access. If you only touch WSL files from inside WSL, this doesn't matter. If you use Windows tools against \\wsl$\... frequently, consider excluding the WSL distro path from real-time scanning.

Running out of disk.
WSL2 stores its VM disk as a sparse VHDX under %LOCALAPPDATA%\Packages\.... It grows but doesn't auto-shrink when you delete files. To reclaim space: wsl --shutdown, then from an Admin PowerShell run Optimize-VHD -Path -Mode Full (requires Hyper-V tools) — or the simpler diskpart path documented on the WSL docs.

Where to go next Copy Chapter

• Installation — actual install steps (Linux/WSL2 use the same installer).
• Integrations → Providers → WSL2 Networking — the canonical networking deep-dive for local model servers.
• MCP guide → WSL → Windows Chrome — controlling your signed-in Windows Chrome from Hermes in WSL.
• Tool Gateway and Web Dashboard — the long-lived services you'll most often want to expose from WSL to the rest of your network.

Developer Guide Plugins Index (`website/docs/developer-guide/plugins/index.md`) Copy Section

sidebar_label: "Build a Plugin" slug: /developer-guide/plugins title: "Build a Hermes Plugin" Copy Chapter

Build a Hermes Plugin

This guide walks through building a complete Hermes plugin from scratch. By the end you'll have a working plugin with multiple tools, lifecycle hooks, shipped data files, and a bundled skill — everything the plugin system supports.

:::info Not sure which guide you need?
Hermes has several distinct pluggable interfaces — some use Python register_* APIs, others are config-driven or drop-in directories. Use this map first:

See the full Pluggable interfaces table for a consolidated view of every extension surface including config-driven (TTS, STT, MCP, shell hooks) and drop-in directory (gateway hooks) styles.
:::

:::caution Third-party-product plugins ship standalone — not into the core tree
Plugins that integrate someone else's product or project — observability/metrics backends, vendor SaaS connectors, analytics dashboards, paid-service tie-ins — are built and distributed as standalone plugin repos, not merged into NousResearch/hermes-agent. Users install them into ~/.hermes/plugins/ or via a pip entry point; everything in this guide works the same way from a standalone repo. This is a coupling-and-maintenance decision (the core moves fast and we don't own your backend), not a quality bar — a plugin can be excellent and still belong in its own repo. Promote it in the Nous Research Discord #plugins-skills-and-skins channel. See CONTRIBUTING.md for the policy.
:::

:::tip Already built in: check here before you hand-roll it
Hermes already ships these for plugin authors:

• Run the catalog check locally: hermes plugins validate /path/to/your-plugin --install-deps runs the same check catalog CI runs. See Submitting to the Plugin Catalog.
• Test your plugin in isolation: hermes plugins doctor [path-or-id] runs the same discovery, manifest parser, register(ctx) and registries Hermes uses, with a temporary HERMES_HOME. See Validate with Plugin Doctor.
• Keep state across updates: plugin_data_dir() and plugin_db() give your plugin a data directory that survives hermes plugins update and remove and follows the active profile. See Store durable state.
• Declare Python dependencies: list them under python_dependencies in plugin.yaml, or in a pyproject.toml next to it. See Python dependencies.
• Ship skills with your plugin: register them with ctx.register_skill(). See Bundle skills.
• Ask for privileged host surfaces: declare them under capabilities: so users get a single consent screen. See Declaring capabilities.
• Make LLM calls: use ctx.llm, which comes with host-owned credentials and a fail-closed trust gate. See Plugin LLM Access.
  :::

Portable Agent Plugins v1 packages Copy Chapter

Hermes can also install and load directory packages that target the Agent
Plugins v1.0.0 format. This is a compatibility adapter for the portable
components Hermes already owns. It does not replace native plugin.yaml plus
register(ctx) plugins.

my-portable-plugin/
├── plugin.json
├── skills/
│   └── summarize/
│       ├── SKILL.md
│       └── references/
└── mcp.json

Install and activate a portable package through the normal workflow:

hermes plugins install owner/repository --no-enable
hermes plugins list
hermes plugins enable <plugin-name>

Portable packages are disabled after installation unless you explicitly enable
them. An enabled package may provide immediate skills/*/SKILL.md directories
and stdio MCP servers from root mcp.json. Skills are read-only, namespaced,
and loaded through skills_list plus skill_view. MCP commands are passed as
one executable token with a separate argument list, never through a shell.
Use skills_list to discover the full qualified skill name. Portable skill
namespaces have the deterministic form agent-plugin-<slug>-<hash>, derived
from the discovered plugin key so sanitized names cannot collide. A portable
package's MCP servers keep the names their mcp.json gives them, the same rule
as a user's own mcp_servers block, so the model-facing mcp__<server>__<tool>
name keeps the tool verb inside the 64-character provider cap. A duplicate server
name is a load-time conflict: a config.yaml server wins over a package, and the
first-loaded package wins over the next; the loser is skipped with a warning
naming both.

Hermes validates plugin.json, Agent Skills frontmatter, fixed component
locations, mcp.json, resolved paths, and symlink containment locally. It does
not fetch JSON schemas while loading a package. A bad skill or MCP entry is
skipped at its own boundary when valid sibling components can still load.
PLUGIN_ROOT points to the resolved package root. PLUGIN_DATA points to a
profile-scoped writable directory managed by Hermes.
Values declared in portable MCP env are visible package data, not a secret
storage mechanism. Do not place credentials in mcp.json.
To pass a user's variable through to a stdio server (Hermes otherwise hands MCP
servers a filtered environment), declare it as "NAME": "${NAME}". The value
comes from the user's shell or profile .env; when the variable is unset (or
empty), the entry is treated as if it weren't there: the server doesn't get the
literal ${NAME}, and NAME keeps whatever value the server would have without
that line (usually unset). Optional variables are safe to forward.

The current portable subset supports stdio and Streamable HTTP MCP entries.
Portable streamable-http entries are routed through Hermes' existing native
remote MCP client (the same runtime that powers URL-based mcp_servers
config), with the v1 boundary rules enforced: the URL must be absolute
http(s) with no user information or fragment, plain HTTP is accepted only
for localhost/loopback hosts, and configured headers are never forwarded
across a cross-origin redirect. Legacy sse entries are reported and
skipped. Agent Plugins v1 does not define trust, permissions, provenance, or a
sandbox. Enabling a package grants its instructions and local executable the
same full-trust posture as other installed Hermes plugins.

A package can ask Hermes to gate one of its MCP servers, the same way a user's
trust: untrusted does in config.yaml. Use it for servers whose tools spend
money, trade, send messages or change accounts, so the user approves each
write-capable call instead of relying on the skill's instructions alone:

{
  "extensions": {
    "com.nousresearch.hermes": {
      "servers": {
        "trade": { "trust": "untrusted" }
      }
    }
  }
}

The server name must match an mcp.json entry. With untrusted, every tool
call to that server that is not annotated readOnlyHint: true asks the user
first, and fails closed where nobody can answer (cron, unattended runs). The
only other accepted value is full, the default, so a package can narrow
access but never widen it. A config.yaml server with the same name replaces
the package's entry, including its trust, but keeps the package's declared costs
and spend limit (below) unless it sets its own. Other harnesses ignore this extension.
trust can sit beside app, requires and liveness in the same server
entry (see Application declarations).

A server whose tools spend money or credits can declare what each call costs
and a budget per chat. Hermes then names the cost in the approval prompt along
with the chat's running total, and a call that would take the chat past
spend_limit asks first even when the user has made the server trusted:

{
  "extensions": {
    "com.nousresearch.hermes": {
      "servers": {
        "renders": {
          "trust": "untrusted",
          "costs": {
            "create_image": 20,
            "animate": { "credits": [5, 20], "note": "per animation" }
          },
          "spend_limit": 100,
          "cost_unit": "credits"
        }
      }
    }
  }
}

Keys of costs are MCP tool names as the server lists them. A cost is a
non-negative number, a [min, max] range, or an object with credits (number
or range) and a short note. spend_limit is optional (0 or absent = no
limit) and cost_unit defaults to credits. A malformed table makes the
package fail to load with an error naming the key. These map to the native
tool_costs, spend_limit and cost_unit keys (see
Tool costs and spend limits).
Costs are facts about the server, so they survive a user's same-name
config.yaml entry (the way a user widens trust) unless that entry sets the
key itself; the user's spend_limit wins, including 0 to turn it off.

A long-running server can also declare a Hermes-specific tool-call timeout
(in seconds) in plugin.json, without changing other servers' defaults:

{
  "extensions": {
    "com.nousresearch.hermes": {
      "servers": { "analysis": { "timeout": 1000 } }
    }
  }
}

The value must be a positive finite number within the platform's thread-wait
limit. It maps to the native per-server timeout; omission preserves the
existing timeouts.mcp.tool_call fallback. A same-name native mcp_servers
entry still replaces the entire package entry, including its timeout. This
extends the wait budget, not the cancellation or permission policy. Configure
any server-internal analysis deadline separately and leave time for its result
to reach the client. Other harnesses ignore this extension.

A server entry key this Hermes does not know (one a newer release added) is
ignored with a warning, which hermes plugins validate lists, and the package
still installs. Releases from before this rule reject the package instead, and a
release that ignores a key may behave less safely than intended, so declare a new
key together with a catalog requires_hermes floor.

An explicit per-server MCP call budget also reaches Hermes' outer tool executor. A call
whose budget exceeds the shared concurrent-batch deadline becomes a sequential
barrier, whether called directly or through tool search. It gets its own budget
without extending unrelated tools in the same model response. Existing shorter
MCP calls retain their normal parallel-admission policy; interruption and
approval handling are unchanged.

The rendered specification currently
labels v1.0.0 a Working Draft, while the
versioned specification repository
records it as Published. Hermes keys behavior on the canonical v1.0.0 schema
identifiers and normative text, not either mutable status label. This is an
explicit supported subset, not a claim of full Agent Plugins conformance.

Native plugin compatibility contract Copy Chapter

Native plugin.yaml plus register(ctx) plugins are protected by behavior,
not by one global plugin API number. Hermes does not expose a
PLUGIN_API_VERSION, require a manifest-wide api: match, or attach an API
version to unrelated values. A plugin that uses a documented behavior should
continue to work after a normal Hermes upgrade.

The compatibility rules are:

• Evolve additively. Documented PluginContext methods are not removed or
  renamed. New parameters are optional, have defaults, and should be
  keyword-only. Existing return fields are not removed or silently retyped.
• Hook payloads are keyword payloads. New hook data is added as keyword
  fields, never by changing the meaning or position of an existing field.
  Hermes inspects callback signatures: a legacy callback receives the fields it
  declares, while a callback with **kwargs receives the complete current
  payload. New plugins should accept **kwargs so they can opt into additive
  data without another signature change.
• Manifests are open to additions. Unknown plugin.yaml fields are ignored.
  Older Hermes releases can therefore load a plugin whose manifest contains
  metadata introduced by a newer release, provided the plugin code itself uses
  supported runtime behavior.
• Provider interfaces grow through defaults. New provider methods have a
  default implementation. New callback context is optional and forwarded only
  when signature inspection shows that a provider accepts it. Adding an
  abstract method or an unconditionally forwarded argument requires a
  migration window rather than a flag-day signature change.
• Version the contract that crosses a boundary. A capability may carry its
  own schema version when it defines a wire payload or persisted format (for
  example, observer payloads or secret-source state). Keep fields additive
  within that local schema. Persisted plugin state and config must remain
  readable, or ship an explicit migration; resumed sessions written by the old
  format must still replay. Do not add version literals to unrelated callback
  or context values.

The contract covers documented surfaces only. Replacing or wrapping core
functions, methods, module attributes or private tables at runtime (assigning
AIAgent.<method>, setattr on a Hermes module, writing into
sys.modules or a core dict) is not a supported extension point. It breaks
whenever the internals move, and it collides with every other plugin patching
the same seam. The plugin catalog refuses it at admission (hermes plugins validate, no core override check). If a public hook you need is missing,
open an issue describing it.

Deprecation policy Copy Section

A documented native plugin behavior may be deprecated only with all of the
following:

1. a replacement and migration instructions in the plugin guide and release
   notes;
2. a warning emitted at most once per process, naming the replacement and the
   earliest removal release;
3. support for the old behavior through at least two subsequent minor
   releases; and
4. behavior-based compatibility coverage for both the legacy path and the
   replacement throughout that window.

Removal after the window must include any migration needed for persisted data
or resumable sessions. In practice, additive aliases and adapters are preferred
to removal.

Hermes enforces this contract with frozen external-plugin fixtures discovered
from an isolated HERMES_HOME. Those tests load and invoke the plugin through
PluginManager; they assert real registration and callback outcomes rather
than internal symbol lists or source-code shape.

Sep 2026 module decomposition: old import paths removed Copy Section

Hermes's internals were split into <stem>_<topic> sibling modules in Sep 2026 (PR #102117). Internal
import paths were never part of the plugin contract above. A temporary compatibility layer kept the old
paths resolving until 2026-09-14; it has been removed, so a plugin that still imports an old path fails to
load with an ImportError (the reason shows in hermes plugins list).

To fix such a plugin, import the name from the module that defines it now, or better, use ctx and the
documented ABCs instead of internals. The full old-to-new map is the
COMPAT_MANIFEST.md
from the last commit that shipped the layer.

What you're building Copy Chapter

A calculator plugin with two tools:

• calculate — evaluate math expressions (2**16, sqrt(144), pi * 5**2)
• unit_convert — convert between units (100 F → 37.78 C, 5 km → 3.11 mi)

Plus a hook that logs every tool call, and a bundled skill file.

Step 1: Create the plugin directory Copy Chapter

Create a directory and continue with Step 2:

mkdir -p ~/.hermes/plugins/calculator
cd ~/.hermes/plugins/calculator

Validate with Plugin Doctor Copy Section

hermes plugins doctor [path-or-id] runs the same directory discovery,
manifest parser, namespaced import, register(ctx), hook registry, and tool
registry used by Hermes itself. It reports invalid hook names, callbacks that do
not accept **kwargs, registration failures, and drift between declared and
registered tools/hooks. For a package with a desktop/plugin.js, it also warns
when the Desktop app is running a stale copy of it (see
Developing a unified package).
Pass --ci to exit non-zero on an error:

hermes plugins doctor . --ci

Doctor uses a temporary HERMES_HOME, restores plugin registration state after
the check, and blocks direct Python socket connections to catch accidental
network access while registration runs. This is not a sandbox: plugin code still
executes in-process with the current user's permissions and can spawn subprocesses,
so only run Doctor on code you trust enough to import.

Step 2: Write the manifest Copy Chapter

Create plugin.yaml:

name: calculator
version: 1.0.0
description: Math calculator — evaluate expressions and convert units
provides_tools:
  - calculate
  - unit_convert
provides_hooks:
  - post_tool_call

This tells Hermes: "I'm a plugin called calculator, I provide tools and hooks." The provides_tools and provides_hooks fields are lists of what the plugin registers.

List every tool your register() registers in provides_tools. The field does not decide whether a user-installed plugin's tools load: once the plugin is enabled, everything register() registers is available, declared or not. What it does drive:

• hermes plugins validate: the "declared tools" check fails when the registered tools don't match the list, which blocks catalog admission.
• Catalog listing: the "N tools" chips and tool-name search in the catalog and the dashboard/Desktop Plugins page.
• Dashboard auth hint: only declared tools' availability checks are used to show "needs auth" and the hermes auth <name> command.
• Bundled kind: platform plugins only: the field is the switch that loads tools.py in CLI/TUI sessions while the adapter stays deferred. See Outbound client tools.

Optional fields you could add:

author: Your Name
requires_env:          # gate loading on env vars; prompted during install
  - SOME_API_KEY       # simple format — plugin disabled if missing
  - name: OTHER_KEY    # rich format — shows description/url during install
    description: "Key for the Other service"
    url: "https://other.com/keys"
    secret: true
capabilities:          # privileged host surfaces you request (consent flow)
  - tools.override     # replace built-in tools (needs user consent)
  - llm.model_override # choose the model for host-owned LLM calls

Declaring capabilities Copy Section

If your plugin needs a privileged host surface — overriding a built-in tool,
picking the model for ctx.llm calls, etc. — declare it in capabilities:.
At install/enable time the user sees the list and consents once; if a later
version adds a capability, the update flow asks again for just the addition.
Undeclared or unconsented capabilities are simply off (fail closed), so
probe before using them and degrade gracefully:

def register(ctx):
    if ctx.has_capability("tools.override"):
        ctx.register_tool(..., override=True)
    else:
        ctx.register_tool(...)   # register under a non-conflicting name

Known capability ids: tools.override, llm.provider_override,
llm.model_override, llm.agent_id_override, llm.profile_override,
llm.task_override (see hermes_cli/plugin_capabilities.py for the
canonical registry). Unknown ids are ignored. The older per-capability
config keys (plugins.entries..allow_tool_override, …) still work but
are deprecated — declare capabilities instead so users get a single,
auditable consent screen. Capabilities are consent + audit, not a
sandbox: they gate host API surfaces, nothing more.

Pip-distributed plugins have no plugin.yaml directory once installed,
so declare capabilities in distribution metadata instead, via the companion
hermes_agent.plugin_capabilities entry-point group. Each declaration is
named .<capability-id> and points at the same object as your
hermes_agent.plugins entry point:

[project.entry-points."hermes_agent.plugins"]
calculator = "my_pkg:register"

[project.entry-points."hermes_agent.plugin_capabilities"]
"calculator.tools.override" = "my_pkg:register"

Hermes reads these from installed metadata without importing your code, so
hermes plugins capabilities and the consent flow stay accurate for pip
installs.

Use the user's Codex sign-in (core-made requests) Copy Section

A plugin that needs the user's ChatGPT / Codex subscription (minting an OpenAI
Realtime client secret, calling a Codex backend endpoint) must not read,
refresh or rewrite ~/.codex/auth.json or Hermes's auth.json. Codex refresh
tokens are single-use: a plugin that refreshes on its own races Hermes's locked
refresh, and the loser's rotation chain gets revoked, signing the user out.
Ask Hermes to make the request instead. Hermes resolves the credential through
its own refresh path, attaches Authorization itself and returns only the
response. Your code never sees the token.

Declare the sign-in in plugin.yaml:

name: live-voice
requires_auth:
  - openai-codex

Then call the public helper. It is a plain function, so dashboard plugins
(dashboard/plugin_api.py) and vendored modules can import it as well as
register(ctx) code:

from hermes_cli.plugin_provider_requests import ProviderNotSignedIn, credentialed_provider_request

def mint_client_secret(session: dict) -> dict:
    try:
        resp = credentialed_provider_request(
            "openai-codex", "POST", "https://api.openai.com/v1/realtime/client_secrets",
            json={"session": session}, timeout=15)
    except ProviderNotSignedIn as exc:
        return {"ok": False, "error": str(exc)}  # tells the user how to sign in
    if resp.status != 200:
        return {"ok": False, "error": f"client secret failed ({resp.status}): {resp.text[:300]}"}
    return {"ok": True, **resp.json()}

This replaces a hand-rolled helper that read ~/.codex/auth.json, POSTed to
auth.openai.com/oauth/token when the token was near expiry and wrote the
result back. Delete that code; there is no refresh step left for the plugin.

credentialed_provider_request(provider, method, url, *, json=None, headers=None, timeout=30.0)
returns a ProviderResponse (status, headers, body, .text, .json()).
The rules:

• Declared plugins only. The caller is the plugin whose file is on the call
  stack. Hermes finds it under the plugins directory and reads its
  plugin.yaml. A plugin that does not list the provider in requires_auth,
  and code outside any installed plugin, gets PermissionError. Call the helper
  from your own function. Handing the bare helper to run_in_executor leaves no
  plugin frame on the stack, so the call is refused.
• Provider origins only. For openai-codex the token is sent only to
  https://chatgpt.com and https://api.openai.com. Any other URL raises
  PermissionError before a request is made. A profile whose Codex credential
  routes to a custom gateway is refused too, because that key belongs to the
  gateway.
• No redirects. A 3xx response comes back as-is and is never followed, so
  the header cannot reach a third host.
• Profile-scoped. The credential is the active profile's Codex sign-in, the
  same one chat uses (hermes auth add openai-codex, or the Codex sign-in in the
  desktop app). When there is none you get ProviderNotSignedIn, whose message
  names the sign-in command.
• Your own headers are sent too, except any that would replace the
  Authorization (or account) headers Hermes attaches.

requires_auth appears in hermes plugins show <name> and at install time, and
a catalog re-pin that adds it asks the user before updating. Like capabilities,
this is consent and visibility. It is not a sandbox: in-process plugin code
can still read any file the user can, and reviewers reject plugins that do.

Usage panels: don't call the usage endpoints yourself. Use
agent.account_usage.fetch_account_usage("openai-codex", read_only=True). It
returns an AccountUsageSnapshot (plan, session/weekly windows with
used_percent and reset_at) and never refreshes or rotates a credential.
Sign-out belongs to Hermes, not to a plugin: point users at
hermes auth logout openai-codex instead of deleting credential files.

Use your own OAuth client (Google and other APIs) Copy Section

A plugin that calls a third-party API with the user's own OAuth client (a
Google Cloud "Desktop app" client, for example) does not run the
consent flow, store the refresh token or refresh it. Declare the client and
Hermes owns the grant:

name: gemini-voice
requires_env:
  - name: GEMINI_VOICE_CLIENT_ID
  - name: GEMINI_VOICE_CLIENT_SECRET
    secret: true
oauth:
  - id: google
    authorize_url: https://accounts.google.com/o/oauth2/v2/auth
    token_url: https://oauth2.googleapis.com/token
    scopes:
      - https://www.googleapis.com/auth/calendar.events.owned
      - https://www.googleapis.com/auth/documents
    client_id_env: GEMINI_VOICE_CLIENT_ID
    client_secret_env: GEMINI_VOICE_CLIENT_SECRET  # optional: a public PKCE client has none
    hosts: [www.googleapis.com, docs.googleapis.com]
    authorize_params: {access_type: offline, prompt: consent}  # Google issues a refresh token only with these

The user signs in once from a terminal with hermes auth add gemini-voice:google
(the plugin's key, a colon, the entry's id). That is the same PKCE login the
model-provider helper runs: a loopback redirect on 127.0.0.1, with an SSH
tunnel hint when Hermes runs on a remote host. If the IdP grants fewer scopes
than declared, nothing is saved. hermes auth status|refresh|logout gemini-voice:google show, refresh and remove the grant. It lives in the active
profile's auth.json; Hermes refreshes it on use once less than two minutes
remain and never starts a sign-in under the gateway or cron.

The plugin calls the API through the same helper, with the entry's id as the
provider:

from hermes_cli.auth_constants import AuthError
from hermes_cli.plugin_provider_requests import ProviderNotSignedIn, credentialed_provider_request

def create_document(title: str) -> dict:
    try:
        resp = credentialed_provider_request(
            "google", "POST", "https://docs.googleapis.com/v1/documents", json={"title": title}, timeout=20)
    except ProviderNotSignedIn as exc:
        return {"ok": False, "error": str(exc)}  # names `hermes auth add gemini-voice:google`
    except AuthError as exc:
        return {"ok": False, "error": f"{exc.code}: {exc}"}
    return {"ok": resp.status < 300, "status": resp.status, "body": resp.json()}

The Codex rules above apply, plus:

• HTTPS only. authorize_url, token_url and every hosts entry are
  https (there is no loopback exception); hermes plugins validate and
  catalog admission fail anything else.
• Declared hosts only. The bearer goes to https://<host> (port 443) for
  the entry's hosts, matched exactly (no subdomains). Any other URL, http,
  or a URL with user info raises PermissionError before a request is made.
  A host outside the sign-in provider's domains is a warning reviewers check.
• Your own client variables. client_id_env and client_secret_env name
  the plugin's own variables; a variable Hermes itself uses (a provider API key,
  a platform token) is refused, since Hermes sends these to token_url.
• The plugin's own grant. The grant is stored under the calling plugin's
  key, so another plugin declaring the same id cannot use it, and the plugin's
  own entry wins over a Hermes sign-in of the same name.
• The grant follows the declaration. It remembers the entry it was made
  for: a plugin version that changes the token URL, hosts, scopes or client
  variables gets ProviderNotSignedIn until the user signs in again, and a
  catalog re-pin that adds an oauth entry or changes its authorize host, token
  host, hosts or scopes asks before updating.
• Errors. ProviderNotSignedIn: not signed in, revoked, or the entry
  changed since sign-in. AuthError codes: oauth_client_id_missing and
  oauth_client_secret_missing (the variable is not set), invalid_client,
  unauthorized_client and invalid_scope (the IdP rejected the client; the
  user has to fix it), oauth_refresh_failed (network or server error; try
  later). A revoked grant (invalid_grant) is retired: nothing goes to the
  network until the next sign-in. Errors reach the plugin without a traceback,
  chain or request object, so none leads back to the token, refresh token or
  client secret.
• Sign-in and removal. hermes auth add prints which hosts get the code,
  the client secret and the token before opening the browser, and refuses to
  run from the gateway, cron or an agent session. hermes plugins remove drops
  the plugin's grants, and hermes auth logout : still works after
  the plugin is gone.

hermes plugins validate checks the oauth: block and that its client
variables are declared, and warns when plugin code names the token URL. Like
requires_auth, this is consent and visibility, not a sandbox.

Manifest v2 reference Copy Section

plugin.yaml also supports an additive v2 schema (#64165). Every field is
optional; a manifest without manifest_version is a v1 manifest and stays
fully supported forever. Unknown fields never break loading — they are ignored
with a warning (forward compatibility), and a manifest_version newer than
this Hermes understands still loads with a warning.

# plugin.yaml — manifest v2 example
name: my-plugin
version: 1.2.0
manifest_version: 2
api_version: 1
license: MIT
homepage: https://github.com/owner/my-plugin
tags: [gateway, demo]
requires_plugins:
  - id: other-plugin
    version_range: ">=1.0,<2"
python_dependencies:
  - "somepkg>=1.0,<2"     # consent before PM admission
config_schema:
  api_url: {type: str, default: "", description: "Service endpoint"}

:::note Shared dependency admission
Plugin installation requests Python dependency consent. Enabling the plugin
prepares its requirements with core dependencies, extras, and enabled plugins
through PM. Pack enables use the same admission transaction. Reinstalling an
active plugin requests consent against its staged declaration before publication.
A refusal preserves the installed plugin and selected environment.

The installer and PM admission reject unsupported manifest_version values
and unmet requires_hermes constraints before publication.
:::

Python dependencies Copy Section

A directory plugin can bring its own PyPI packages. Declare them either in the manifest
(python_dependencies, above) or, preferably, in a pyproject.toml next to plugin.yaml:

[project]
name = "my-plugin"
version = "1.0.0"
requires-python = ">=3.11"
dependencies = [
    "somepkg>=1.0,<2",
    "other[extra]>=3.11",
]

When both exist the pyproject.toml wins. What Hermes does with them:

• Install / enable — PM resolves core, selected extras, and the enabled plugin union
  across every profile sharing the dependency home, including custom HERMES_HOME roots.
  A new plugin is downloaded disabled; Python dependency consent precedes enablement.
  pyproject.toml takes precedence over python_dependencies and legacy pip_dependencies.
• Atomic publication — PM prepares a fresh environment generation before publishing
  an enablement or an active plugin replacement. Resolution, download, or build failure
  preserves the previous environment and plugin selection; no existing plugin is sacrificed.
• Updates retain the union — hermes update includes enabled plugins while preparing
  its new generation. There is no post-update pip reinstall. hermes plugins update prepares
  active replacements before swapping their code and dependency generation together.
• Requirement hygiene — malformed PEP 508 requirements are refused. Environment markers
  remain intact for the target interpreter to evaluate. hermes-agent self-dependencies are
  omitted because the checkout supplies Hermes. Direct-URL requirements are not managed;
  use a plugin-owned external runtime for them.
• --no-deps downloads a new plugin without dependency consent and leaves it disabled,
  even with --enable. It cannot bypass PM admission when replacing an active plugin.
• --yes-deps answers the dependency question up front, so a headless install (CI, SSH
  automation, a container entrypoint) prepares the declared dependencies instead of being refused.
  It is mutually exclusive with --no-deps.
• python_runtime: external keeps a sidecar's dependencies out of the shared union.
  Hermes does not install that Python runtime or modify its declaration.
• Nothing to load is an error — hermes plugins validate rejects plugin.yaml without
  __init__.py, desktop/plugin.js, or plugin.json beside it. Pip-layout packages need
  a directory-plugin wrapper.
• security.allow_lazy_installs: false blocks on-demand acquisition. Explicit dependency
  consent and explicit enablement authorize PM preparation; discovery never installs.

HERMES_HOME/plugins/ survives hermes update and Desktop updates: the updater only rebuilds the
venv and the checkout, never the home directory.

Dependency security policy Copy Section

Hermes checks the age of its own dependencies when it locks them: the checkout's
[tool.uv] exclude-newer = "3 days" keeps any release younger than three days out of uv.lock,
so a hijacked upload has time to be caught upstream before it reaches users. Users install from
that vetted lock; their machines never re-check dates. The check does not apply to your
plugin's dependencies. When Hermes resolves your plugin into its environment, Hermes's exact
pins stay put, other packages Hermes uses may move within the ranges Hermes declares, and
everything else follows your requirements, so a plugin can floor on a release published
yesterday and install today. The plugin's author, not Hermes, is responsible for what that pulls
in. A plugin that requires a different version of a package Hermes pins exactly fails to install
until Hermes's pin moves.

Set your own policy and hold yourself to it. Strongly recommended:

• Upper bounds on every dependency — >=floor,<next_major for stable packages,
  >=0.29,<0.32 for pre-1.0 ones. A bare >=X.Y adopts every future release unreviewed.
• Floor on the oldest API-compatible version, not the release of the week. A floor on a
  fresh wheel forces every installer onto it the day it appears; >=old,!=broken,<next keeps the
  wide range and skips the one bad release.
• Adopt a release-age check of your own: wait a few days before floors move to a new
  release, and resolve with uv --exclude-newer "3 days" (or UV_EXCLUDE_NEWER) in your own CI so
  the lock you test is the one users get.
• Pin your lock, review your bumps. Treat a dependency bump as a code change: read the
  upstream diff, then re-pin.

The plugin catalog review reads your dependency list at the pinned SHA (plugin.yaml or
pyproject.toml) and flags bare floors and missing bounds; an entry is not held for a floor that
is merely recent.

Step 3: Write the tool schemas Copy Chapter

Create schemas.py — this is what the LLM reads to decide when to call your tools:

/* Detailed source-code truncated for AI context efficiency. */

Why schemas matter: The description field is how the LLM decides when to use your tool. Be specific about what it does and when to use it. The parameters define what arguments the LLM passes.

Step 4: Write the tool handlers Copy Chapter

Create tools.py — this is the code that actually executes when the LLM calls your tools:

/* Detailed source-code truncated for AI context efficiency. */

Key rules for handlers:

1. Signature: def my_handler(args: dict, **kwargs) -> str
2. Return: Always a JSON string. Success and errors alike.
3. Never raise: Catch all exceptions, return error JSON instead.
4. Accept **kwargs: Hermes injects context keywords (task_id, session_id, user_task,
   parent_agent, ...) and only forwards the ones your signature names, so def handler(args)
   works; **kwargs is how you opt into the full, additively growing context.

Step 5: Write the registration Copy Chapter

Create __init__.py — this wires schemas to handlers:

"""Calculator plugin — registration."""

import logging

from . import schemas, tools

logger = logging.getLogger(__name__)

# Track tool usage via hooks
_call_log = []

def _on_post_tool_call(tool_name, args, result, task_id, **kwargs):
    """Hook: runs after every tool call (not just ours)."""
    _call_log.append({"tool": tool_name, "session": task_id})
    if len(_call_log) > 100:
        _call_log.pop(0)
    logger.debug("Tool called: %s (session %s)", tool_name, task_id)


def register(ctx):
    """Wire schemas to handlers and register hooks."""
    ctx.register_tool(name="calculate",    toolset="calculator",
                      schema=schemas.CALCULATE,    handler=tools.calculate)
    ctx.register_tool(name="unit_convert", toolset="calculator",
                      schema=schemas.UNIT_CONVERT, handler=tools.unit_convert)

    # This hook fires for ALL tool calls, not just ours
    ctx.register_hook("post_tool_call", _on_post_tool_call)

What register() does:

• Called exactly once at startup
• ctx.register_tool() puts your tool in the registry — the model sees it immediately
• ctx.register_hook() subscribes to lifecycle events
• ctx.register_cli_command() registers a CLI subcommand (e.g. hermes my-plugin <subcommand>)
• ctx.register_command() registers an in-session slash command (e.g. /myplugin <args> inside CLI / gateway chat) — see Register slash commands below
• ctx.dispatch_tool(name, arguments) — call any other tool (built-in or from another plugin) with the parent agent's context (approvals, credentials, task_id) wired up automatically. Useful from slash-command handlers that need to invoke terminal, read_file, or any other tool as if the model had called it directly.
• ctx.get_config() / ctx.set_config() access only this plugin's settings namespace; ctx.state stores plugin-owned runtime data under the active profile.
• If this function crashes, the plugin is disabled but Hermes continues fine

dispatch_tool example — a slash command that runs a tool:

def handle_scan(ctx, raw_args: str):
    """Implement /scan by invoking the terminal tool through the registry."""
    result = ctx.dispatch_tool("terminal", {"command": f"find . -name '{raw_args}'"})
    return result  # returned to the caller's chat UI

def register(ctx):
    # Handlers receive a single raw_args string; close over ctx via a lambda.
    ctx.register_command(
        "scan",
        lambda raw: handle_scan(ctx, raw),
        description="Find files matching a glob",
    )

The dispatched tool goes through the normal approval, redaction, and budget pipelines — it's a real tool invocation, not a shortcut around them.

Store settings and runtime state Copy Section

Use plugin-relative config keys for user-visible behavior. Hermes resolves them
under plugins.entries..settings and rejects global, cross-plugin,
and traversal paths:

def register(ctx):
    endpoint = ctx.get_config("endpoint", default="https://example.invalid")
    retries = ctx.get_config("retry.attempts", default=3)

    ctx.set_config("endpoint", endpoint)
    ctx.set_config("retry.attempts", retries)

Use ctx.state for plugin-owned cursors, caches, and deduplication data rather
than placing runtime bookkeeping in config.yaml:

def register(ctx):
    cursor = ctx.state.get("cursor", default={"page": 0})
    ctx.state.set("cursor", {"page": cursor["page"] + 1})

State is profile-scoped, atomically replaced, safe across concurrent writers,
and limited to 10 MiB per plugin. Portable packages share the same directory as
their PLUGIN_DATA; native plugins receive a collision-resistant,
Windows-safe namespace. Malformed existing state is reported and preserved.

Config and state have different owners: settings are user-visible behavior in
config.yaml, while state is plugin-owned runtime data under
<HERMES_HOME>/plugin-data/. Neither API exposes another plugin's namespace.

Settings form in the Desktop Copy Section

Every key you declare in the manifest's config_schema renders as a row on the
plugin's own page under the Desktop app's Settings → Plugins (the gear on the
plugin's Capabilities → Plugins row opens it). No
Desktop code is needed: the backend's plugins.manage list returns the schema
plus each key's current value, and saving writes through the same writer as
ctx.set_config(), so plugins.entries..settings.<key> is what your plugin
reads back. The form is table-driven by type:

Every entry also accepts label (or title; without one the key is shown in
sentence case, maps_api_key → "Maps API key"), description (help text under
the label), default and required (marks the row Required).

config_schema:
  api_url: {type: str, default: "https://api.example.com", label: "API URL", description: "Service endpoint"}
  retries: {type: int, default: 3}
  mode: {type: str, choices: [fast, careful], default: fast}
  api_key: {type: secret, env: MY_PLUGIN_API_KEY, description: "Personal access token"}

Secrets never touch config.yaml. A secret field carries only the .env
name and whether a value is set; the Desktop stores the value through the same
credential route as provider API keys (PUT /api/env), and your plugin reads it
with get_secret("MY_PLUGIN_API_KEY") from agent.secret_scope — exactly like a requires_env entry.
Never read .env, auth.json or another tool's credential files yourself (catalog rule 11).
The plugins.manage settings action refuses secret keys and any value whose type
or choices disagree with the schema.

Portable packages (plugin.json) declare the same schema under the Hermes
vendor namespace, since Agent Plugins v1 rejects unknown top-level fields:

{
  "extensions": {
    "com.nousresearch.hermes": {
      "config_schema": {
        "api_key": { "type": "secret", "env": "MY_PLUGIN_API_KEY" },
        "show_chip": { "type": "bool", "default": true, "label": "Show the status-bar chip" }
      }
    }
  }
}

A secret whose env names a variable your mcp.json passes through
("env": { "MY_PLUGIN_API_KEY": "${MY_PLUGIN_API_KEY}" }) reaches the MCP server
right away: after a save, Hermes reconnects the plugin's servers whose resolved
launch inputs changed (a new key does, a toggle does not), so the form is also
where users set the server's key.

React to a save without polling. Every save broadcasts
plugin..settings.changed (payload { written: [...keys] }; a secret-only
save sends an empty list), so a Desktop half re-reads its preferences at once:
ctx.onEvent('plugin.my-plugin.settings.changed', reload). Read the values from
your own plugin_api.py with load_config_readonly() from hermes_cli.config
(plugins.entries..settings), falling back to the schema defaults.

Step 6: Test it Copy Chapter

Start Hermes:

hermes

You should see calculator: calculate, unit_convert in the banner's tool list.

Try these prompts:

What's 2 to the power of 16?
Convert 100 fahrenheit to celsius
What's the square root of 2 times pi?
How many gigabytes is 1.5 terabytes?

Check plugin status:

/plugins

Output:

Plugins (1):
  ✓ calculator v1.0.0 (2 tools, 1 hooks)

Debugging plugin discovery Copy Section

If your plugin doesn't show up — or shows up but isn't loading — set HERMES_PLUGINS_DEBUG=1 to get verbose discovery logs on stderr:

HERMES_PLUGINS_DEBUG=1 hermes plugins list

You'll see, for every plugin source (bundled, user, project, entry-points):

• which directories were scanned and how many manifests each yielded
• per manifest: resolved key, name, kind, source, on-disk path
• skip reasons: disabled via config, not enabled in config, exclusive plugin, no plugin.yaml, depth cap reached
• on load: the plugin being imported, plus a one-line summary of what register(ctx) registered (tools, hooks, slash commands, CLI commands)
• on parse failure: a full traceback for the exception (YAML scanner errors, etc.)
• on register() failure: a full traceback pointing at the line in your __init__.py that raised

The same logs are always written to ~/.hermes/logs/agent.log at WARNING level (failures only) and DEBUG level (everything) when the env var is set. So if you can't run with the env var (e.g. from inside the gateway), tail the log file instead:

hermes logs --level WARNING | grep -i plugin

Common reasons a plugin doesn't appear:

• Not enabled in config — plugins are opt-in. Run hermes plugins enable <name> (the name comes from the plugins list output, which can be <category>/ for nested layouts).
• Wrong directory layout: Native packages use ~/.hermes/plugins//plugin.yaml (flat) or one category level. Portable packages use root plugin.json in the same locations. Anything deeper is ignored.
• Missing __init__.py: Native packages need both plugin.yaml and __init__.py with a register(ctx) function. Portable packages do not import Python and do not require __init__.py.
• Wrong kind — gateway adapters need kind: platform in their manifest. Memory providers are auto-detected as kind: exclusive and routed through the memory.provider config instead of plugins.enabled.

Your plugin's final structure Copy Chapter

~/.hermes/plugins/calculator/
├── plugin.yaml      # "I'm calculator, I provide tools and hooks"
├── __init__.py      # Wiring: schemas → handlers, register hooks
├── schemas.py       # What the LLM reads (descriptions + parameter specs)
└── tools.py         # What runs (calculate, unit_convert functions)

Four files, clear separation:

• Manifest declares what the plugin is
• Schemas describe tools for the LLM
• Handlers implement the actual logic
• Registration connects everything

What else can plugins do? Copy Chapter

Ship data files Copy Section

Put any files in your plugin directory and read them at import time:

# In tools.py or __init__.py
from pathlib import Path
from ruamel.yaml import YAML

_PLUGIN_DIR = Path(__file__).parent
_DATA_FILE = _PLUGIN_DIR / "data" / "languages.yaml"

with open(_DATA_FILE) as f:
    _DATA = YAML(typ="safe").load(f)

That's for files you ship. State you write is different — see the next
section.

Store durable state Copy Section

Never write runtime state into your plugin directory: that's the install
tree, and hermes plugins update / remove git-pull or delete it — your
users' data dies with it. The sanctioned home is the per-plugin data root,
which survives both and follows the active profile:

from plugins.plugin_storage import plugin_data_dir, plugin_db

# <hermes home>/plugin-data/<name>/ — created on first use
state_file = plugin_data_dir("my-plugin") / "state.json"

# Or a SQLite database at <data dir>/data.db (WAL mode, thread-friendly)
conn = plugin_db("my-plugin")
conn.execute("CREATE TABLE IF NOT EXISTS runs (id TEXT PRIMARY KEY)")

One directory per plugin means every plugin's data is inspectable in one
predictable place. Secrets don't belong here — credential reads go through
the standard .env / secret-scope path like everywhere else.

Bundle skills Copy Section

Plugins can ship skill files that the agent loads via skill_view("plugin:skill"). Register them in your __init__.py:

~/.hermes/plugins/my-plugin/
├── __init__.py
├── plugin.yaml
└── skills/
    ├── my-workflow/
    │   └── SKILL.md
    └── my-checklist/
        └── SKILL.md

from pathlib import Path

def register(ctx):
    skills_dir = Path(__file__).parent / "skills"
    for child in sorted(skills_dir.iterdir()):
        skill_md = child / "SKILL.md"
        if child.is_dir() and skill_md.exists():
            ctx.register_skill(child.name, skill_md)

The agent can now load your skills with their namespaced name:

skill_view("my-plugin:my-workflow")   # → plugin's version
skill_view("my-workflow")              # → built-in version (unchanged)

Key properties:

• Plugin skills are read-only — they don't enter ~/.hermes/skills/ and can't be edited via skill_manage.
• Plugin skills are not listed in the system prompt's <available_skills> index — they're opt-in explicit loads.
• Bare skill names are unaffected — the namespace prevents collisions with built-in skills.
• When the agent loads a plugin skill, a bundle context banner is prepended listing sibling skills from the same plugin.

:::tip Legacy pattern
The old shutil.copy2 pattern (copying a skill into ~/.hermes/skills/) still works but creates name collision risk with built-in skills. Prefer ctx.register_skill() for new plugins.
:::

Read the skill catalog Copy Section

A plugin that shows which skills the agent can see (a catalog view, "open this skill", drift checks
against the installed copy) should call the same helpers the skills_list and skill_view tools use,
not walk the skill directories itself. These names are public and covered by the compatibility
contract:

from tools.skills_tool import find_all_skills, locate_skill, skill_lookup_path_error, skill_search_dirs, sort_skills

def list_skills():
    return sort_skills(find_all_skills())

def open_skill(name):
    if err := skill_lookup_path_error(name):
        return err
    roots, _active = skill_search_dirs()
    error, _skill_dir, skill_md = locate_skill(name, None, roots)
    return error or skill_md.read_text(encoding="utf-8-sig", errors="replace")

Plugin-registered skills (ctx.register_skill) are not on disk under these roots; find_all_skills()
returns the on-disk catalog only.

Ship a language pack Copy Section

A plugin can add a UI language or override the wording of an existing one for every surface at once —
Python (agent.i18n.t(): approval prompts, gateway replies, tool verbs, tips), the hermes --tui
interface and the Desktop app. Declare provides_locales and ship the YAML; no Python is needed:

~/.hermes/plugins/hermes-lang-pl/
├── plugin.yaml
└── locales/
    ├── pl.yaml            # core (Python) strings — same key tree as the bundled locales/en.yaml
    ├── pl.tui.yaml        # optional: TUI strings (keys in locales/_keys.tui.json)
    └── pl.desktop.yaml    # optional: Desktop strings (keys in locales/_keys.desktop.json)

name: hermes-lang-pl
version: 1.0.0
description: Polish language pack
provides_locales:
  - id: pl              # lowercase BCP-47-style id: pl, pt-br, zh-hant
    endonym: Polski     # what language switchers show
    rtl: false

When provides_locales is declared the loader calls ctx.register_locale_dir(/locales) before
register() (a manifest-only pack with no __init__.py loads like a manifest-only Desktop plugin).
Catalogs are layered and partial: pack → user overlay (<HERMES_HOME>/locales/) → bundled →
English → key; a pack only needs the keys it changes, and the last pack loaded wins per key.
Core values keep English's named {placeholders}; TUI/Desktop entries whose English value is a
function are written as strings with positional {0}, {1} placeholders.

Plugins with code can register programmatically — the handles are PluginRegistrations, so unloading
the plugin removes the layer, and registration never changes display.language:

def register(ctx):
    here = Path(__file__).parent
    ctx.register_locale("pl", here / "locales" / "pl.yaml", endonym="Polski")        # YAML path
    ctx.register_locale("pl", {"approval": {"denied": "      ✗ Odrzucono"}})          # mapping, nested or flat
    ctx.register_locale("pl", here / "locales" / "pl.tui.yaml", surface="tui")       # core | tui | desktop
    ctx.register_locale_dir(here / "locales")                                         # every <lang>[.surface].yaml

hermes plugins validate checks each declared id has a parseable, text-only locales/.yaml
(a non-text leaf is an error) and warns with the names of keys absent from the English catalog of
that surface. Renderers fetch the pack layer through the i18n.languages / i18n.catalog RPCs.
User-facing guide: Language Packs.

Gate on environment variables Copy Section

If your plugin needs an API key:

# plugin.yaml — simple format (backwards-compatible)
requires_env:
  - WEATHER_API_KEY

If WEATHER_API_KEY isn't set, the plugin is disabled with a clear message. No crash, no error in the agent — just "Plugin weather disabled (missing: WEATHER_API_KEY)".

When users run hermes plugins install, they're prompted interactively for any missing requires_env variables. Values are saved to .env automatically.

For a better install experience, use the rich format with descriptions and signup URLs:

# plugin.yaml — rich format
requires_env:
  - name: WEATHER_API_KEY
    description: "API key for OpenWeather"
    url: "https://openweathermap.org/api"
    secret: true

Both formats can be mixed in the same list. Already-set variables are skipped silently.

Lazy-install optional Python dependencies Copy Section

For an SDK covered by a Hermes project extra, use pm.ensure_import at the
operation that needs it. Use pm.available for a read-only availability check.
Do not install dependencies from a frequently polled check_fn.

This example requests the existing bedrock extra:

from pm import InstallError, ensure_import

def my_tool_handler(args, **kwargs):
    try:
        ensure_import("bedrock")
    except InstallError as exc:
        return {"error": str(exc)}

    import boto3
    # Use the SDK here.

The argument is a pyproject.toml extra name. It is not an arbitrary package
specification or a plugin-qualified key. The old LAZY_DEPS registry and
FeatureUnavailable exception no longer exist.

If a new environment is selected, the helper can report a required restart.
Return that error instead of importing from a second environment inside the
running process. Already available dependencies need no installation, even
when security.allow_lazy_installs is false.

For a directory plugin's own Python dependencies, declare dependencies under
[project] in its pyproject.toml. Without an authored project file, PM combines
legacy pip_dependencies and python_dependencies lists from plugin.yaml or
plugin.yml. Old PM-generated project files do not override these lists.
Consent, workspace membership, and currency checks use the same declaration.
PM prepares their dependencies together with core requirements before enabling
the plugin. The generated workspace does not rewrite the plugin directory or
the shipped lockfile. Dependency conflicts refuse admission and preserve the
previous selection. PM does not automatically disable other plugins.

Dependencies installed manually with pip are not durable PM declarations.
A later environment replacement need not retain them. Wrapper plugins whose
Python runtimes remain outside PM can use the
memory-provider survival contract.
See Package management for the
runtime layout and lazy-install policy.

Thread-safe lazy singletons Copy Section

Plugins often cache an expensive object — an SDK client, an HTTP session, a connection pool — in a module-level variable built on first use:

_client = None

def get_client():
    global _client
    if _client is not None:
        return _client
    _client = ExpensiveClient(...)   # ← TOCTOU race
    return _client

This is a footgun. Hermes runs multiple threads in one process (delegated tool calls, background workers, the self-improvement fork), so two threads can hit get_client() before _client is set, both pass the is not None check, both run the expensive build, and the second write clobbers the first — leaking whatever resource the loser opened (connection, file handle, background thread).

Don't hand-roll the lock. Use the helpers in plugins/plugin_utils.py:

from plugins.plugin_utils import lazy_singleton, SingletonSlot

# Zero-arg accessor → decorate it:
@lazy_singleton
def get_client():
    return ExpensiveClient(load_config())   # runs exactly once

client = get_client()    # safe across threads
get_client.reset()       # drop the instance (tests / teardown)


# Accessor that takes a build argument → use a slot:
_slot: SingletonSlot = SingletonSlot()

def get_client(config=None):
    return _slot.get(lambda: ExpensiveClient(resolve(config)))

def reset_client():
    _slot.reset()

Both serialize concurrent first calls with double-checked locking and run the factory at most once. If the factory raises, nothing is cached and the next call retries. The Honcho memory plugin (client.py) is the reference consumer.

Rule of thumb: any time you write global _something followed by a is None check and a build, reach for one of these instead.

Conditional tool availability Copy Section

For tools that depend on optional libraries:

ctx.register_tool(
    name="my_tool",
    schema={...},
    handler=my_handler,
    check_fn=lambda: _has_optional_lib(),  # False = tool hidden from model
)

Overriding a built-in tool Copy Section

To replace a built-in tool with your own implementation (e.g. swap the
default browser tool for a headed-Chrome CDP backend, or replace
web_search with a custom corporate index), pass override=True:

def register(ctx):
    ctx.register_tool(
        name="browser_navigate",             # same name as the built-in
        toolset="plugin_my_browser",         # your own toolset namespace
        schema={...},
        handler=my_custom_navigate,
        override=True,                       # explicit opt-in
    )

Without override=True, the registry rejects any registration that would
shadow an existing tool from a different toolset — this prevents
accidental overwrites. Overriding a built-in tool additionally
requires the operator to opt in via
plugins.entries..allow_tool_override: true in config.yaml;
without that gate, register_tool(override=True) raises
PluginToolOverrideError. The override is logged so it's
auditable in ~/.hermes/logs/agent.log. Plugins load after built-in
tools, so the registration order is correct: your handler replaces the
built-in one.

Non-bundled plugins also need an operator grant. For any plugin that
does not ship with Hermes core (user, project, or pip source),
override=True against an existing built-in tool additionally requires a
per-plugin opt-in in config.yaml:

plugins:
  entries:
    my-plugin:                    # the plugin's registry key from `hermes plugins list`
      allow_tool_override: true

Without the grant, ctx.register_tool(..., override=True) raises
PluginToolOverrideError; since register() exceptions are caught by the
loader, the plugin is disabled and Hermes continues. The gate exists
because an enabled plugin that silently replaces a privileged built-in
like shell_exec or write_file could intercept everything the model
routes through it. Bundled plugins are exempt: an override there is a
maintainer decision. If config cannot be loaded, the gate fails closed.

You normally never edit this key by hand. hermes plugins enable <name>
asks whether to grant the capability only when the plugin's manifest
declares it under capabilities: (the consent screen, defaulting to no);
a plugin that declares no capabilities is enabled without any grant
prompt. The --allow-tool-override / --no-allow-tool-override flags set
or revoke the grant explicitly in either case, for scripted installs or
for pre-authorizing a plugin that has not adopted the manifest block.
The same grant also gates deregister(): without it, a plugin cannot
remove a tool it does not own (which would otherwise be a way around the
override check).

Register multiple hooks Copy Section

def register(ctx):
    ctx.register_hook("pre_tool_call", before_any_tool)
    ctx.register_hook("post_tool_call", after_any_tool)
    ctx.register_hook("pre_llm_call", inject_memory)
    ctx.register_hook("on_session_start", on_new_session)
    ctx.register_hook("on_session_end", on_session_end)

Hook reference Copy Section

Each hook is documented in full on the Event Hooks reference — callback signatures, parameter tables, exactly when each fires, and examples. Here's the summary:

Most hooks are fire-and-forget observers — their return values are ignored. The exceptions are pre_llm_call, which can inject context into the conversation, and pre_tool_call, which can return a block/approve directive.

All callbacks should accept **kwargs for forward compatibility. If a hook callback crashes, it's logged and skipped. Other hooks and the agent continue normally.

The kanban lifecycle hooks fire after the board DB change commits, so a callback always sees durable state and can never hold the SQLite write lock. Because kanban workers run as separate hermes -p chat -q subprocesses, kanban_task_claimed fires in the dispatcher process while kanban_task_completed / kanban_task_blocked fire in the worker process — hook in the dispatcher to observe every transition centrally, or in the worker for per-task in-session context.

The API request hooks are observers for the raw provider request, one level below the per-turn pre_llm_call / post_llm_call pair: a single turn that calls tools makes several API requests, and these hooks fire around each one. They exist for observability plugins (tracing, cost accounting, latency dashboards). The request and response kwargs are sanitized, size-capped JSON views of the provider payload (sensitive keys redacted, long strings truncated, SDK objects normalized), and usage is a plain token-summary dict. Every payload carries the correlation fields turn_id, api_request_id, task_id, session_id, and api_call_count, so a plugin can stitch requests, tool calls, and turns together. api_request_error fires when a provider call raises and adds status_code, retry_count / max_retries, retryable, reason, and an error dict with type and message.

`pre_llm_call` context injection Copy Section

This is the only hook whose return value matters. When a pre_llm_call callback returns a dict with a "context" key (or a plain string), Hermes injects that text into the current turn's user message. This is the mechanism for memory plugins, RAG integrations, guardrails, and any plugin that needs to provide the model with additional context.

Return format

# Dict with context key
return {"context": "Recalled memories:\n- User prefers dark mode\n- Last project: hermes-agent"}

# Plain string (equivalent to the dict form above)
return "Recalled memories:\n- User prefers dark mode"

# Return None or don't return → no injection (observer-only)
return None

Any non-None, non-empty return with a "context" key (or a plain non-empty string) is collected and appended to the user message for the current turn.

Oversized-context spill

Per-hook context is capped at 10,000 characters by default. Anything above the cap is written to $HERMES_HOME/hook_outputs/<session_id>/.txt and replaced with a head/tail preview plus the saved path. The model can read the full content via read_file or terminal if it genuinely needs it. This keeps a runaway plugin from inflating every subsequent turn's prompt and blowing out the prompt cache prefix. Tune in config.yaml:

hooks:
  output_spill:
    enabled: true          # default: true
    max_chars: 10000       # default; set higher to opt out of spilling
    preview_head: 500      # chars shown at the top of the preview
    preview_tail: 500      # chars shown at the bottom of the preview
    # directory: null      # default: $HERMES_HOME/hook_outputs

How injection works

Injected context is appended to the user message, not the system prompt. This is a deliberate design choice:

• Prompt cache preservation — the system prompt stays identical across turns. Anthropic and OpenRouter cache the system prompt prefix, so keeping it stable saves 75%+ on input tokens in multi-turn conversations. If plugins modified the system prompt, every turn would be a cache miss.
• Ephemeral — the injection happens at API call time only. The original user message in the conversation history is never mutated, and nothing is persisted to the session database.
• The system prompt is Hermes's territory — it contains model-specific guidance, tool enforcement rules, personality instructions, and cached skill content. Plugins contribute context alongside the user's input, not by altering the agent's core instructions.

Example: Memory recall plugin

"""Memory plugin — recalls relevant context from a vector store."""

import httpx

MEMORY_API = "https://your-memory-api.example.com"

def recall_context(session_id, user_message, is_first_turn, **kwargs):
    """Called before each LLM turn. Returns recalled memories."""
    try:
        resp = httpx.post(f"{MEMORY_API}/recall", json={
            "session_id": session_id,
            "query": user_message,
        }, timeout=3)
        memories = resp.json().get("results", [])
        if not memories:
            return None  # nothing to inject

        text = "Recalled context from previous sessions:\n"
        text += "\n".join(f"- {m['text']}" for m in memories)
        return {"context": text}
    except Exception:
        return None  # fail silently, don't break the agent

def register(ctx):
    ctx.register_hook("pre_llm_call", recall_context)

Example: Guardrails plugin

"""Guardrails plugin — enforces content policies."""

POLICY = """You MUST follow these content policies for this session:
- Never generate code that accesses the filesystem outside the working directory
- Always warn before executing destructive operations
- Refuse requests involving personal data extraction"""

def inject_guardrails(**kwargs):
    """Injects policy text into every turn."""
    return {"context": POLICY}

def register(ctx):
    ctx.register_hook("pre_llm_call", inject_guardrails)

Example: Observer-only hook (no injection)

"""Analytics plugin — tracks turn metadata without injecting context."""

import logging
logger = logging.getLogger(__name__)

def log_turn(session_id, user_message, model, is_first_turn, **kwargs):
    """Fires before each LLM call. Returns None — no context injected."""
    logger.info("Turn: session=%s model=%s first=%s msg_len=%d",
                session_id, model, is_first_turn, len(user_message or ""))
    # No return → no injection

def register(ctx):
    ctx.register_hook("pre_llm_call", log_turn)

Multiple plugins returning context

When multiple plugins return context from pre_llm_call, their outputs are joined with double newlines and appended to the user message together. The order follows plugin discovery order (alphabetical by plugin directory name).

Middleware: change what happens Copy Section

Hooks observe the agent loop (with the few documented steering shapes above). Middleware changes what happens: request middleware rewrites the effective payload before anything downstream sees it, and execution middleware wraps the actual call. Register it from the same register(ctx) entry point:

def cap_find_output(tool_name, args, **kwargs):
    """Rewrite terminal find commands to cap their output."""
    command = args.get("command", "")
    if tool_name == "terminal" and command.startswith("find "):
        return {
            "args": {**args, "command": command + " | head -100"},
            "source": "my-plugin",
            "reason": "cap find output",
        }
    return None  # leave the call unchanged

def register(ctx):
    ctx.register_middleware("tool_request", cap_find_output)

The canonical list of kinds is VALID_MIDDLEWARE in hermes_cli/middleware.py:

Rules that matter in practice:

• Request middleware chains: each callback sees the payload as rewritten by earlier callbacks, while original_args / original_request always carries the pre-middleware copy. Payloads are copied between callbacks, so mutate freely.
• You can include source, reason, and name strings in the returned dict. They land in the middleware trace, which downstream observer hooks receive as the middleware_trace kwarg.
• next_call in execution middleware is single-use. Calling it twice raises, because it would re-run the provider or tool.
• A middleware callback that raises is logged and skipped; the chain continues. A downstream failure raised after your next_call propagates as itself. Middleware can never break the base runtime path.
• Middleware payloads carry middleware_schema_version (hermes.middleware.v1) alongside the observer telemetry fields.
• Unknown kinds register with a warning instead of failing, so a plugin written against a newer Hermes still loads on an older one.

Register CLI commands Copy Section

Plugins can add their own hermes subcommand tree:

def _my_command(args):
    """Handler for hermes my-plugin <subcommand>."""
    sub = getattr(args, "my_command", None)
    if sub == "status":
        print("All good!")
    elif sub == "config":
        print("Current config: ...")
    else:
        print("Usage: hermes my-plugin <status|config>")

def _setup_argparse(subparser):
    """Build the argparse tree for hermes my-plugin."""
    subs = subparser.add_subparsers(dest="my_command")
    subs.add_parser("status", help="Show plugin status")
    subs.add_parser("config", help="Show plugin config")
    subparser.set_defaults(func=_my_command)

def register(ctx):
    ctx.register_tool(...)
    ctx.register_cli_command(
        name="my-plugin",
        help="Manage my plugin",
        setup_fn=_setup_argparse,
        handler_fn=_my_command,
    )

After registration, users can run hermes my-plugin status, hermes my-plugin config, etc.

Memory provider plugins use a convention-based approach instead: add a register_cli(subparser) function to your plugin's cli.py file. The memory plugin discovery system finds it automatically — no ctx.register_cli_command() call needed. See the Memory Provider Plugin guide for details.

Active-provider gating: Memory plugin CLI commands only appear when their provider is the active memory.provider in config. If a user hasn't set up your provider, your CLI commands won't clutter the help output.

Register slash commands Copy Section

Plugins can register in-session slash commands — commands users type during a conversation (like /lcm status or /ping). These work in both CLI and gateway (Telegram, Discord, etc.).

def _handle_status(raw_args: str) -> str:
    """Handler for /mystatus — called with everything after the command name."""
    if raw_args.strip() == "help":
        return "Usage: /mystatus [help|check]"
    return "Plugin status: all systems nominal"

def register(ctx):
    ctx.register_command(
        "mystatus",
        handler=_handle_status,
        description="Show plugin status",
    )

After registration, users can type /mystatus in any session. The command appears in autocomplete, /help output, and the Telegram bot menu.

Signature: ctx.register_command(name: str, handler: Callable, description: str = "", args_hint: str = "")

Key differences from register_cli_command():

Conflict protection: If a plugin tries to register a name that conflicts with a built-in command (help, model, new, etc.), the registration is silently rejected with a log warning. Built-in commands always take precedence.

Calling-session context: a handler can learn which chat and session invoked it by declaring any of these keyword parameters (or **kwargs for all of them). Handlers that declare none keep the one-argument handler(raw_args) call, so existing plugins are unaffected:

Every surface passes them: messaging platforms, the classic CLI, the TUI and Desktop. Sync handlers run in the gateway executor and async handlers are awaited, as before.

def _handle_whoami(raw_args: str, *, session_id: str = "", platform: str = "", source=None) -> str:
    user = source.user_id if source is not None else "local user"
    return f"{user} on {platform}, session {session_id or '(none yet)'}"

def register(ctx):
    ctx.register_command("whoami", handler=_handle_whoami, description="Show the calling session")

source is transport identity, not an authorization grant: authorize from stable ids (source.user_id, source.chat_id), never from display names or the command text, and fail closed when a sensitive command gets source=None. Handler exceptions propagate; Hermes never retries the call with fewer arguments.

Where handlers run: a slash command handler runs in the gateway process that owns the session, also when the user types the command in the classic hermes chat CLI. The handler is not running in the user's terminal or directory, so:

• Return the text to show. print() writes to the gateway's stdout, and the user never sees it.
• Take the session's working directory from agent.runtime_cwd.resolve_agent_cwd(), not os.getcwd(), which is the gateway's own directory. Resolve relative paths against it.
• Read session identity with gateway.session_context.get_session_env("HERMES_SESSION_PLATFORM") and the other HERMES_SESSION_* names, not os.environ.

from agent.runtime_cwd import resolve_agent_cwd

def _handle_todo(raw_args: str) -> str:
    todo = resolve_agent_cwd() / "TODO.md"  # the session's folder, not the gateway's
    return todo.read_text() if todo.exists() else "No TODO.md here."

Dispatch tools from slash commands Copy Section

Slash command handlers that need to orchestrate tools (spawn a subagent via delegate_task, call file_edit, etc.) should use ctx.dispatch_tool() instead of reaching into framework internals. The parent-agent context (workspace hints, spinner, model inheritance) is wired up automatically.

def register(ctx):
    def _handle_deliver(raw_args: str):
        result = ctx.dispatch_tool(
            "delegate_task",
            {
                "goal": raw_args,
                "toolsets": ["terminal", "file", "web"],
            },
        )
        return result

    ctx.register_command(
        "deliver",
        handler=_handle_deliver,
        description="Delegate a goal to a subagent",
    )

Signature: ctx.dispatch_tool(name: str, args: dict, *, parent_agent=None) -> str

Runtime behavior:

• CLI mode: parent_agent is resolved from the active CLI agent so workspace hints, spinner, and model selection inherit as expected.
• Gateway mode: There is no CLI agent, so tools degrade gracefully — workspace is read from the configured terminal working directory and no spinner is shown.
• Explicit override: If the caller passes parent_agent= explicitly, it is respected and not overwritten.

This is the public, stable interface for tool dispatch from plugin commands. Plugins should not reach into ctx._cli_ref.agent or similar private state.

Act from inside a hook (profile + tools) Copy Section

ctx._cli_ref is only populated in an interactive CLI session. It is None in the gateway, in non-interactive hermes chat -q runs, and in kanban-spawned worker sessions — so any plugin logic that reaches through _cli_ref silently no-ops in exactly those contexts. Two stable, session-agnostic APIs cover what hooks actually need:

• ctx.profile_name — the active profile name (e.g. "default", or the assignee profile in a kanban worker). Derived from HERMES_HOME, so it works everywhere with no _cli_ref dependency.
• ctx.dispatch_tool(name, args) — invoke any registered tool (built-in or plugin), including the kanban_* tools, delegate_task, terminal, read_file, etc. Works from hook callbacks regardless of which process the hook fires in.

Together these let a kanban lifecycle hook observe a transition and act on the board without touching framework internals:

def register(ctx):
    def on_blocked(*, task_id, reason=None, **kw):
        # Runs in the worker process; ctx._cli_ref is None here.
        ctx.dispatch_tool("kanban_comment", {
            "task_id": task_id,
            "comment": f"[{ctx.profile_name}] auto-noted block: {reason}",
        })
    ctx.register_hook("kanban_task_blocked", on_blocked)

For running a full hermes <subcommand> (e.g. hermes kanban show), shell out with the terminal tool via ctx.dispatch_tool("terminal", {"command": "hermes kanban show ..."}) — there is no in-process slash-command bridge for headless worker sessions, and tools are the supported way to drive Hermes from a hook.

Send raw CDP commands to the agent's browser Copy Section

A plugin that must drive the agent's browser below the browser tools can get a
CDP handle pinned to a task's live supervisor connection with
SUPERVISOR_REGISTRY.capture(task_id) and send commands with
call(method, params=None, *, session_id=None, timeout=10.0). The handle
raises CapturedCDPInvalid once that connection is gone and never retargets a
newer one. Use it instead of reading or writing CDPSupervisor private
attributes, which the catalog rejects. It is trusted in-process transport only:
it performs no origin, consent or ownership checks for you. Full contract:
Browser CDP Supervisor.

Know which cron run you are in Copy Section

ctx.current_cron_execution() returns the scheduled run the current code executes inside, or None outside cron. It works from any hook that fires during the run (pre_tool_call, post_tool_call, pre_llm_call, ...) and from tool handlers. The value is a frozen CronExecution:

The scheduler sets it only after the run has won its execution claim, and clears it when the run ends. It is per-run, so two jobs or profiles firing at the same time never see each other's value. The model cannot forge it: hook arguments come from Hermes, and tool subprocesses (terminal, execute_code) run in a separate interpreter. Subagents spawned with delegate_task get None because they are not the scheduled run itself.

def register(ctx):
    def guard(*, tool_name, args, **kw):
        run = ctx.current_cron_execution()
        if tool_name == "deploy" and (run is None or run.scheduled_instant is None):
            return {"action": "block", "message": "deploy only runs from its scheduled cron job"}
    ctx.register_hook("pre_tool_call", guard)

Add Automation Blueprints Copy Section

ctx.register_automation_blueprint(key, *, title, description, schedule_template, prompt_template, category="general", slots=(), deliver_default="origin", skills=(), tags=()) adds a fill-in-the-blanks automation to the Automation Blueprints catalog. It appears next to the built-ins in /blueprint (CLI, TUI, messengers), the dashboard's Blueprints tab, and the Desktop Cron page, labelled with your plugin's name. The arguments are the fields of the built-in AutomationBlueprint (cron/blueprint_catalog.py); each slot is a dict of BlueprintSlot fields.

def register(ctx):
    ctx.register_automation_blueprint(
        "standup",
        title="Team standup digest",
        description="Every weekday, summarize what changed in a repo since yesterday.",
        category="work",
        schedule_template="{minute} {hour} * * 1-5",
        prompt_template="Summarize yesterday's commits and open PRs for {repo} as a short standup digest.",
        slots=[
            {"name": "repo", "type": "text", "label": "Which repo?", "default": "acme/app"},
            {"name": "time", "type": "time", "label": "What time?", "default": "09:15"},
            {"name": "deliver", "type": "enum", "label": "Where to deliver?", "default": "origin",
             "options": ["origin", "local"], "strict": False},
        ],
        tags=["work", "daily"],
    )

Users then run /blueprint teamtools:standup (or just /blueprint standup) or pick it in the Desktop/dashboard form.

• Keys are namespaced. The catalog key is :<key> (teamtools:standup), so a plugin can never replace a built-in or another plugin's blueprint. Pass the bare key; a key containing : is rejected.
• Slots and templates. Slot type is time (HH:MM), enum, weekdays, or text. prompt_template may use any slot as {name}. schedule_template may use slot names plus {minute}/{hour} (from a slot named time) and {dow} (from a recurrence/day slot, else *). A slot named deliver gets the profile's real delivery targets in the Desktop and dashboard forms.
• Validated at registration. An unknown placeholder, bad slot type, duplicate key, or schedule that does not parse logs a warning and skips that blueprint; the rest of your plugin still loads. When every slot has a default, Hermes fills the blueprint once at load, so a broken template fails then instead of on the user's first Schedule it.
• Per profile. Plugins load per profile, so the blueprint is listed only in profiles where your plugin is enabled.
• Jobs outlive the plugin. Scheduling a blueprint creates an ordinary cron job with the prompt and schedule already filled in. Disabling or uninstalling the plugin removes the blueprint from the catalog but leaves those jobs running. If a job's skills name a skill your plugin bundles, the job skips that skill (and logs it) while the plugin is disabled.

This needs no manifest capability. It also works under plugin host isolation, because slots are plain dicts.

Handle Slack Block Kit button clicks Copy Section

Plugins that post Block Kit messages with interactive elements (buttons, overflow menus, datepickers, etc.) can register the click handlers directly with the Slack adapter — no monkey-patching of slack_bolt.AsyncApp required.

def register(ctx):
    async def _on_approve(ack, body, action):
        # ack within 3 seconds — slack_bolt requirement.
        await ack()
        # body["channel"]["id"], body["user"]["id"], body["message"]["ts"]
        # action["action_id"], action["value"]
        sweep_id = (action.get("value") or "").split("|", 1)[-1]
        # ...do the deterministic work, then post a follow-up.

    ctx.register_slack_action_handler("inbox_sweep_approve", _on_approve)

Signature: ctx.register_slack_action_handler(action_id, callback) -> None

Runtime behavior:

• The handler is queued at plugin-load time and wired into the adapter's slack_bolt.AsyncApp when the Slack platform connects.
• Each callback is wrapped defensively: if your handler raises, the gateway logs the error and best-effort-acks the click so Slack stops retrying.
• Standard slack_bolt rules apply — await ack() within 3 seconds, then do longer work.
• For multi-workspace deployments the handler fires for clicks from any connected workspace; use body["team"]["id"] if you need to scope behaviour.

This is the public way for plugins to participate in Slack interactivity. Older plugins may patch SlackAdapter.connect; prefer this API instead. For the full slack_bolt surface (events, shortcuts, commands — not just Block Kit actions), use the generic register_platform_handler("slack", ...) below.

Register native platform handlers (any platform) Copy Section

Plugins that need to receive platform events the core adapter doesn't route — extra update types, native button callbacks, reaction/member events, webhook routes — can register a handler factory that the platform's adapter invokes at connect time. This works on every gateway platform.

def register(ctx):
    def _wire(native, adapter):
        # native: the platform's client/app object (see table below)
        # adapter: the platform adapter instance (treat as read-only)
        # Import platform SDKs HERE so register() works without them.
        ...

    ctx.register_platform_handler("discord", _wire)

Signature: ctx.register_platform_handler(platform, factory) -> None

What native is, per platform:

Runtime behavior:

• Factories are queued at plugin-load time and invoked when the platform connects — for platforms where dispatch order matters (Telegram, Slack, Teams, aiohttp routers) they run before the core handlers register, so scoped plugin handlers take precedence and everything else falls through.
• Always scope handlers you add to first-match dispatch tables. On Telegram, use CallbackQueryHandler(..., pattern=r"^myplugin:") — an unscoped handler would swallow the core button flows (exec approvals, model picker, clarify prompts).
• Each factory is isolated: if it raises, the error is logged and the platform still connects.
• Import platform SDKs inside the factory body, not at module level — register() must work when the SDK isn't installed.
• One plugin can register factories for several platforms; each fires only when its platform connects.

Telegram alias: ctx.register_telegram_handler(factory) is a back-compat alias for ctx.register_platform_handler("telegram", factory).

Example — Telegram, pattern-scoped inline buttons:

def register(ctx):
    def _wire(application, adapter):
        from telegram.ext import CallbackQueryHandler

        async def _on_button(update, context):
            query = update.callback_query
            await query.answer()
            # ...handle "myplugin:*" callbacks

        application.add_handler(
            CallbackQueryHandler(_on_button, pattern=r"^myplugin:")
        )

    ctx.register_platform_handler("telegram", _wire)

Example — Discord, reaction events:

def register(ctx):
    def _wire(bot, adapter):
        async def on_raw_reaction_add(payload):
            ...  # e.g. reaction-based voting / moderation

        bot.add_listener(on_raw_reaction_add, "on_raw_reaction_add")

    ctx.register_platform_handler("discord", _wire)

Mid-run plugin loading: what activates now vs next session Copy Section

A plugin can load while the gateway (or the TUI/Desktop server) is already running: hermes plugins install/enable, a Desktop or dashboard install, a catalog re-pin, or a tool-triggered force
re-discovery. Every one of those paths runs a real forced rescan (discover_plugins(force=True)) and
PluginManager.on_plugin_loaded(callback) fires from inside it with one summary per newly loaded plugin
(hermes_cli/plugins_activation.py):

{"name": "late-mcp", "key": "late-mcp",
 "activated_now": {"gateway_commands": ["late"], "callbacks": ["telegram"]},
 "deferred": {"tools": ["late_tool"], "prompt": ["late.section"], "mcp_servers": ["worker"]}}

• Active immediately — gateway slash commands, gateway transform hooks / other hooks, and platform
  callbacks: the gateway runner subscribes at boot and calls every live adapter's idempotent
  rewire_plugin_handlers(), so a register_platform_handler factory (or Slack action handler) registered
  by a late plugin is wired without a restart. Re-wiring is deduped per native client by (plugin, factory qualname); on Telegram the late handlers are hoisted ahead of core's catch-all filters.COMMAND /
  CallbackQueryHandler (PTB dispatches the first match per group), exactly as they would sit at connect.
• Deferred — tools and prompt sections apply from the next session (the running session's
  prompt/tool schema is cache-stable, same rule as /skills install); mcp_servers (the plugin's
  mcp.json servers, by their mcp.json names) connect on mcp.reload or the next session.
• There is no un-wire: disabling a plugin mid-run keeps its already-wired handlers until the gateway
  restarts, and the surfaces say so.

Install surfaces report exactly this split: hermes plugins install/enable prints it after nudging the running
gateway (reload-plugins control-socket verb), plugins.manage install/toggle/update returns activation +
gateway_reloaded (restart_required is true only when no gateway answered).

:::tip
This guide covers general plugins (tools, hooks, slash commands, CLI commands). The sections below sketch the authoring pattern for each specialized plugin type; each links to its full guide for field reference and examples.
:::

Specialized plugin types Copy Chapter

Hermes has five specialized plugin types beyond the general surface. Each ships as a directory under plugins/<category>/<name>/ (bundled) or ~/.hermes/plugins/<category>/<name>/ (user). The contract differs by category — pick the one you need, then read its full guide.

Model provider plugins — add an LLM backend Copy Section

Drop a profile into plugins/model-providers/<name>/:

# plugins/model-providers/acme/__init__.py
from providers import register_provider
from providers.base import ProviderProfile

register_provider(ProviderProfile(
    name="acme",
    aliases=("acme-inference",),
    display_name="Acme Inference",
    env_vars=("ACME_API_KEY", "ACME_BASE_URL"),
    base_url="https://api.acme.example.com/v1",
    auth_type="api_key",
    default_aux_model="acme-small-fast",
    fallback_models=("acme-large-v3", "acme-medium-v3"),
))

# plugins/model-providers/acme/plugin.yaml
name: acme-provider
kind: model-provider
version: 1.0.0
description: Acme Inference — OpenAI-compatible direct API

Lazy-discovered the first time anything calls get_provider_profile() or list_providers() — auth.py, config.py, doctor.py, models.py, runtime_provider.py, and the chat_completions transport auto-wire to it. User plugins override bundled ones by name.

Full guide: Model Provider Plugins — field reference, overridable hooks (prepare_messages, build_extra_body, build_api_kwargs_extras, fetch_models), api_mode selection, auth types, testing.

Platform plugins — add a gateway channel Copy Section

Drop an adapter into plugins/platforms/<name>/:

# plugins/platforms/myplatform/adapter.py
from gateway.platforms.base import BasePlatformAdapter

class MyPlatformAdapter(BasePlatformAdapter):
    async def connect(self): ...
    async def send(self, chat_id, text): ...
    async def disconnect(self): ...

def check_requirements():
    from agent.secret_scope import get_secret
    return bool(get_secret("MYPLATFORM_TOKEN"))

def _env_enablement():
    from agent.secret_scope import get_secret
    tok = (get_secret("MYPLATFORM_TOKEN") or "").strip()
    if not tok:
        return None
    return {"token": tok}

def register(ctx):
    ctx.register_platform(
        name="myplatform",
        label="MyPlatform",
        adapter_factory=lambda cfg: MyPlatformAdapter(cfg),
        check_fn=check_requirements,
        required_env=["MYPLATFORM_TOKEN"],
        # Auto-populate PlatformConfig.extra from env so env-only setups
        # show up in `hermes gateway status` without SDK instantiation.
        env_enablement_fn=_env_enablement,
        # Opt in to cron delivery: `deliver=myplatform` routes to this var.
        cron_deliver_env_var="MYPLATFORM_HOME_CHANNEL",
        emoji="💬",
        platform_hint="You are chatting via MyPlatform. Keep responses concise.",
    )

# plugins/platforms/myplatform/plugin.yaml
name: myplatform-platform
label: MyPlatform
kind: platform
version: 1.0.0
description: MyPlatform gateway adapter
requires_env:
  - name: MYPLATFORM_TOKEN
    description: "Bot token from the MyPlatform console"
    password: true
optional_env:
  - name: MYPLATFORM_HOME_CHANNEL
    description: "Default channel for cron delivery"
    password: false

Full guide: Adding Platform Adapters — complete BasePlatformAdapter contract, message routing, auth gating, setup wizard integration. Look at plugins/platforms/irc/ for a stdlib-only working example.

Memory provider plugins — add a cross-session knowledge backend Copy Section

Drop an implementation of MemoryProvider into plugins/memory/<name>/:

# plugins/memory/my-memory/__init__.py
from agent.memory_provider import MemoryProvider

class MyMemoryProvider(MemoryProvider):
    @property
    def name(self) -> str:
        return "my-memory"

    def is_available(self) -> bool:
        from agent.secret_scope import get_secret
        return bool(get_secret("MY_MEMORY_API_KEY"))

    def initialize(self, session_id: str, **kwargs) -> None:
        self._session_id = session_id

    def sync_turn(self, user_content, assistant_content, *,
                  session_id="", messages=None) -> None:
        ...

    def prefetch(self, query, *, session_id="") -> str:
        ...

    def get_tool_schemas(self) -> list[dict]:
        return []   # required @abstractmethod — see full guide

def register(ctx):
    ctx.register_memory_provider(MyMemoryProvider())

Memory providers are single-select — only one is active at a time, chosen via memory.provider in config.yaml.

If a provider also loads as a general plugin, general discovery owns its lifecycle hooks. The memory loader supplies hooks only as a fallback until that same plugin source loads successfully through general discovery. Repeated provider loads replace the fallback hook group; distinct callbacks within the group are preserved. This does not deduplicate hooks from different plugin sources or change provider activation.

Full guide: Memory Provider Plugins — full MemoryProvider ABC, threading contract, profile isolation, CLI command registration via cli.py.

Context engine plugins — replace the context compressor Copy Section

# plugins/context_engine/my-engine/__init__.py
from agent.context_engine import ContextEngine

class MyContextEngine(ContextEngine):
    @property
    def name(self) -> str:
        return "my-engine"

    def update_from_response(self, usage) -> None: ...
    def should_compress(self, prompt_tokens: int = None) -> bool: ...
    def compress(self, messages, current_tokens=None, focus_topic=None,
                 force=False, memory_context="") -> list: ...

def register(ctx):
    ctx.register_context_engine(MyContextEngine())

Context engines are single-select — chosen via context.engine in config.yaml.

Full guide: Context Engine Plugins.

Image-generation backends Copy Section

Drop a provider into plugins/image_gen/<name>/:

# plugins/image_gen/my-imggen/__init__.py
from agent.image_gen_provider import ImageGenProvider

class MyImageGenProvider(ImageGenProvider):
    @property
    def name(self) -> str:
        return "my-imggen"

    def is_available(self) -> bool: ...
    def generate(self, prompt: str, aspect_ratio="landscape", **kwargs) -> dict:
        # returns success_response(...) / error_response(...)
        ...

def register(ctx):
    ctx.register_image_gen_provider(MyImageGenProvider())

# plugins/image_gen/my-imggen/plugin.yaml
name: my-imggen
kind: backend
version: 1.0.0
description: Custom image generation backend

Full guide: Image Generation Provider Plugins — full ImageGenProvider ABC, list_models() / get_setup_schema() metadata, success_response()/error_response() helpers, base64 vs URL output, user overrides, pip distribution.

Reference examples: plugins/image_gen/openai/ (DALL-E / GPT-Image via OpenAI SDK), plugins/image_gen/openai-codex/, plugins/image_gen/xai/ (Grok image gen).

Computer-use backend plugins Copy Section

The computer_use tool talks to exactly one driver through the ComputerUseBackend ABC
(tools/computer_use/backend.py). computer_use.backend in config.yaml picks it; the default is the
built-in cua-driver, which ships as an ordinary provider at plugins/computer_use/cua/. Another driver
is a provider plugin in ~/.hermes/plugins/<name>/ whose register(ctx) calls
ctx.register_computer_use_provider(). The directory name is the value you put in computer_use.backend.
Computer-use providers are single-select, like memory providers and context engines:

/* Detailed source-code truncated for AI context efficiency. */

# ~/.hermes/plugins/my-driver/plugin.yaml
name: my-driver
version: 1.0.0
description: Alternative computer-use driver   # shown in the picker

Select it in hermes tools → Computer Use (installed providers are listed under cua-driver, in the
CLI and in the Desktop toolset panel), or set it directly. No plugins.enabled entry is needed:

# config.yaml
computer_use:
  backend: my-driver     # default: cua

Rules:

• One provider is active at a time. Only the selected one is imported and instantiated. Installed
  providers that aren't selected stay on disk and are only listed (from plugin.yaml) as options. A
  provider never activates itself.
• Selection is per profile and read when a session starts its driver. If the configured name
  doesn't resolve, the call fails with an error naming it and the installed providers. Hermes never
  falls back to another driver.
• The model-facing schema is the same for every provider, so the prompt cache survives a driver
  swap. Report gaps per action with ActionResult(ok=False, code="unsupported_action", ...).
• Approval gating, the Bot Desktop lease, screenshot dedup, element caps and vision routing all run
  in the tool, above the backend. The backend only drives the screen.
• hermes computer-use status/doctor/permissions run cua-driver checks only when cua is
  selected. For any other provider they report its is_available() and run its doctor() if it has one.
• Providers return live driver sessions, so they load in-process only. Under
  plugins.isolation: host, a user provider is refused and the call reports that it could not be loaded.

Non-Python extension surfaces Copy Chapter

Hermes also accepts extensions that aren't Python plugins at all. These are shown in the Pluggable interfaces table; the sections below sketch each authoring style briefly.

MCP servers — register external tools Copy Section

Model Context Protocol (MCP) servers register their own tools into Hermes without any Python plugin. Declare them in ~/.hermes/config.yaml:

mcp_servers:
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
    timeout: 120

  linear:
    url: "https://mcp.linear.app/sse"
    auth:
      type: "oauth"

Hermes connects to each server at startup, lists its tools, and registers them alongside built-ins. The LLM sees them exactly like any other tool. Full guide: MCP.

Gateway event hooks — fire on lifecycle events Copy Section

Drop a manifest + handler into ~/.hermes/hooks/<name>/. Unlike plugins there is no plugins.enabled step: the gateway imports every valid hook directory at startup, so placing the files is the opt-in (trust model):

# ~/.hermes/hooks/long-task-alert/HOOK.yaml
name: long-task-alert
description: Send a push notification when a long task finishes
events:
  - agent:end

# ~/.hermes/hooks/long-task-alert/handler.py
async def handle(event_type: str, context: dict) -> None:
    if context.get("duration_seconds", 0) > 120:
        # send notification …
        pass

Events include gateway:startup, session:start, session:end, session:reset, agent:start, agent:step, agent:end, and wildcard command:*. Errors in hooks are caught and logged — they never block the main pipeline.

Full guide: Gateway Event Hooks.

Shell hooks — run a shell command on tool calls Copy Section

If you just want to run a script when a tool fires (notifications, audit logs, desktop alerts, auto-formatters), use shell hooks in config.yaml — no Python required:

hooks:
  - event: post_tool_call
    command: "notify-send 'Tool ran: {tool_name}'"
    when:
      tools: [terminal, patch, write_file]

Supports all the same events as Python plugin hooks (pre_tool_call, post_tool_call, pre_llm_call, post_llm_call, on_session_start, on_session_end, pre_gateway_dispatch) plus structured JSON output for pre_tool_call blocking decisions.

Full guide: Shell Hooks.

Skill sources — add a custom skill registry Copy Section

If you maintain a GitHub repo of skills (or want to pull from a community index beyond the built-in sources), add it as a tap:

hermes skills tap add myorg/skills-repo
hermes skills search my-workflow --source myorg/skills-repo
hermes skills install myorg/skills-repo/my-workflow

Publishing your own tap is just a GitHub repo with skills/<skill-name>/SKILL.md directories — no server or registry signup needed.

Full guides: Skills Hub · Publishing a custom tap (repo layout, minimal example, non-default paths, trust levels).

TTS / STT via command templates Copy Section

Any CLI that reads/writes audio or text can be plugged in through config.yaml — no Python code:

tts:
  provider: voxcpm
  providers:
    voxcpm:
      type: command
      command: "voxcpm --ref ~/voice.wav --text-file {input_path} --out {output_path}"
      output_format: mp3
      voice_compatible: true

For STT, point HERMES_LOCAL_STT_COMMAND at an argv-tokenized template. It runs without implicit shell interpretation; wrap it in sh -c, cmd /c, or PowerShell explicitly if the trusted local command requires shell syntax. Supported placeholders: {input_path}, {output_path}, {format}, {voice}, {model}, {speed} (TTS); {input_path}, {output_dir}, {language}, {model} (STT). Any path-interacting CLI is automatically a plugin.

Full guides: TTS custom command providers · STT.

Distribute via pip Copy Chapter

For sharing plugins publicly, add an entry point to your Python package:

# pyproject.toml
[project.entry-points."hermes_agent.plugins"]
my-plugin = "my_plugin_package"

Entry-point discovery remains supported when the distribution is present in the
environment supplied by the installation owner (for example, a Nix derivation).
It is discovery, not permission to inject packages into a PM-selected generation.
For managed installs, distribute a directory plugin with pyproject.toml or
manifest Python requirements and use hermes plugins install / enable so PM
can admit it transactionally. Restart Hermes after a new environment is selected.
hermes pm install accepts managed tool names, not arbitrary PyPI packages.

Distribute for NixOS Copy Chapter

:::warning Nix is no longer explicitly supported
Nix/NixOS is no longer an explicitly supported install path (best-effort only) — see Nix Setup. This section is kept for users already deploying on NixOS.
:::

NixOS users can install your plugin declaratively if you provide a pyproject.toml with entry points:

Entry-point plugins (recommended for distribution):

# User's configuration.nix
services.hermes-agent.extraPythonPackages = [
  (config.services.hermes-agent.package.python.pkgs.buildPythonPackage {
    pname = "my-plugin";
    version = "1.0.0";
    src = pkgs.fetchFromGitHub {
      owner = "you";
      repo = "hermes-my-plugin";
      rev = "v1.0.0";
      hash = "sha256-...";  # nix-prefetch-url --unpack
    };
    format = "pyproject";
    build-system = [ config.services.hermes-agent.package.python.pkgs.setuptools ];
  })
];

Directory plugins (no pyproject.toml needed):

services.hermes-agent.extraPlugins = [
  (pkgs.fetchFromGitHub {
    owner = "you";
    repo = "hermes-my-plugin";
    rev = "v1.0.0";
    hash = "sha256-...";
  })
];

See the Nix Setup guide for complete documentation including overlay usage and collision checking.

Common mistakes Copy Chapter

Handler doesn't return JSON string:

# Wrong — returns a dict
def handler(args, **kwargs):
    return {"result": 42}

# Right — returns a JSON string
def handler(args, **kwargs):
    return json.dumps({"result": 42})

Missing **kwargs in handler signature:

# Works — the dispatcher only forwards the context keywords a signature names
def handler(args):
    ...

# Better — receives every injected context field (task_id, session_id, parent_agent, ...)
def handler(args, **kwargs):
    ...

Handler raises exceptions:

# Wrong — exception propagates, tool call fails
def handler(args, **kwargs):
    result = 1 / int(args["value"])  # ZeroDivisionError!
    return json.dumps({"result": result})

# Right — catch and return error JSON
def handler(args, **kwargs):
    try:
        result = 1 / int(args.get("value", 0))
        return json.dumps({"result": result})
    except Exception as e:
        return json.dumps({"error": str(e)})

Schema description too vague:

# Bad — model doesn't know when to use it
"description": "Does stuff"

# Good — model knows exactly when and how
"description": "Evaluate a mathematical expression. Use for arithmetic, trig, logarithms. Supports: +, -, *, /, **, sqrt, sin, cos, log, pi, e."

User Guide Egress Index (`website/docs/user-guide/egress/index.md`) Copy Section

title: Egress proxy sidebar_position: 1 Copy Chapter

Egress proxy

Optional outbound credential-injection firewall for remote terminal sandboxes. The sandbox only ever holds opaque proxy tokens; real API keys never leave the host.

• iron-proxy — single-binary TLS-intercepting proxy from ironsh/iron-proxy, lazy-installed and managed by hermes egress.

User Guide Features Overview (`website/docs/user-guide/features/overview.md`) Copy Section

title: "Features Overview" sidebar_label: "Overview" sidebar_position: 1 Copy Chapter

Features Overview

Hermes Agent includes a rich set of capabilities that extend far beyond basic chat. From persistent memory and file-aware context to browser automation and voice conversations, these features work together to make Hermes a powerful autonomous assistant.

:::tip Don't know where to start?
hermes setup --portal covers a model provider plus all four Tool Gateway tools (web search, image generation, TTS, browser) in one command. See Nous Portal.
:::

Core Copy Chapter

• Tools & Toolsets — Tools are functions that extend the agent's capabilities. They're organized into logical toolsets that can be enabled or disabled per platform, covering web search, terminal execution, file editing, memory, delegation, and more.
• Skills System — On-demand knowledge documents the agent can load when needed. Skills follow a progressive disclosure pattern to minimize token usage and are compatible with the agentskills.io open standard.
• Persistent Memory — Bounded, curated memory that persists across sessions. Hermes remembers your preferences, projects, environment, and things it has learned via MEMORY.md and USER.md.
• Context Files — Hermes automatically discovers and loads project context files (.hermes.md, AGENTS.md, CLAUDE.md, SOUL.md, .cursorrules) that shape how it behaves in your project.
• Context References — Type @ followed by a reference to inject files, folders, git diffs, and URLs directly into your messages. Hermes expands the reference inline and appends the content automatically.
• Checkpoints — Hermes automatically snapshots your working directory before making file changes, giving you a safety net to roll back with /rollback if something goes wrong.

Automation Copy Chapter

• Scheduled Tasks (Cron) — Schedule tasks to run automatically with natural language or cron expressions. Jobs can attach skills, deliver results to any platform, and support pause/resume/edit operations.
• Subagent Delegation — The delegate_task tool spawns child agent instances with isolated context, restricted toolsets, and their own terminal sessions. Run 3 concurrent subagents by default (configurable) for parallel workstreams.
• Code Execution — The execute_code tool lets the agent write Python scripts that call Hermes tools programmatically, collapsing multi-step workflows into a single LLM turn via sandboxed RPC execution.
• Event Hooks — Run custom code at key lifecycle points. Gateway hooks handle logging, alerts, and webhooks; plugin hooks handle tool interception, metrics, and guardrails.
• Batch Processing — Run the Hermes agent across hundreds or thousands of prompts in parallel, generating structured ShareGPT-format trajectory data for training data generation or evaluation.

Media & Web Copy Chapter

• Voice Mode — Full voice interaction across CLI and messaging platforms. Talk to the agent using your microphone, hear spoken replies, and have live voice conversations in Discord voice channels.
• Wake Word — Hands-free "Hey Hermes" trigger for the CLI, TUI, and desktop app. An on-device hotword listener starts a voice session when you speak the wake phrase.
• Browser Automation — Full browser automation with multiple backends: Browserbase cloud, Browser Use cloud, local Chrome/Brave/Chromium/Edge via CDP, or local Chromium. Navigate websites, fill forms, and extract information.
• Vision & Image Paste — Multimodal vision support. Paste images from your clipboard into the CLI and ask the agent to analyze, describe, or work with them using any vision-capable model.
• Image Generation — Generate images from text prompts using FAL.ai. Eleven models supported (FLUX 2 Klein/Pro, GPT-Image 1.5/2, Nano Banana Pro, Ideogram V3, Recraft V4 Pro, Qwen, Z-Image Turbo, Krea V2 Medium/Large); pick one via hermes tools.
• Voice & TTS — Text-to-speech output and voice message transcription across all messaging platforms, with ten native provider options: Edge TTS (free), ElevenLabs, OpenAI TTS, MiniMax, Mistral Voxtral, Google Gemini, xAI, NeuTTS, KittenTTS, and Piper — plus custom command providers for any local TTS CLI.

Integrations Copy Chapter

• MCP Integration — Connect to any MCP server via stdio or HTTP transport. Access external tools from GitHub, databases, file systems, and internal APIs without writing native Hermes tools. Includes per-server tool filtering and sampling support.
• Provider Routing — Fine-grained control over which AI providers handle your requests. Optimize for cost, speed, or quality with sorting, whitelists, blacklists, and priority ordering.
• Fallback Providers — Automatic failover to backup LLM providers when your primary model encounters errors, including independent fallback for auxiliary tasks like vision and compression.
• Credential Pools — Distribute API calls across multiple keys for the same provider. Automatic rotation on rate limits or failures.
• Prompt caching — Built-in cross-session 1-hour prefix cache for Claude on native Anthropic, OpenRouter, and Nous Portal. Always-on; no configuration required.
• Memory Providers — Plug in external memory backends (RetainDB, ByteRover, plus Honcho, Hindsight, Supermemory, Mem0, OpenViking and Holographic from the plugin catalog) for cross-session user modeling and personalization beyond the built-in memory system.
• API Server — Expose Hermes as an OpenAI-compatible HTTP endpoint. Connect any frontend that speaks the OpenAI format — Open WebUI, LobeChat, LibreChat, and more.
• IDE Integration (ACP) — Use Hermes inside ACP-compatible editors such as VS Code, Zed, and JetBrains. Chat, tool activity, file diffs, and terminal commands render inside your editor.
• Batch Processing — Run the agent over many prompts or tasks in parallel from the CLI, with structured outputs and trajectory capture suitable for evals or downstream training pipelines.

Customization Copy Chapter

• Personality & SOUL.md — Fully customizable agent personality. SOUL.md is the primary identity file — the first thing in the system prompt — and you can swap in built-in or custom /personality presets per session.
• Skins & Themes — Customize the CLI's visual presentation: banner colors, spinner faces and verbs, response-box labels, branding text, and the tool activity prefix.
• Plugins — Add custom tools, hooks, and integrations without modifying core code. Three plugin types: general plugins (tools/hooks), memory providers (cross-session knowledge), and context engines (alternative context management). Managed via the unified hermes plugins interactive UI.

User Guide Messaging Index (`website/docs/user-guide/messaging/index.md`) Copy Section

sidebar_position: 1 title: "Messaging Gateway" Copy Chapter

Messaging Gateway

Chat with Hermes from Telegram, Discord, Slack, WhatsApp, Signal, SMS, Email, Home Assistant, Mattermost, Matrix, DingTalk, Feishu/Lark, WeCom, Weixin, BlueBubbles (iMessage), QQ, Yuanbao, Microsoft Teams, LINE, ntfy, or your browser. The gateway is a single background process that connects to all your configured platforms, handles sessions, runs cron jobs, and delivers voice messages.

For the full voice feature set — including CLI microphone mode, spoken replies in messaging, and Discord voice-channel conversations — see Voice Mode and Use Voice Mode with Hermes.

:::tip
Bots need both a model provider and tool providers (TTS, web). A Nous Portal subscription bundles all of them.
:::

Messaging status in Desktop and the dashboard Copy Chapter

Messaging status belongs to the selected profile on the selected machine. Credentials
saved by hermes gateway setup can enable a credential-based platform without a
platforms entry in config.yaml; an explicit platforms.<name>.enabled: false
still disables it. A different profile never inherits the server process's credentials.
Platforms without required credential fields are not enabled merely because that list
is empty.

Naming the server's own profile explicitly (for example profile=default on a
default-profile server) gives the same status as an unscoped request. Saved means
credentials are stored, not that the messaging gateway is running or the platform is
connected. An enabled platform can correctly show Messaging gateway stopped.

Platform Comparison Copy Chapter

Voice = TTS audio replies and/or voice message transcription. Images = send/receive images. Files = send/receive file attachments. Threads = threaded conversations. Reactions = emoji reactions on messages. Typing = typing indicator while processing. Streaming = progressive message updates via editing.

:::note Hermes Relay
Hermes Relay (experimental) is not a chat platform itself — it is a connector system that fronts platforms like Discord, Telegram, Slack, and WhatsApp through an external connector that owns the platform credentials. Capabilities (media, native approval/clarify prompts, reactions, threads, typing, streaming) are negotiated per connector at handshake rather than fixed in the table above.
:::

Architecture Copy Chapter

flowchart TB
    subgraph Gateway["Hermes Gateway"]
        subgraph Adapters["Platform adapters"]
            tg[Telegram]
            dc[Discord]
            wa[WhatsApp]
            sl[Slack]
            gc[Google Chat]
            sig[Signal]
            sms[SMS]
            em[Email]
            ha[Home Assistant]
            mm[Mattermost]
            mx[Matrix]
            dt[DingTalk]
    fs[Feishu/Lark]
    wc[WeCom]
    wcb[WeCom Callback]
    wx[Weixin]
    bb[BlueBubbles]
    qq[QQ]
    yb[Yuanbao]
    ms[Microsoft Teams]
    api["API Server<br/>(OpenAI-compatible)"]
    wh[Webhooks]
        end

        store["Session store<br/>per chat"]
        agent["AIAgent<br/>run_agent.py"]
        cron["Cron scheduler<br/>ticks every 60s"]
    end

    tg --> store
    dc --> store
    wa --> store
    sl --> store
    gc --> store
    sig --> store
    sms --> store
    em --> store
    ha --> store
    mm --> store
    mx --> store
    dt --> store
    fs --> store
    wc --> store
    wcb --> store
    wx --> store
    bb --> store
    qq --> store
    yb --> store
    ms --> store
    api --> store
    wh --> store
    store --> agent
    cron --> store

Each platform adapter receives messages, routes them through a per-chat session store, and dispatches them to the AIAgent for processing. The gateway also runs the cron scheduler, ticking every 60 seconds to execute any due jobs.

Intentional Silence Tokens Copy Chapter

For group chats, hooks, and automation flows, Hermes supports explicit silence tokens. If the agent's final response is exactly one supported token, the gateway suppresses outbound delivery and sends nothing to the chat.

Supported tokens:

• [SILENT]
• SILENT
• NO_REPLY
• NO REPLY
• [静默] / 静默 and [沉默] / 沉默 — the Chinese renderings a model produces when it translates the sentinel instead of emitting it literally

Whitespace and case are normalized, but the whole final response must be the token. A sentence like "Use [SILENT] when nothing changed" is delivered normally.

Silence is a delivery decision only. Hermes keeps the assistant silence turn in the session transcript, so the conversation still alternates normally:

user: side-channel chatter
assistant: [SILENT]   # stored, not delivered
user: next message

Failed turns still surface as errors; Hermes does not hide failures just because the text resembles a silence token.

On a message from a person, a bare silence token is replaced by a short notice, because a message that needed a reply must not vanish. Internal wakes such as background-process notifications may stay silent, and so may a message the platform adapter reports as not addressed to the bot. Slack reports this for messages that open by @mentioning someone else and for unmentioned top-level messages that start a new thread in a free-response channel; other platforms always get the notice.

Quick Setup Copy Chapter

The easiest way to configure messaging platforms is the interactive wizard:

hermes gateway setup        # Interactive setup for all messaging platforms

This walks you through configuring each platform with arrow-key selection, shows which platforms are already configured, and offers to start/restart the gateway when done.

Gateway Commands Copy Chapter

hermes gateway              # Run in foreground
hermes gateway setup        # Configure messaging platforms interactively
hermes gateway install      # Install as a user service (Linux) / launchd service (macOS)
sudo hermes gateway install --system   # Linux only: install a boot-time system service
hermes gateway start        # Start the default service
hermes gateway stop         # Stop the default service
hermes gateway status       # Check default service status
hermes gateway status --system         # Linux only: inspect the system service explicitly

Stack dump on demand (`SIGUSR2`) Copy Section

On Linux and macOS, kill -USR2 <gateway pid> appends a dump of every thread's
stack to ~/.hermes/logs/gateway_faulthandler.log and the gateway keeps
running — use it to see what a stalled or misbehaving gateway is doing without
restarting it.

Built-in event-loop liveness watchdog Copy Section

On every platform the gateway runs an out-of-loop watchdog thread that probes
the asyncio loop (gateway.loop_watchdog_probe_interval_s, default 30 s). When
the loop stops dispatching for gateway.loop_watchdog_max_strikes consecutive
probes (default 3), housekeeping, the cron scheduler and the embedded kanban
dispatcher have all frozen with it, so the watchdog dumps every thread's stack
to the log, stamps gateway_state.json with gateway_state: degraded and
exit_reason: loop_liveness_watchdog, and exits with code 75 so the service
supervisor restarts the process. hermes gateway status renders that record as
⚠ Gateway exited degraded: event loop stopped dispatching … until a new
gateway process overwrites it, and the dashboard's gateway badge shows
Degraded with the same reason. Set gateway.loop_watchdog: false in
config.yaml to disable the watchdog.

Housekeeping also re-stamps gateway_state.json's updated_at every tick
(60 s), so it doubles as a heartbeat: when the process is still alive but that
stamp is more than 120 s old, hermes gateway status prints
⚠ Gateway heartbeat stale: housekeeping has not refreshed gateway_state.json for N s … and the dashboard badge reads Heartbeat stale — the "looks
running but nothing is scheduled" case. Restart the gateway.

Optional Linux event-loop watchdog Copy Section

A systemd-managed gateway can opt into process recovery when Python's asyncio
event loop stops receiving scheduling time. This covers whole-process stalls
that also prevent platform-specific liveness tasks from running:

gateway:
  systemd_watchdog_seconds: 120

Regenerate the service unit after changing this setting:

hermes gateway install --force

A positive value makes the generated unit use Type=notify,
NotifyAccess=main, and the matching WatchdogSec. Hermes sends heartbeats
only while its event loop is making timely progress; systemd restarts the
process when they stop. The default 0 keeps the existing Type=simple
behavior. This setting is Linux/systemd-only and does not treat an ordinary
platform network disconnect as an event-loop failure.

Chat Commands (Inside Messaging) Copy Chapter

Session Management Copy Chapter

Session Persistence Copy Section

Sessions persist across messages until they reset. The agent remembers your conversation context.

Finding Past Sessions (`/sessions`) Copy Section

/sessions lists your previous sessions for the current chat — including the one you're in now, marked (current) — and /sessions <name> resumes one (shorthand for /resume). When the list grows long, /sessions search <query> (alias find) filters by title or session-id match, ordered by most recently active. Cross-origin listing with /sessions all is admin-only — regular users get a notice explaining the list stayed chat-scoped, and only ever see sessions from their own chat origin.

Persistent `/model` Overrides Copy Section

A /model switch in a gateway chat applies to that session and now survives gateway restarts: the model/provider choice is persisted to the session store and rehydrated on first use after a restart (credentials are re-resolved at load time and never written to disk). /new (or /reset) clears the override, and /model <name> --global writes it through to config.yaml instead. /model <name> --once applies for a single turn only.

Delivery Reliability Copy Section

Final agent responses are recorded in a durable delivery ledger
(state.db) around each platform send. If the gateway crashes or restarts
between producing a response and the platform confirming receipt, the next
boot redelivers the stored response instead of losing it — or re-running the
whole turn. The ledger lives in the home the gateway was started from; a
multiplexed gateway keeps every served profile's replies there too.

Semantics are honest at-least-once:

• A response whose send never started is redelivered as-is.
• A response that was mid-send when the gateway died (the platform may or
  may not have received it), including a redelivery an earlier boot was
  still sending, is redelivered with a visible
  "♻️ Recovered reply — … may be a duplicate" prefix. Ambiguity is labeled,
  never silently resent.
• A final send refused by flood control (such as Telegram rate limits) is retried automatically
  after the recorded penalty expires, without requiring a reconnect or restart.
  A restart during the penalty adopts the stored reply without spending a retry
  attempt or re-running the agent. Retries retain the original bot profile, chat
  and thread. A rate-limit recovery prefix warns that earlier chunks may already
  have arrived; the ledger cannot infer partial delivery from message length.
• Any other rejected final send (a platform 5xx, an unclassified error) is retried the same
  way after a growing backoff (30 s, then 2 min); the last budgeted attempt is left for the
  next gateway start, so an outage that outlasts the timer never strands the reply. A
  permanently unreachable chat (blocked bot, deleted group) is not retried.
• Redelivery is bounded: 3 attempts, 24-hour freshness, then the row is
  abandoned. Delivered rows are pruned after 7 days.

Disable with gateway.delivery_ledger: false in config.yaml (restores the
old behavior: in-flight responses are lost on crash).

Session continuity Copy Section

Gateway conversations do not reset after inactivity or at a daily boundary. Use /new
or /reset for an explicit new conversation; context compression remains automatic.
Core ignores legacy session_reset settings, reset-policy overrides and reset-timer
environment variables. If your config still sets session_reset.mode to idle, daily
or both, gateway startup and hermes doctor warn about it. To keep time-based resets,
install the catalog plugin that reads the same block unchanged:
hermes plugins install hermes-session-reset-policy. Cached agents may be released to reclaim resources without
replacing the durable conversation. Restart-recovery freshness limits automatic
continuation, not the history loaded when you send a message.

Per-Channel Model & System Prompt Overrides Copy Chapter

Different channels can run different models and personas from a single gateway — e.g. a cheap fast model in #daily and a frontier model with a specialist prompt in #dev. Configure channel_overrides under the platform in ~/.hermes/config.yaml:

platforms:
  discord:
    enabled: true
    channel_overrides:
      "123456789012345678":        # channel/thread id
        model: anthropic/claude-sonnet-4.6
        provider: anthropic
        system_prompt: "You are the #dev channel code-review specialist."
      "987654321098765432":
        model: openai/gpt-5-mini

Details:

• All three keys are optional — set only model, only system_prompt, or any combination. Unset fields fall back to the global defaults.
• Lookup order is exact channel/thread id first, then the parent channel/forum id — so Discord threads inherit their parent channel's override automatically.
• Resolution priority for the model is: session /model override → channel_overrides → global config. A user running /model in a chat still wins over the channel default.
• The system_prompt override replaces the global gateway prompt for that channel (it is ephemeral — injected per turn, not stored in history).

Security Copy Chapter

By default, the gateway denies all users who are not in an allowlist or paired via DM. This is the safe default for a bot with terminal access.

# Restrict to specific users (recommended):
TELEGRAM_ALLOWED_USERS=123456789,987654321
DISCORD_ALLOWED_USERS=123456789012345678
SIGNAL_ALLOWED_USERS=+155****4567,+155****6543
SMS_ALLOWED_USERS=+155****4567,+155****6543
[email protected],[email protected]
MATTERMOST_ALLOWED_USERS=3uo8dkh1p7g1mfk49ear5fzs5c
MATRIX_ALLOWED_USERS=@alice:matrix.org
DINGTALK_ALLOWED_USERS=user-id-1
FEISHU_ALLOWED_USERS=ou_xxxxxxxx,ou_yyyyyyyy
WECOM_ALLOWED_USERS=user-id-1,user-id-2
WECOM_CALLBACK_ALLOWED_USERS=user-id-1,user-id-2
TEAMS_ALLOWED_USERS=aad-object-id-1,aad-object-id-2

# Or allow
GATEWAY_ALLOWED_USERS=123456789,987654321

# Or explicitly allow all users (NOT recommended for bots with terminal access):
GATEWAY_ALLOW_ALL_USERS=true

DM Pairing (Alternative to Allowlists) Copy Section

Instead of manually configuring user IDs, unknown users receive a one-time pairing code when they DM the bot. Email is the exception: unknown email senders are ignored unless email pairing is explicitly enabled.

# The user sees: "Pairing code: XKGH5N7P"
# You approve them with:
hermes pairing approve telegram XKGH5N7P

# Other pairing commands:
hermes pairing list          # View pending + approved users
hermes pairing revoke telegram 123456789  # Remove access

Pairing codes expire after 1 hour, are rate-limited, and use cryptographic randomness.

Admins vs Regular Users Copy Section

Allowlists answer "can this person reach the bot at all?" The admin / user split answers "now that they're in, what are they allowed to do?"

Every allowed user falls into one of two tiers per scope (DM vs group/channel):

• Admin — full access. Can run every registered slash command (built-in + plugin) and use every gated capability.
• Regular user — restricted access. Can chat with the agent normally, but can only run the slash commands you explicitly enable. The always-allowed floor is /help and /whoami.

The tiers are configured per platform and per scope. DM admin status does not imply group/channel admin status — each scope has its own admin list.

What the tiers gate today: slash commands. The split runs through the live command registry, so it covers built-ins and plugin-registered commands without per-feature wiring. Plain chat is not affected — non-admins can still talk to the agent.

What may be gated in the future: more capability surfaces (tool access, model switching, expensive operations) will hang off the same admin / user distinction as we add them. Configuring the split now means those future restrictions land cleanly without you having to re-model who's an admin.

Configuration

gateway:
  platforms:
    discord:
      extra:
        allow_from: ["111", "222", "333"]
        allow_admin_from: ["111"]                    # admins → all slash commands
        user_allowed_commands: [status, model]       # what non-admins may run
        # Optional: separate group/channel scope
        group_allow_admin_from: ["111"]
        group_user_allowed_commands: [status]

Backward compat: if allow_admin_from is not set for a scope, the tier split is disabled for that scope and every allowed user has full access. Existing installs keep working with no changes — opt in when you want the distinction.

Inspecting your access

Use /whoami from any platform to see the active scope, your tier (admin / user / unrestricted), and which slash commands you can run. When an admin list is configured, /help and /commands show a non-admin only the commands they can actually run (/help, /whoami, plus user_allowed_commands); admins see the full catalog. See the Telegram and Discord pages for platform-specific examples.

Redirecting the Agent Copy Chapter

Send a message while the agent is working to correct the active turn:

• Model generation restarts with context — reasoning already shown and visible partial text are retained as an ordinary assistant checkpoint
• Completed work stays available — prior tool calls and results remain in the turn
• Running tools finish safely — the correction is applied at the next tool-result boundary instead of killing the tool
• /stop remains a hard stop — use it to cancel the active turn and foreground work

Queue vs interrupt vs steer (busy-input mode) Copy Section

By default, messaging a busy agent redirects its active turn (a running foreground terminal command is moved to the background rather than killed, so your message is read immediately). Two other modes are available:

• queue — follow-up messages wait and run as the next turn after the current task finishes. Each follow-up (text, voice note, video, document) gets its own turn in arrival order; only a rapid photo burst is merged into one album turn.
• steer — follow-up messages are injected into the current run via /steer, arriving at the agent after the next tool call. No interrupt, no new turn. Falls back to queue behavior if the agent hasn't started yet.

Gateway steers (including explicit /steer) and active-turn redirects carry the requesting event's available platform, chat, thread, sender, message, profile, and scope identifiers as per-message JSON context. With privacy.redact_pii: true, identifiers in this model-visible context are hashed on supported platforms, including alternate and parent identifiers; the original event identifiers remain internal for routing. Otherwise identifiers are preserved exactly. Neither mode changes the session's system prompt or chooses a fallback reply destination. The context is routing data, not authorization or a guarantee of automatic delivery.

display:
  busy_input_mode: steer   # or queue, or interrupt (default)
  busy_ack_enabled: true   # set to false to suppress the ⚡/⏳/⏩ chat reply entirely
  busy_text_debounce_seconds: 0.35   # quiet window before merged busy text is delivered
  busy_text_hard_cap_seconds: 1.0    # never hold merged busy text longer than this

All four keys are read from each profile's own config.yaml, so multiplexed profiles keep independent busy policies; there is no process-environment override.

The first time you message a busy agent on any platform, Hermes appends a one-line reminder to the busy-ack explaining the knob ("💡 First-time tip — …"). The reminder fires once per install — a flag under onboarding.seen.busy_input_prompt latches it. Delete that key to see the tip again.

If you find the busy acknowledgment noisy, set display.busy_ack_enabled: false. Input handling is unchanged; only the confirmation message is hidden.

Clarify Questions (Multi-Select) Copy Chapter

When the agent uses the clarify tool to ask you a question, the gateway renders the choices as a numbered prompt (or native buttons on platforms that support them). Clarify supports multi-select questions too — the agent can let you pick several options at once:

• Messaging platforms — the prompt says "Multiple selections allowed"; reply with the numbers separated by commas or spaces (e.g. 1, 3), the option text, or your own free-form answer.
• Classic CLI / TUI — multi-select renders as checkboxes: Space toggles an option, Enter submits the selection.

Single-select prompts behave as before: pick one option by number, button, or text, or type your own answer via the "Other" path.

Tool Progress Notifications Copy Chapter

Control how much tool activity is displayed in ~/.hermes/config.yaml:

display:
  tool_progress: all    # off | new | all | verbose | log
  tool_progress_command: false  # set to true to enable /verbose in messaging
  # How progress is grouped on platforms that support message editing:
  #   accumulate (default) — edit one bubble in place as tools run
  #   separate             — send one message per tool (pre-v0.9 style; noisier)
  # Only applies where tool_progress is already enabled.
  tool_progress_grouping: accumulate   # accumulate | separate

`log` mode — audit file instead of chat messages Copy Section

Setting display.tool_progress: log sends no progress bubbles to chat. Instead, each tool call is appended as a line to ~/.hermes/logs/tool_calls.log — a rotating audit file (5 MB × 3 backups) run through the same secret-redacting formatter as regular logs, so credentials never land on disk. Use it when you want a full tool-call trail without any chat noise.

Configurable status phrases Copy Section

Long-running gateway status lines ("still working…"-style heartbeats) draw from a phrase catalog. Built-in defaults ship in gateway/assets/status_phrases.yaml; you can add your own with profile-portable files under HERMES_HOME:

• ~/.hermes/status_phrases.yaml or any *.yaml in ~/.hermes/status_phrases/ (conventional paths, auto-loaded), or
• point config at a relative path:

display:
  status_phrases:
    path: status_phrases/whatsapp.yaml  # relative to HERMES_HOME
    mode: append                        # append (default) or replace

Phrase files map a surface (status, generic) to a list of strings (max 80 phrases per surface, 160 chars each). Absolute paths and .. escapes are ignored so config stays profile-portable. Only your configured phrase strings are used — raw tool arguments, commands, and reasoning text are never interpolated into a status phrase.

Message timestamps in model context Copy Section

Off by default. When enabled, Hermes prepends a human-readable timestamp
(e.g. [Tue 2026-04-28 13:40:53 CEST]) onto each user message in the
model's context so the agent knows when messages were sent — useful for
temporal reasoning ("you asked this morning…", noticing a long gap). It is
not added to assistant messages or the system prompt.

gateway:
  message_timestamps:
    enabled: false   # set true to show send-times to the model

Persisted transcripts always stay clean — the timestamp is stored as message
metadata regardless of this toggle, so enabling it later also surfaces
send-times for past messages, and replay never accumulates duplicate prefixes.

When enabled, the bot sends status messages as it works:

💻 `ls -la`...
🔍 web_search...
📄 web_extract...
🐍 execute_code...

Background Sessions Copy Chapter

Run a prompt in a separate background session so the agent works on it independently while your main chat stays responsive:

/bg Check all servers in the cluster and report any that are down

Hermes confirms immediately:

🔄 Background task started: "Check all servers in the cluster..."
   Task ID: bg_143022_a1b2c3

How It Works Copy Section

Each /bg prompt spawns a separate agent instance that runs asynchronously:

• Isolated session — the background agent has its own session with its own conversation history. It has no knowledge of your current chat context and receives only the prompt you provide.
• Same configuration — inherits your model, provider, toolsets, reasoning settings, and provider routing from the current gateway setup.
• Non-blocking — your main chat stays fully interactive. Send messages, run other commands, or start more background tasks while it works.
• Result delivery — when the task finishes, the result is sent back to the same chat or channel where you issued the command, prefixed with "✅ Background task complete". If it fails, you'll see "❌ Background task failed" with the error.

Background Process Notifications Copy Section

When the agent running a background session uses terminal(background=true) to start long-running processes (servers, builds, etc.), the gateway can push status updates to your chat. Control this with display.background_process_notifications in ~/.hermes/config.yaml:

display:
  background_process_notifications: concise    # concise | all | result | error | off

You can also set this via environment variable:

HERMES_BACKGROUND_NOTIFICATIONS=result

With terminal(background=true, notify_on_complete=true) the finished process starts a new agent turn and the agent reports the result itself, so no separate status line is sent. The exception is a process that finishes while the turn that launched it is still running: the completion is queued as the agent's next turn and you get the one-line concise status right away (unless the mode is off, or error with a zero exit code), instead of silence until that turn ends.

Use Cases Copy Section

• Server monitoring — "/bg Check the health of all services and alert me if anything is down"
• Long builds — "/bg Build and deploy the staging environment" while you continue chatting
• Research tasks — "/bg Research competitor pricing and summarize in a table"
• File operations — "/bg Organize the photos in ~/Downloads by date into folders"

:::tip
Background tasks on messaging platforms are fire-and-forget — you don't need to wait or check on them. Results arrive in the same chat automatically when the task finishes.
:::

Service Management Copy Chapter

Linux (systemd) Copy Section

hermes gateway install               # Install as user service
hermes gateway start                 # Start the service
hermes gateway stop                  # Stop the service
hermes gateway status                # Check status
journalctl --user -u hermes-gateway -f  # View logs

# Enable lingering (keeps running after logout)
sudo loginctl enable-linger $USER

# Or install a boot-time system service that still runs as your user
sudo hermes gateway install --system
sudo hermes gateway start --system
sudo hermes gateway status --system
journalctl -u hermes-gateway -f

Use the user service on laptops and dev boxes. Use the system service on VPS or headless hosts that should come back at boot without relying on systemd linger.

:::danger Don't add a custom ExecStopPost kill drop-in
The unit Hermes installs already shuts the gateway down cleanly with KillMode=mixed + KillSignal=SIGTERM, and uses Restart=always with RestartForceExitStatus so updates and /restart respawn correctly. Do not add a systemd drop-in such as ExecStopPost=/bin/kill -9 $MAINPID — ExecStopPost fires on every stop, including clean restarts, so it SIGKILLs the freshly spawned instance before it stabilizes and Restart=always immediately respawns it. The result is an infinite restart loop (and, on Telegram, a flood of restart messages). If you've added such a drop-in, remove it: systemctl --user edit hermes-gateway (or sudo systemctl edit hermes-gateway for a system service) and delete the ExecStopPost line, then systemctl --user daemon-reload.
:::

Direct `systemctl restart` / `stop` exits cleanly Copy Section

The installed unit declares ExecStop= to record a planned-stop marker for $MAINPID before SIGTERM is delivered, so stopping or restarting the service directly is classified as intentional: the gateway drains, persists gateway_state=stopped, and exits 0 — the journal shows a clean stop/start with no Failed with result exit-code line.

systemctl --user restart hermes-gateway   # or: sudo systemctl restart hermes-gateway

Prefer hermes gateway restart when in-flight agent turns matter: it asks the gateway to drain first (SIGUSR1, honoring the restart wait budget) and waits for the replacement, while a raw systemctl restart stops the current process on systemd's schedule. After updating Hermes, run hermes gateway restart once so the running service picks up the regenerated unit that contains the ExecStop= line (hermes gateway status warns while the installed unit is outdated).

The installed unit also maps systemctl reload hermes-gateway to SIGUSR1. For Hermes, reload therefore means a graceful drain, process exit, and supervisor relaunch; it is not an in-process configuration reload. Use hermes gateway restart when you want the CLI to wait for and verify the replacement process.

:::tip Headless VMs: user service + linger avoids root prompts
A system service needs root for every restart — including the automatic gateway restart at the end of hermes update. When hermes update runs as a non-root user, it tries passwordless sudo systemctl; if that's unavailable, it skips the restart and prints the manual sudo systemctl restart hermes-gateway command (it never blocks on an interactive password prompt).

For a headless VM you never log into, a user service with lingering enabled gives you the same start-at-boot behavior with zero root involvement:

hermes gateway install          # user service
sudo loginctl enable-linger $USER   # one-time: start at boot, survive logout

After that, hermes update can restart the gateway without any privileges. If you prefer to keep the system service, either run updates with sudo hermes update, or grant the service account passwordless sudo for systemctl, e.g. in sudo visudo -f /etc/sudoers.d/hermes-gateway:

hermes ALL=(root) NOPASSWD: /usr/bin/systemctl --no-ask-password reset-failed hermes-gateway*, /usr/bin/systemctl --no-ask-password start hermes-gateway*, /usr/bin/systemctl --no-ask-password restart hermes-gateway*

:::

Avoid keeping both the user and system gateway units installed at once unless you really mean to. Hermes will warn if it detects both because start/stop/status behavior gets ambiguous.

An installed unit (or launchd plist) belongs to the HERMES_HOME it pins. A gateway started from a different home, such as a test or scratch home that happens to resolve to the same service name, never rewrites it: gateway run, start, restart and install --force refuse with a message naming both homes and leave the file alone. To deliberately point an existing service at the current home, run hermes gateway install --force-unit-path.

:::note Inside a container, only the system scope is offered
hermes gateway install (and the hermes gateway setup wizard) refuse to install a user service when Hermes detects it is running inside a container. A user unit lands in ~/.config/systemd/user, and when that home is bind-mounted from the host (podman/distrobox), the host's own systemd --user enables and starts the same unit — a second gateway polling the same bot token. Run the gateway as the container's main process (hermes gateway run, with a container restart policy), or in a systemd container (systemd as PID 1) install the isolated system scope: sudo hermes gateway install --system --run-as-user .
:::

:::info Multiple installations
If you run multiple Hermes installations on the same machine (with different HERMES_HOME directories), each gets its own systemd service name. The default ~/.hermes uses hermes-gateway; other installations use hermes-gateway-<hash>. The hermes gateway commands automatically target the correct service for your current HERMES_HOME.
:::

macOS (launchd) Copy Section

hermes gateway install               # Install as launchd agent
hermes gateway start                 # Start the service
hermes gateway stop                  # Stop the service
hermes gateway status                # Check status
tail -f ~/.hermes/logs/gateway.log   # View logs

The generated plist lives at ~/Library/LaunchAgents/ai.hermes.gateway.plist. It includes three environment variables:

• PATH — your full shell PATH at install time, with the venv bin/ and node_modules/.bin prepended. This ensures user-installed tools (Node.js, ffmpeg, etc.) are available to gateway subprocesses like the WhatsApp bridge.
• VIRTUAL_ENV — points to the Python virtualenv so tools can resolve packages correctly.
• HERMES_HOME — scopes the gateway to your Hermes installation.

:::tip PATH changes after install
launchd plists are static — if you install new tools (e.g. a new Node.js version via nvm, or ffmpeg via Homebrew) after setting up the gateway, run hermes gateway install again to capture the updated PATH. The gateway will detect the stale plist and reload automatically.
:::

:::info Installing without starting
The plist sets RunAtLoad, so loading it starts the gateway. hermes gateway install --no-start-now, like answering No to "Start the gateway now?" in hermes gateway setup, writes the plist without loading it: the gateway starts at your next login, or when you run hermes gateway start. A gateway that launchd is already running is reloaded onto the new plist, not stopped.
:::

:::info Local Network access (LAN devices fail with "No route to host")
macOS Local Network Privacy attributes a socket to the executable launchd spawned for the job. A bare venv Python has no application identity, so a launchd-run gateway could not reach LAN hosts (Home Assistant, local model servers) — every connect failed with errno 65 No route to host while the same URL worked from Terminal, and no prompt was ever shown to grant it. The generated plist therefore runs the gateway through /usr/bin/osascript; a JXA system() call starts the gateway without an interactive event-polling loop, and macOS treats its children as osascript's own — an Apple platform binary, exempt from the check. ps shows osascript → stderr_timestamp → gateway run; stop/restart/KeepAlive behave exactly as before. A plist installed by an older Hermes is refreshed by hermes gateway install (or on the next hermes gateway start).
:::

:::tip Picking up new credentials after hermes auth add / hermes auth reset
Agents run as threads inside the one gateway process; the only child processes are tool subprocesses (terminal commands, browsers), which never hold provider credentials. A running gateway also re-reads the openai-codex login it seeded from auth.json the next time its pool selects that entry after it had gone exhausted or dead (entries added with hermes auth add openai-codex are independent accounts and are not resynced). When you want every session on the fresh login at once, restart the gateway — but prefer the drain-aware path over a bare kill:

• hermes gateway restart asks the gateway (SIGUSR1) to refuse new turns, waits up to agent.restart_after_turn_timeout (default 1800 s) for in-flight turns to finish, exits, and lets launchd's KeepAlive relaunch it; the new process reads auth.json from scratch.
• launchctl kickstart -k gui/$UID/ai.hermes.gateway sends SIGTERM instead: the gateway interrupts in-flight chat turns after agent.restart_drain_timeout (default 0 — immediately; the user is told and the turn resumes on their next message), gives cron runs and api_server (/v1) runs agent.cron_drain_timeout (default 30 s), kills tool subprocesses and exits, then launchd relaunches it. Nothing from the old process survives, so a session that still fails with 401 after the relaunch is talking to a different gateway process — check hermes gateway status (and launchctl list | grep hermes) for a second PID, such as a manually started hermes gateway run, and stop that one too.
  :::

:::info Multiple installations
Like the Linux systemd service, each HERMES_HOME directory gets its own launchd label. The default ~/.hermes uses ai.hermes.gateway; other installations use ai.hermes.gateway-<suffix>.
:::

Windows (Task Scheduler) Copy Section

hermes gateway install               # Register the Hermes_Gateway Scheduled Task (runs at logon)
hermes gateway start                 # Start the gateway hidden, without a console window
hermes gateway stop                  # Drain and stop the service
hermes gateway status                # Check status, including registration drift

The Scheduled Task runs wscript.exe on a generated .vbs launcher under %USERPROFILE%\.hermes\gateway-service\. The launcher starts python.exe -m hermes_cli.main gateway run with a hidden window and **exits immediately** — by design: wscript.exe has no console, so at logon it never receives the CTRL_CLOSE_EVENT that kills a cmd.exe-hosted gateway, and the gateway inherits one hidden console instead of every subprocess flashing its own (see hermes_cli/gateway_windows.py::_build_gateway_vbs_script).

:::warning RestartOnFailure covers the launcher, not the gateway
Because the launcher returns as soon as the gateway is spawned, Task Scheduler only ever sees the launcher's exit code. The <RestartOnFailure> policy in the registered task therefore fires only when wscript.exe itself fails to start the gateway — it does not restart a gateway that crashes or is killed later. Gateway auto-restart on Windows relies on the gateway's own in-process restart path (/restart, updates, and the hermes gateway restart command); a gateway killed from outside stays down until hermes gateway start or schtasks /Run /TN <task>.
:::

hermes gateway install writes the task from the current template; a task registered by an older build would otherwise keep its old settings (no RestartOnFailure, no logon Delay, an older launcher command line) indefinitely. hermes gateway status compares the registered task with the current template and warns when it predates it:

⚠ Scheduled Task registration predates the current template (missing: RestartOnFailure, LogonTrigger Delay; version 1.3 vs 1.4)
  Repair: hermes gateway start  (or: hermes gateway install)

hermes gateway start and hermes update run the same comparison and re-register a drifted task from the current template automatically (like the systemd unit refresh on Linux); when schtasks refuses without elevation, re-run hermes gateway install, which can request administrator approval. The check is silent when the task cannot be queried, and it only inspects a few settings Hermes owns (task version, RestartOnFailure, the logon trigger delay and the launcher arguments), so deliberate local edits elsewhere in the task are not flagged.

Platform-Specific Toolsets Copy Chapter

Each platform has its own toolset:

Operating a multi-platform gateway Copy Chapter

A gateway typically runs several adapters at once (Telegram + Discord + Slack, etc.). The sections below cover day-2 operations that span all platforms.

`/platform` command Copy Section

Once the gateway is running, use the /platform slash command from any connected CLI session or chat to inspect and steer individual adapters without restarting the whole gateway:

/platform list                  # show all adapters and their state
/platform pause <name>          # stop dispatching new messages to one adapter
/platform resume <name>         # re-enable a paused adapter

/platform list shows whether each adapter is running, paused (manually), or paused-by-breaker (see below). Pausing keeps the adapter loaded and its background loops alive — incoming messages are dropped on the floor, but the connection itself stays open so resume is instant.

See also the broader status summary command /platforms.

Disabling a platform whose credentials are still in `.env` Copy Section

platforms.<name>.enabled: false in ~/.hermes/config.yaml is authoritative.
Credentials for that platform left in the environment (TELEGRAM_BOT_TOKEN,
WEIXIN_TOKEN, HASS_TOKEN, EMAIL_*, TWILIO_ACCOUNT_SID, ...) are still
wired into the platform's config so send-only tooling keeps working, but they
no longer start the adapter:

platforms:
  weixin:
    enabled: false   # wins over WEIXIN_TOKEN in .env

Earlier releases let the mere presence of credentials re-enable twelve
platforms (Weixin, WhatsApp Cloud, Home Assistant, Email, SMS, DingTalk, Feishu,
WeCom, WeCom callback, BlueBubbles, QQ Bot, Yuanbao) regardless of that key. If
you relied on that, the gateway now logs one WARNING per affected platform at
startup so it does not just go dark:

Platform 'weixin' is explicitly disabled by platforms.weixin.enabled: false in config.yaml,
so the credentials found in the environment (WEIXIN_TOKEN, WEIXIN_ACCOUNT_ID) will NOT start
its adapter. Environment credentials no longer override an explicit disable. Remove the key
or set platforms.weixin.enabled: true to turn it back on.

Omitting the enabled key entirely keeps the env-only behaviour: credentials
present → adapter starts.

Ignoring an inherited proxy (`gateway.trust_env`) Copy Section

By default every platform adapter honors HTTP_PROXY / HTTPS_PROXY /
NO_PROXY (and SSL_CERT_FILE) from the gateway's environment, and
auto-detects the macOS system proxy. A gateway started by a Windows Scheduled
Task or a service manager can inherit a proxy the interactive shell never
sees — a local Clash/V2Ray listener that isn't running yet — and log
Cannot connect to host 127.0.0.1:7890 on every poll. Turn the inherited
proxy off for all adapters at once:

gateway:
  trust_env: false

Explicit per-platform proxy variables (DISCORD_PROXY, TELEGRAM_PROXY,
MATRIX_PROXY, ...) are still honored. Restart the gateway after changing it.

Automatic circuit breaker Copy Section

Each adapter is wrapped in a circuit breaker. Repeated retryable failures (network blips, rate-limit replies, 5xx upstream responses, websocket disconnects) cause the breaker to trip — the adapter is auto-paused, an operator notification is sent to the home channel of another live platform when one is configured, and a structured log line is emitted.

The breaker does not auto-resume — it stays open until you run /platform resume <name> manually. This is intentional: if a platform is in a sustained outage, you don't want the gateway thrashing reconnects.

Where to look when a platform is paused Copy Section

When an adapter is paused, check:

1. Gateway log (~/.hermes/logs/gateway.log or the systemd / launchd unit log). Search for the platform name and circuit breaker, paused, or disabled. The trip event includes the failure count and the last error.
2. /platform list output — shows the current state and last reason.
3. The provider's status page (Telegram bot API status, Discord status, etc.). The breaker tripped because the platform was unhealthy; don't try to resume until it's back.

Once upstream is healthy, /platform resume <name> clears the breaker and re-arms the adapter.

Restart notifications Copy Section

When the gateway restarts (or is shut down with in-flight sessions), it can send a one-shot "the agent is back" / "the agent was interrupted" message to each platform's home channel. This is controlled per-platform by the gateway_restart_notification flag in config.yaml, which defaults to true:

gateway:
  platforms:
    telegram:
      home_chat_id: "123456789"
      gateway_restart_notification: false   # opt out for this platform
    discord:
      home_chat_id: "987654321"
      # gateway_restart_notification omitted → defaults to true

Disable it on noisy or low-priority platforms while leaving it on for your primary chat. The notification is sent once per restart, regardless of how many sessions were in flight.

Typing indicators Copy Section

While the agent is processing a message, the gateway shows a live typing status on platforms that support it — a "typing…" bubble on Telegram/Discord/Signal, or the "is thinking…" assistant status on Slack. This is controlled per-platform by the typing_indicator flag in config.yaml, which defaults to true:

gateway:
  platforms:
    slack:
      typing_indicator: false   # don't show "is thinking…" on Slack
    telegram:
      # typing_indicator omitted → defaults to true

Set typing_indicator: false on any platform where the indicator is unwanted. Some users find Slack's "is thinking…" status noisy (it also briefly disables the compose box while shown, since it uses Slack's Assistant API). Disabling it only suppresses the indicator — message delivery and everything else is unchanged. The flag is generic, so the same key works for every platform.

Session resume across gateway restarts Copy Section

When the gateway shuts down with an in-flight tool call or generation, the affected sessions are flagged as restart_interrupted. On the next startup, the gateway schedules an auto-resume for each one — the user gets a short heads-up in the chat ("Send any message after restart and I'll try to resume where you left off.") and the session picks up from the last committed turn when they reply.

Only turns that were actually in flight are resumed, and each resumes once. A chat whose turn had already finished is never answered again just because it was active shortly before a crash. If the gateway was killed after the agent finished a reply but before it was sent, the stored reply is delivered (with a "Recovered reply" notice) instead of being regenerated.

This behaviour is on by default and is logged at gateway start:

Scheduled auto-resume for N restart-interrupted session(s)

No configuration is required. If you don't want the heads-up, set gateway_restart_notification: false on the platform.

Mobile-friendly progress defaults Copy Section

Telegram is usually a mobile inbox, so the defaults are tuned for that surface:

• tool_progress defaults to off — no per-tool breadcrumb stream filling up the chat.
• busy_ack_detail defaults to off — busy-state acknowledgments and long-running heartbeats stay terse (no iteration 21/60 debug detail).
• interim_assistant_messages stays on — real mid-turn assistant commentary (the model literally telling you what it's about to do) is signal, not noise.
• long_running_notifications stays on — a single edit-in-place "⏳ Working — N min" bubble updates every few minutes so you have a heartbeat instead of staring at typing… for half an hour.

These per-platform defaults apply only while the same key is unset directly under display:. A global display.tool_progress, display.show_reasoning, display.busy_ack_detail, display.interim_assistant_messages or display.long_running_notifications applies to every platform and replaces its default. A config.yaml copied from an older cli-config.yaml.example sets all five globally, and an older first-time hermes setup wrote tool_progress: all; delete those lines to get the per-platform defaults back.

Opt out of either of the kept-on defaults or opt back into verbose progress per platform:

display:
  platforms:
    telegram:
      # Re-enable the tool-progress stream
      tool_progress: new
      # Show "iteration N/M, running: tool" in heartbeats and busy acks
      busy_ack_detail: true
      # Or quiet them entirely
      interim_assistant_messages: false
      long_running_notifications: false

Warning and error notifications (opt-in suppression) Copy Section

Automatic warning and error notifications are shown by default. To suppress
these notifications, enable suppress_warning_notifications globally or for
an individual surface:

display:
  suppress_warning_notifications: true
  platforms:
    telegram:
      suppress_warning_notifications: false

This example suppresses notifications globally while keeping them visible on
Telegram. Omit the setting or use false to preserve normal delivery. Platform
overrides take precedence; null inherits. Invalid values do not enable
suppression.

The setting controls automatic engine warnings, retry/fallback diagnostics,
watchdog and database notices, cron failure notifications, Kanban failure
notifications, background/delegation diagnostics, and adapter-generated error
notices. It applies to messaging platforms, CLI/TUI presentation and API
notification presentation. Classification belongs to the producer: warning-like
text in a user request or an ordinary result is not filtered by its wording.

Suppression changes presentation, not execution. Existing logs, stored diagnostic
content, retry decisions, failure state, scheduler bookkeeping and notification
cursors remain available. A diagnostic-only internal wake (a subagent or credit
failure, a Kanban crash notice) still runs its agent turn — so the agent can act on
the failure and the session history stays consistent — and that turn is billed as
usual; only its unsolicited text, media and streaming presentation are muted. Structured
approval and clarification controls, direct command/API outcomes and requested
results are not converted into success or discarded. API failure flags, status
codes and usage remain truthful even when diagnostic text is hidden.

Cron failure_deliver still selects the destination; the destination's warning
policy determines whether an automatic failure notice is presented there.
Suppressed deliveries are settled without claiming a successful send. Already
admitted deliveries retain their delivery identity and outcome.

Policy is resolved for the owning profile and logical destination. Agent turns
use their turn policy; independent notifications and deferred deliveries evaluate
policy at their own delivery boundary. Already delivered messages are not removed.
Suppression does not fix an underlying failure or add another logging destination.

Progress bubble cleanup (opt-in) Copy Section

Tool-progress messages, the "still working…" heartbeat, and status-callback bubbles can also be auto-deleted after the final response lands. Enable per-platform via display.platforms..cleanup_progress:

display:
  platforms:
    telegram:
      cleanup_progress: true
    discord:
      cleanup_progress: true

Defaults to false. Only platforms whose adapter implements delete_message honor the setting (currently Telegram and Discord). Failed runs skip cleanup so the bubbles remain as breadcrumbs.

Next Steps Copy Chapter

• Telegram Setup
• Discord Setup
• Slack Setup
• Google Chat Setup
• WhatsApp Setup
• WhatsApp Business Cloud API Setup
• Signal Setup
• SMS Setup (Twilio)
• Email Setup
• Home Assistant Integration (plugin catalog)
• Mattermost Setup
• Matrix Setup
• DingTalk Setup
• Feishu/Lark Setup
• WeCom Setup
• WeCom Callback Setup
• Weixin Setup (WeChat)
• BlueBubbles Setup (iMessage)
• Photon Setup (iMessage)
• QQBot Setup
• Yuanbao Setup
• Microsoft Teams Setup
• Teams Meetings Pipeline
• Microsoft Graph Webhook Listener
• LINE Setup
• ntfy Setup
• SimpleX Chat Setup
• Open WebUI + API Server
• Raft Setup
• IRC Setup
• Buzz Setup
• A2A (Agent-to-Agent) Setup
• Webhooks

User Guide Secrets Index (`website/docs/user-guide/secrets/index.md`) Copy Section

Secrets

Hermes can pull API keys from external secret managers at process startup instead of storing them in ~/.hermes/.env. The bootstrap token for the secret manager lives in .env; every other provider key (OpenAI, Anthropic, OpenRouter, etc.) can stay in the manager and rotate centrally.

Supported:

• Bitwarden Secrets Manager — bws CLI, lazy-installed, free tier works.
• 1Password — op:// references via the official op CLI; service-account or desktop session auth.
• Command helper — any CLI vault (keepassxc-cli, secret-tool, pass, custom scripts) via a user-configured helper that prints KEY=VALUE lines.

Multiple sources at once Copy Chapter

You can enable more than one secret source at the same time — for example a team Bitwarden project alongside a personal vault plugin. Sources compose per env var with a deterministic precedence ladder:

1. Your .env / shell wins by default. A source only replaces a pre-existing value when its own override_existing: true is set (Bitwarden defaults to true so central rotation works).
2. Mapped sources beat bulk sources. A source where you explicitly bind env vars to references (an env: map) outranks a source that injects a whole project of secrets implicitly, regardless of ordering.
3. First source wins. Within the same shape, the order of the optional secrets.sources list (or registration order) decides. Later claims on an already-claimed var are skipped — with a startup warning, never silently.

override_existing never lets one source overwrite a var another source already claimed, and no source can ever overwrite another source's bootstrap token (e.g. BWS_ACCESS_TOKEN).

secrets:
  sources: [bitwarden]     # optional explicit ordering
  bitwarden:
    enabled: true
    project_id: "..."

Every credential injected by a source is labelled with its origin — setup flows and hermes model show (from Bitwarden) next to detected keys so you always know where a value came from.

Profiles and shared vaults Copy Chapter

Two orchestrator-level knobs make one shared vault safe across profiles:

• secrets.preserve_existing — a list of env var names whose existing .env / shell value always wins, even against a source with override_existing: true. Use it for per-profile platform secrets (e.g. FEISHU_APP_SECRET) that intentionally differ across profiles while everything else rotates centrally:

  yaml Copy

  secrets:
    preserve_existing: [FEISHU_APP_SECRET, TELEGRAM_BOT_TOKEN]

• Profile aliasing (on by default, secrets.profile_alias: false to disable) — when Hermes runs under a named profile, a vault secret named FOO_ (credential-shaped suffixes only: *_API_KEY, *_TOKEN, *_SECRET, *_KEY, *_PASSWORD) also hydrates the canonical FOO. Store TELEGRAM_BOT_TOKEN_MILLA in the shared project and the milla profile's adapters — which read the fixed name TELEGRAM_BOT_TOKEN — get the right value automatically. A var the vault supplies directly under its canonical name always beats an alias.

Both apply to every source — bundled and plugin — because they live in the orchestrator, not the backends.

Secrets in child processes Copy Chapter

Terminal commands, execute_code sandboxes and no_agent cron scripts run with a sanitized environment: Hermes-managed credentials are stripped, and only variables you declare in terminal.env_passthrough (or a loaded skill's required_environment_variables) are forwarded. A declared variable is forwarded with the owning profile's value — from that profile's .env or its secret sources — even when the profile is served by a multi-profile gateway or the Desktop/dashboard backend and its secrets never entered the process environment. A profile's declared value never reaches another profile's children, and the launch profile's .env credentials are dropped from children that run for a served profile. Provider credentials cannot be declared; see Security → Credential scoping.