Hermes Agent: The Practitioner's Reference (2026)

TL;DR: Hermes Agent is an open-source self-improving AI agent from Nous Research. It runs as a CLI and as a multi-platform messaging gateway, stores a durable identity and persistent memory on disk, aggregates skills that improve with use, and works with any OpenAI-compatible LLM provider — Nous Portal, OpenRouter, Anthropic, GitHub Copilot, z.ai, Kimi, MiniMax, DeepSeek, Qwen Cloud, Hugging Face, Google, xAI/SuperGrok, or your own self-hosted endpoint.¹²¹⁹ The current release is v0.21.5 (tag v2026.9.24, September 24, 2026), a rollup patch on the v0.21 line; What’s New in v0.21.5 covers what changed, and the release sections after it run newest to oldest.⁵² The hardest part for most new users is provider authentication: Hermes ships 39 providers in its static picker list at tag v2026.9.24 and auto-extends that list from 38 bundled provider plugins, plus custom endpoints, and three distinct auth paths (API key in .env, OAuth via hermes model, or custom endpoint in config.yaml).⁵³ The auth model is the thing to learn first — everything else is downstream of which provider is resolved.

Hermes Agent operates as a full agent runtime, not a chat wrapper. It reads your filesystem, executes commands in sandboxed backends, scrapes the web, spawns subagents, runs scheduled cron jobs, talks to Telegram/Discord/Slack/WhatsApp/Signal/Email from a single gateway process, and creates its own skills from experience.¹ The CLI is a terminal UI built on top of a conversation loop in run_agent.py; the gateway is a long-running process that routes messages from messaging platforms through the same conversation loop.³

The difference between casual and expert Hermes usage comes down to five systems. Master these and Hermes becomes a force multiplier:

1. Provider resolution: how auth flows map to API calls
2. Configuration hierarchy: config.yaml + .env + auth.json + SOUL.md + AGENTS.md
3. Tool + toolset system: what the agent can do, gated per platform
4. Skills system: procedural memory the agent creates and evolves
5. Gateway + cron + profiles: running Hermes where you live, not just where you are

Key Takeaways

• Provider auth is three paths, not one. API key in .env, OAuth via hermes model/hermes auth, or custom endpoint in config.yaml. Pick the path that matches your provider, not the one that feels familiar.
• Switching providers is a single command. hermes model interactively walks you through every supported provider including OAuth logins, and /model provider:model switches mid-session without losing history.²
• Two files are the user-editable config surface. ~/.hermes/config.yaml holds settings and ~/.hermes/.env holds secrets. auth.json, SOUL.md, MEMORY.md, and skills/ are managed by Hermes directly — you can edit SOUL.md by hand, but the rest is touched by the agent itself.⁴
• Hermes is the successor to OpenClaw. If you’re migrating, hermes claw migrate imports 30+ categories of state automatically.⁵
• Auxiliary tasks ride your main model by default. Vision, approval classification, compression, and session titles run as separate “auxiliary” LLM calls, and at the tag auto routes every one of them to your main chat model – nothing to configure, but on expensive reasoning models these side tasks add meaningful cost. Point individual auxiliary.<task> slots at cheap fast models when that matters.⁴³⁴

Every section below is grounded in the upstream documentation at hermes-agent.nousresearch.com/docs and the source tree at github.com/NousResearch/hermes-agent. Every factual claim has a footnote pointing at the specific upstream page it came from.

Choose Your Path

How Hermes Works: The Mental Model

Hermes is structured around a single conversation loop that any entry point can invoke. The entry points are the CLI (cli.py), the messaging gateway (gateway/run.py), the ACP adapter for editor integration, the batch runner, and an API server.³ All of them ultimately call AIAgent.run_conversation() in run_agent.py, which:

1. Builds the system prompt from SOUL.md, MEMORY.md, USER.md, skills, context files, and tool guidance via agent/prompt_builder.py (the September 2026 decomposition moved it into the new agent/ package)³
2. Resolves the runtime provider via runtime_provider.py — this is the step that picks your auth, base URL, and API mode³
3. Calls the provider using one of three API modes: chat_completions, codex_responses, or anthropic_messages³
4. Dispatches any returned tool calls through model_tools.py and the central tool registry (tools/registry.py)³
5. Loops until the model produces a final response, then persists the session to SQLite with FTS5³

Understanding this loop matters because every feature — personalities, memory, skills, compression, fallback — attaches to one of these stages. When you’re reading a config key and wondering what it does, the answer is usually “it’s a knob on stage 1, 2, 3, or 4 of the loop above.”

Platform-agnostic core. One AIAgent class serves CLI, gateway, ACP, batch, and API server. Platform differences live in the entry point, not in the agent itself.³ This is why the same slash commands work in the terminal and in Telegram — they’re dispatched from a shared COMMAND_REGISTRY in hermes_cli/commands.py.⁶

The directory structure is the system. Hermes stores everything under ~/.hermes/ (or $HERMES_HOME for non-default profiles):⁴

~/.hermes/
├── config.yaml        # Settings (model, terminal, TTS, compression, etc.)
├── .env               # API keys and secrets
├── auth.json          # OAuth provider credentials (Nous Portal, Codex, Anthropic)
├── SOUL.md            # Primary agent identity (slot #1 in system prompt)
├── memories/          # Persistent memory (MEMORY.md, USER.md)
├── skills/            # Bundled + agent-created + hub-installed skills
├── cron/              # Scheduled jobs
├── sessions/          # Gateway session state
└── logs/              # agent.log, gateway.log, errors.log (secrets auto-redacted)

Every file above has a specific role; none of them overlap. If you’re looking for “where does Hermes store X,” it’s one of these.

What’s New in v0.21.5 (The September 24 Rollup)

Hermes Agent v0.21.5 (tag v2026.9.24, September 24, 2026) is the current release, the third thin rollup on the v0.21.x line: “This tag rolls up the ~460 PRs merged since v0.21.4 into a stable tagged release for downstream consumers”. Curated notes are again deferred to v0.22.0. The operator-facing changes, checked in source at the tag:⁵²⁵³

• Hindsight memory leaves the core tree. The bundled Hindsight provider and the hermes-agent[hindsight] pip extra are gone; Hindsight now installs from the plugin catalog, maintained by Vectorize; the release notes omit this. If your config sets memory.provider: hindsight, hermes update installs the catalog plugin into every profile home that names it, and the first agent start installs it if still missing, unless security.allow_lazy_installs is false (then run hermes plugins install hindsight). Settings, .env keys, and memory data are untouched. See External Memory Providers.
• gateway.multiplex_profiles: false is retired. The gateway rewrites it to true in place and prints a one-time boxed notice. A named profile that must keep its own gateway sets gateway.standalone: true in its own config.yaml; to take one served profile offline, hermes -p <name> gateway stop now parks it without stopping the host. See Messaging Gateway.
• New models in the Nous and OpenRouter pickers: GPT-6 Sol and GPT-6 Luna (each with a -pro variant) and Claude Opus 5.5.
• Plugin compat is unchanged: plugins.allow_deprecated_imports: true still works.

Updating: hermes update or the installer one-liner; Docker and Hermes Cloud images build from nousresearch/hermes-agent:v2026.9.24.⁵²

What’s New in v0.21.4 (The Second Rollup Patch)

Hermes Agent v0.21.4 (tag v2026.9.21, September 21, 2026) is the second deliberately thin rollup on the v0.21.x line. Its own framing: “Patch release. This tag rolls up the ~1,800 PRs merged since v0.21.3 into a stable tagged release for downstream consumers (Docker images, Hermes Cloud, hosted deployments).” The window since v0.21.3: “5,071 non-merge commits” across “5,169 changed files”, “1,812 merged PRs”, and “2,116 closed issues”. By commit count that is the second-largest tag-to-tag window in the project’s history, behind only v0.21.1’s 5,139; by merged PRs it is the largest. The curated story is deferred again, verbatim: “Full curated release notes for this window ship with v0.22.0, which will document everything from v0.21.0 onward” and “Nothing in this window is skipped.” The note does list what it leaves undocumented, and each item below was checked in source at the tag; where an item changes a standing section of this guide, the pointer is inline.⁵⁰⁵¹

• One gateway per host, and Desktop attaches instead of respawning. The ruling is one hermes serve and one hermes gateway run per host per OS user, each multiplexing every profile – enforced by a new host-wide singleton layer: a host lock held for the lifetime of the winning process plus a rendezvous record carrying (pid, createTime), so a second invocation can prove the owner is the same live process and attach instead of binding a second port. Staleness is proved, never assumed, and the Desktop app runs the same idea from its side, attaching to the running host backend instead of spawning a second one. Messaging Gateway carries the mechanics.⁵¹
• Connectors become one backend-owned operation with one setup card. A manage_connections tool call drives a pure-data connection state machine on the backend, and Desktop, TUI, and CLI all render it as the same setup card: a field per missing credential, the card’s verb held until every required field has text. See the Nous free tier subsection.⁵¹
• --format stream-json: machine-readable one-shot runs. hermes chat -q ... --format stream-json emits one JSON object per stdout line for CI runners and orchestrators: a system/init event, then text deltas / tool_use / tool_result events, then one terminal result envelope carrying exit code, final text, and token stats. Diagnostics and the session ID stay on stderr, tool output is capped at 5,000 characters per event, the flag implies --quiet, requires -q or --query-file (exit 2 without one), and cannot be combined with --tui. The hermes chat options table carries the flag.⁵¹
• skills.auto_load pins skills into every session. Names listed under skills.auto_load in config.yaml load fully in every new session – CLI, TUI, gateway, cron, and API alike – resolved once when the prompt is first built. Skills System gains a Pinned Skills subsection.⁵¹
• A decline option for unauthorized DMs. unauthorized_dm_behavior gains a third value beside pair and ignore: decline sends one polite refusal, then goes silent toward that sender for 24 hours. See User Authorization & Pairing.⁵¹
• mcp.discovery_concurrency caps MCP discovery connects. Default 4, 0 = unlimited; every configured server still connects, they just stop arriving all at once. See MCP Integration.⁵¹
• session_search learns time bounds and a recall retry. The discovery shape takes after/before bounds (ISO or relative durations like 7d), and a zero-result multi-word query is retried matching ANY term instead of FTS5’s implicit all-terms AND. See Session Search.⁵¹
• hermes sessions set-journal-mode delete|wal: the offline journal converter. The self-service path for a state.db stuck in the wrong SQLite journal mode – what previously required a hand-run PRAGMA journal_mode=DELETE. Stop the gateway, dashboard, and every CLI first: it refuses while any foreign process holds the database, flips without waiting out openers, and verifies the SQLite header bytes afterward. Windows has no holder scan, so there it refuses until you pass --force after stopping every Hermes process yourself. hermes doctor now points at it. The hermes sessions row in Top-Level Commands carries it.⁵¹
• Desktop: a font setting, one-click engine updates, and plugin uninstall. Settings gains a font-family field persisted per profile at desktop.font_family – it overrides the theme’s sans face across chat and UI, the suggestion list leads with accessibility faces (OpenDyslexic, Atkinson Hyperlegible, Lexend), and empty means the theme decides. The managed local-model runtime shows an “Update engine” button when an update is available, with a failed update staying visible for a direct retry. And the Plugins hub uninstalls a plugin behind a confirm dialog.⁵¹
• Video catalogs: LTX 2.5 and Kling O3. The FAL video plugin adds ltx-2.5 (Lightricks’ open-source audio-video model: native audio, up to 20 s / 4K image-to-video, camera-motion presets, cheap tier – fal rejects clips over 10 s at 1440p/2160p) and kling-o3 (Kuaishou’s frontier family, premium tier: multi-shot native storytelling, optional audio, 3-15 s).⁵¹
• The plugin catalog becomes a shipped directory and a website. The repo’s plugin-catalog/ directory grew from 9 entries at v2026.9.14 to 228 at this tag – one reviewed YAML per plugin, pinned to an exact commit SHA – and the docs site now builds a page per plugin and per author, each rendering the plugin’s README from the pinned commit. The ten community plugins the release names are all catalog entries at the tag. Plugin System carries the details.⁵¹
• And a large fix run across profile/multiplex isolation, cron, kanban, Desktop, and state.db, named by the release only as a category; the curated record of those fixes is v0.22.0’s to write.⁵⁰

The plugin-compat revert still has not landed in this window. COMPAT_MANIFEST.md, compat_manifest.json, and the compat shims are all present at v2026.9.21; the only changes to hermes_cli/plugin_compat.py in the window are a process-wide scan cache (a multiplex gateway discovers plugins once per served profile, and re-parsing every plugin’s source cost ~0.4 s per profile on the boot path) and POSIX-form hit paths on Windows (#112576) – the date gate and the literal-boolean escape hatch are unchanged, so plugins.allow_deprecated_imports: true still keeps affected plugins loading. The compat box in Plugin System carries the current state.⁴²

Updating is unchanged: hermes update (git installs) or the shell installer for fresh ones; Docker and Hermes Cloud images build from this tag (nousresearch/hermes-agent:v2026.9.21).⁵⁰

What’s New in v0.21.3 (The September 14 Patch)

Hermes Agent v0.21.3 (tag v2026.9.14, September 14, 2026) is three more days of main under a two-item note, cut because Cloud agents auto-update to the newest release tag and the remote-gateway sign-in fixes needed to reach them. (1) Remote dashboard sessions no longer get revoked by refresh bursts: both refresh paths on the gateway (the cookie gate and the desktop’s native bearer route) now coalesce concurrent requests carrying the same rotating refresh token into a single flight, so a desktop wake burst can no longer replay an already-rotated token into the Portal’s reuse detection and revoke the whole session – and refresh runs off the event loop, so a slow identity provider no longer freezes /api/status. (2) Long-lived processes stop minting duplicate state.db writer handles: gateway, dashboard/desktop backend, ACP, and CLI readers attach read-only, and in-process writers share the registry handle. Window stats: “1,036 non-merge commits” across “2,642 changed files” and “338 merged PRs”. Everything else is deferred on purpose: the release names what it is not documenting (reasoning-effort pickers on every model picker, OpenRouter OAuth PKCE, HEIF/HEIC/AVIF decoding, a FAL catalog wave, Slack pasted tables and the Agent Sessions API, the state.db WAL refusal on cross-VM filesystems, and more) and commits to the curated record, verbatim: “Full curated release notes for this window ship with v0.22.0, which will document everything from v0.21.0 onward” and “Nothing in this window is skipped.”⁴⁹

And the plugin-compat deadline arrived on schedule. The 2026-09-14 removal that v0.21.1 announced took effect as a date gate in the shipped code, not as a code revert: at tag v2026.9.14, hermes_cli/plugin_compat.py carries COMPAT_REMOVAL_DATE = 2026-09-14, and removal_in_effect() returns true from that date (or as soon as the manifest file is gone), so an affected external plugin is now disabled at load with the red notice. What has NOT happened yet: the revert that actually deletes the old import paths. COMPAT_MANIFEST.md, compat_manifest.json, and the compat shims are all still present at the tag – and still at v2026.9.21 and on main as of September 22 – which is why plugins.allow_deprecated_imports: true still works as an escape hatch: the old paths still resolve once the loader is allowed to proceed. Two sharp edges: the key must be a literal YAML boolean (the code accepts only the boolean True; a quoted string like "true" or "false" is treated as unset, per the source comment “Literal boolean only”), and the hatch dies the moment the revert lands, because the paths themselves disappear. The compat box in Plugin System carries the current state.⁴²⁴⁹

What’s New in v0.21.2 (The state.db Patch Release)

Hermes Agent v0.21.2 (tag v2026.9.11, September 11, 2026) exists first of all to fix what v0.21.0 broke. The release says it plainly: “v0.21.0 shipped a large rewrite of the session store’s connection handling, and for some installs it made state.db fragile: second writers cancelling each other’s locks, healthy databases reported as corrupt, one bad row killing sessions list. This release closes that class and rolls up everything else that landed on main in the four days since v0.21.1.” Unlike v0.21.1’s deliberately thin note, this one documents its own highlights; the window stats are “947 non-merge commits” across “1,869 changed files” and “312 merged PRs” from “140 contributors”, and the curated record of the whole v0.21.x stretch remains v0.22.0’s to write.⁴⁸

• The state.db reliability campaign: six PRs, 44 issues closed. The release’s operator advice comes first, and it should be yours too: if your state.db broke on 0.21.0 or 0.21.1, run hermes doctor – it now names structural damage and full-text-search index damage separately instead of calling everything “FTS write corruption”, and it points at hermes sessions recover --inspect-only (offline, non-destructive, profile-pinned; reports canonical-table readability without creating an output database) when a rebuild is not enough. The root-cause work removes every second writer on the store: profile gateways were writing hosted-room state into the root state.db every 5 seconds, and that coordination now lives in a dedicated shared-state.db, so profile gateways never open the master session store writable; the dashboard opens read-only first; cron’s lifecycle guard goes through the tracked connection registry instead of a raw open() on a live database (which cancels the gateway’s POSIX locks – the classic corrupt-your-SQLite recipe); and doctor --fix refuses a checkpoint it cannot prove is safe. Beyond the writers: FTS-index damage now degrades search and rebuilds the index later instead of fail-closing the whole turn; one corrupt row no longer kills sessions list, export, or insights (bad rows render ? with a warning naming the session); sessions never bind to or read another profile’s database; and a read-only open no longer takes the write lock, so a one-shot hermes behind a busy gateway went from a 4-20 s stall-and-fail to 0.01 s.⁴⁸
• Multi-profile isolation hardening. Since v0.19.0 this guide has repeated the project’s claim that profile routing gives each profile “fully isolated config, skills, memory, and secrets.” At v0.21.2 that promise had holes, now closed: secondary-profile bots inherited the default profile’s allow-lists, adapters could send credentials to the default profile’s host, stdio MCP servers received the default profile’s vault secrets, MEDIA: delivery could attach another profile’s .env/auth.json/state.db, webhook and Feishu callbacks could drift off the routed profile, and secondary profiles could pick up a sibling’s Nous bearer from per-process memos (#107609-#107630). If you run several profiles under one multiplexed gateway, this is the release where the isolation claim actually holds.⁴⁸
• The password-blind credential vault. The agent can now sign in, pay, and fill addresses in the browser from 1Password, Bitwarden, or the local Hermes vault without ever seeing a secret, and two-factor codes come from a saved authenticator key (TOTP: a base32 seed or an otpauth://totp URI; counter-based HOTP is rejected) or are asked for in your UI. Every backend hands the agent the same shape – login metadata plus an opaque namespaced handle (vault_ local, op:, bw:), with the password resolved at fill time only; external managers stay locked until you unlock them for the session, and the master password “is never a tool argument, never argv, never persisted.” This builds on v0.19.0’s SecretSource work, which took provider API keys out of plaintext .env; the vault now does the same for the agent’s browsing credentials.⁴⁸
• A curated, SHA-pinned plugin catalog. hermes plugins browse lists “every curated plugin catalog entry”, hermes plugins search queries the catalog, and hermes plugins install resolves catalog names alongside Git URLs and owner/repo. hermes plugins pack rounds it out with “declarative, shareable plugin sets”: one hermes-pack.yaml pinning a set of plugins to exact commit SHAs, pack install fanning out to ordinary pinned installs with capability consent staying per-plugin, pack export emitting a pack for the current install, and pack show as a dry run. The Plugin System command block carries the new subcommands.⁴⁸
• Nous free tier and guided first launch. Fresh installs get free inference and connectors out of the box with one command to sign in, /login works from inside a chat, and connector tools (Gmail, Linear, Notion, and the rest) are searchable through tool_search. The desktop’s guided first launch sits behind HERMES_GUEST_ONBOARDING=1, and only the literal 1 enables it: the desktop’s own test asserts that 'true', '0', and an empty value all leave it off, and the launch decision is stamped into the spawned backend’s environment so an inherited value never leaks through. See Nous Tool Gateway.⁴⁸
• Desktop backend spawn storms are over. Bot Mode used to spawn or dial one backend per profile on launch and on every roster tick, hovering the Bots roster spawned a backend per row, and a profile switch could spawn a duplicate primary. All of it is fixed in this window.⁴⁸

Updating is unchanged: hermes update from an existing install, or the shell installer for fresh ones.⁴⁸

What’s New in v0.21.1 (The Rollup Patch)

Hermes Agent v0.21.1 (tag v2026.9.7, September 7, 2026) is deliberately thin: a “Patch release” that “rolls up current main since v0.21.0 for tagged deployments and downstream consumers.” The body gives the window stats – “5,139 non-merge commits across 4,364 changed files (+601,014 / -768,419)” and “632 merged PRs” – and then defers the story: “Full curated release notes for this window will ship with v0.22.0.” That makes this the largest single tag-to-tag window in the project’s history (no previous adjacent-tag window exceeds the 2,790 non-merge commits of v2026.7.20..v2026.7.30), shipped under the smallest release note. Until v0.22.0 writes the curated record, the six clusters below are what changes how you operate Hermes at the tag, each verified in source.⁴¹

• The codebase was decomposed, and a plugin-compat clock runs out on September 14. The September 2026 decomposition (PR #102117) split the repo’s large modules into focused files: a new agent/ package holds the conversation loop’s internals (214 top-level modules plus seven subpackages; prompt_builder.py now lives at agent/prompt_builder.py, while run_agent.py remains AIAgent’s home), the CLI’s subcommand parsers moved into a hermes_cli/subcommands/ package (61 modules), the static CANONICAL_PROVIDERS list moved from hermes_cli/models.py to hermes_cli/models_catalog_static.py (the list itself is unchanged: 39 static entries, still auto-extended from 39 bundled provider-plugin directories), and delegate_task split across roughly a dozen tools/delegate_tool_* modules. Internal import paths are not a stable API, so a new COMPAT_MANIFEST.md at the repo root re-exports 1,148 “moved-lazy” public names from their old module paths, each emitting a HermesPluginCompatWarning once per name per process when resolved. The compat layer was temporary, and its removal took effect on schedule on 2026-09-14, six days after the tag – not as a code revert but as a date gate already in the shipped code. Since that date an affected third-party plugin is not loaded: the CLI banner, hermes doctor, and hermes update show a red notice naming the disabled plugin, the desktop shows a one-time modal, and hermes plugins list shows the reason. If you run external plugins, check them: hermes plugins compat <path> prints every file:line with old path -> new path and exits 1 while anything remains (--json for machine-readable output; run it bare to scan the whole installed set). The escape hatch for a plugin whose author has not caught up is plugins.allow_deprecated_imports: true in config.yaml, and it still works: the revert that actually deletes the old import paths still has not landed as of September 22 (verified through tag v2026.9.21 and on main), so the old paths still resolve once the loader is allowed to proceed. The aftermath detail is in What’s New in v0.21.2 above; the Plugin System section carries the current-state box.⁴²
• Gateway conversations no longer rotate on timers, at all. The session-lifecycle doc now states the contract outright: “Inactivity and wall-clock time never rotate a conversation. /new and /reset create an explicit boundary; context compression continues to manage long histories. Legacy timer configuration is ignored. The existing SessionResetPolicy datatype is inert compatibility data, not a runtime policy.” Boundaries are explicit and user-made; if you carried OpenClaw-era session-reset timers through hermes claw migrate, they are now inert data. See Messaging Gateway.⁴³
• MCP authorization grows a device-code path. hermes mcp login <name> gains --flow {browser,device}: browser is the existing PKCE flow, device is an RFC 8628 device-code login for machines where a browser callback is impractical, and the flag overrides the server’s oauth.flow config. The window also hardened the rest of the MCP auth surface: profile ownership is enforced throughout OAuth sessions, malformed OAuth metadata caches are ignored instead of wedging a server, and the desktop relays MCP OAuth through client-local callbacks. Related: -t/--toolsets now also filters which configured MCP servers are spawned at all, so a one-shot hermes -z -t <toolsets> run skips cold-starting servers it does not need. The MCP Integration command block now carries login and reauth [--all], both of which predate this window but had not been documented here.⁴⁴
• Delegation gets honest about background work. Six reliability changes to delegate_task, all read from the delegate tool source at the tag. (1) A background batch returns as ONE completion by default; opting into delegation.independent_completions splits the call into completion units: tasks sharing a group value join and report together, and each ungrouped task reports alone as it finishes. The default is deliberate – the source notes that a per-task flurry of completions “fragmented orchestrators that had no plan for it.” (2) A child’s background processes are killed at its teardown unless the child hands them to the parent with process_manage(action="handoff"); un-handed leftovers are named on the result as orphaned_processes, and child processes that exited without ever being read surface as unread_completions with an output tail. The design stance, per the source docstring: the parent “must hear that from the runtime” rather than trust a child’s claimed “watcher running”. (3) delegation.fallback_providers becomes a real config surface: null inherits the parent chain for unpinned children, [] disables fallback, and a child pinned by provider, endpoint, or model gets no fallback unless this setting declares one. (4) The child fallback chain resolves through the canonical normalizer, so malformed entries are dropped instead of breaking a spawn. (5) A crash mid-unit no longer loses finished children: each finished child of a multi-child unit is durably recorded on the unit’s own row and survives into the recovered result as a partial. (6) Subagents never inherit the 1-hour prompt-cache tier: a delegated child is downgraded to the 5-minute tier, because the 1h tier is priced for a person who steps away, not a burst of parallel children.⁴⁵
• Providers and models. The catalogs pick up OpenAI’s GPT-6 Astra and Astra Pro with -fast/-flex speed-tier variants (“2x price, priority tier” / “0.5x price, flex tier”) on the Nous Portal and OpenRouter catalogs. On the ChatGPT/Codex OAuth route, Astra is account-gated (only live account-scoped discovery may advertise it) and gains an opt-in -900k picker variant that raises the advertised 272K window to a live-verified ~900K; the suffix never goes on the wire. Alongside it: anthropic/claude-fable-5.1, google/gemini-3.7-flash and gemini-3.8-flash, qwen/qwen3.8-max-0902 and qwen3.8-flash, and Meta’s Muse Spark 1.3 family (1M context, contributor variants included) plus a Meta muse-image image-generation provider plugin. Tavily lands as a web search/extract backend (TAVILY_API_KEY; keyless works when Tavily is selected via hermes tools). A managed llama.cpp runtime makes local models a first-class path (official binaries, one supervised llama-server, one-click setup from the desktop), and out-of-tree external-process providers get their own resolution branch. Operationally: the picker’s remote catalogs now refresh every 20 minutes (model_catalog.ttl_minutes, default 20; the legacy ttl_hours key is honored only where a user had set it explicitly).⁴⁶
• Desktop: annotate the page, control the session. The in-app browser gains comment mode: click Annotate, then click any element (or drag a box) on the live page and type a note; saved comments stay as numbered pins and never send a turn by themselves. When you are done, “Add N comments” hands the batch to the composer with a cropped screenshot per pin, and each element comment carries its CSS selector, its markup, and the computed styles that matter for layout, so the agent finds the element in your source instead of guessing from a picture (password and hidden values, and key-shaped attributes, are redacted before markup leaves the page). Larger batches arrive grouped by page region, so twenty-odd comments become a handful of pieces of work that usually touch separate files – which is what makes fanning them out to parallel workers safe. Around it: structured session controls plus session automation controls, drag-to-create sessions, a session import view for foreign coding-agent transcripts, display.resume_last_session (default true: cold start reopens the last chat or page), a first-open consent prompt offering browser.use_real_profile when a Browser pane opens with it off, a built-in optional-skills catalog under Capabilities -> Skills with one-click install, and a new Russian desktop UI locale (the CLI’s 17 locale catalogs are unchanged).⁴⁷

Updating is unchanged: hermes update from an existing install, or the shell installer for fresh ones. The curated record of this window is v0.22.0’s to write; the clusters above are what changes at the tag.⁴¹

What’s New in v0.21.0 (The Pantheon Release)

Hermes Agent v0.21.0 (tag v2026.8.31, August 31, 2026) is the current feature release, and it is the curated record the whole v0.20.x rollup train had been deferring to: “This release rolls up everything from the v0.20.1-v0.20.6 infrastructure patch tags - those windows are fully documented here.” The framing is the sequel to the Herald: “v0.20.0 made Hermes the herald - he spoke, and he carried word to other agents. In v0.21.0 the gods assemble.” The stats line, verbatim: “Since v0.20.0: ~5,800 commits · ~2,475 merged PRs · ~5,680 files changed · ~869,000 insertions · ~135,000 deletions · ~2,100 issues closed · 760+ contributors”.³⁵

The release organizes itself by feature area; so does this summary. Where a feature changes a standing section of this guide, the pointer is inline.

• Bot Mode: your agents become a society, built in. Bot Mode graduates from the bundled hermes-bots plugin of the v0.20.3 window to a default-on part of the desktop app. Every agent profile gets a name, a deterministic avatar face with randomize/lock controls, and a place in a shared roster; you create Discord-style group chats where multiple bots and you talk in one room, @-mention any bot from the composer, and give rooms names and pictures. The sub-catalog includes attributed agent-to-agent message cards, sender-side delivery notices, paint-first hydration for instant wakes, a Routines pane, and a rebuild on the app design system. The release’s own line: “Before, ‘multi-agent’ meant plumbing; now it looks like a chat app full of coworkers.”³⁵
• hermes peer: bot-to-bot DMs between your agents. Any Hermes agent can message any other by handle, across profiles and gateways, from the CLI or from inside a conversation – ask your research bot to hand findings to your coding bot and read the reply where you are. “Replies land in each agent’s canonical Bot Chat, so conversations between agents are durable and inspectable, not fire-and-forget.” The hermes peer command (add/list/remove peers, dm) is in the Top-Level Commands table.³⁵
• Cron jobs that remember. Scheduled jobs stop being goldfish: cron agents load and update persistent memory like every other agent, continuity=true carries each run’s output into the next so a monitor can dedupe against what it already reported, every job gets a durable notepad scratchpad, monitor-mode jobs skip the LLM entirely when nothing changed, reasoning effort can be pinned per job, and cron output can land in a bot’s canonical Bot Chat, where the bot actually responds. The Scheduled Tasks (Cron) section now documents the at-tag mechanics of each.³⁵³⁷
• Live subagent orchestration. delegate_task gains control actions: list running children, steer one mid-flight with a course correction, or stop it early and keep the partial result. Child outputs can be validated against a JSON schema, per-delegation cost is surfaced in results, and the defaults are raised to 250 iterations per subagent and 10 concurrent children (the unified caps that replaced max_async_children in v0.19.0).³⁵³⁸
• The MCP command center. MCP servers and the catalog merge into one desktop page with drag-in “paste anything” import, background health checks that nudge you to re-auth before a tool call fails, a fleet cost/usage overlay (schema token estimates, 30-day usage per server), and hermes:// deep links that install an MCP server with explicit confirmation. See MCP Integration.³⁵
• A CLI power wave. Ctrl+P opens a fuzzy command palette (also reachable as /palette), the /model picker filters as you type, /status shows reasoning mode, pending approvals, and context usage, and the status bar can display live cache-hit %, latency, and tokens/sec with per-field toggles. Plus a global emergency stop, session pin/unpin, rotating composer placeholders, and terminal pets. One naming note: the release bills a dry-run approval checker as hermes approval-check; at the tag that surface is hermes approvals test – no approval-check subcommand exists.³⁵⁴⁰
• The agent drives the desktop’s browser. The in-app browser stops being a window the agent can only look at: Hermes navigates, clicks, and reads it directly, and pages pop out to your system browser with full link context menus.³⁵
• Six new providers and a model catalog wave. Meta Model API (Muse Spark), CommandCode, Tencent TokenPlan, Nebius Token Factory, Ramp Router, and Actual Computer. Three of those (Meta AI, CommandCode, Actual Computer) landed inside earlier rollup windows and were already in the provider matrix; the matrix now adds Tencent TokenPlan, Nebius Token Factory, and Ramp Router, plus the docs’ new Alibaba Token Plan SKU. The catalogs pick up GLM-5.3-Flash, qwen3.8-max/flash, Gemini 3.7 Flash, MiniMax M3 free, Nemotron 3.5 Lightning, and Muse Spark 1.2. Two structural changes ride along: model_overrides in config.yaml lets you patch any model’s context window or pricing without waiting on a release, and providers can now ship as pip-installed packages discovered via entry points; a unified selection-guard registry also warns across every picker surface when a model trains on your data.³⁵³⁶
• Security hardening across the board. Writes to protected agent-instruction files (AGENTS.md, skills, memory stores) now always require approval so a prompt-injected agent cannot quietly rewrite its own standing orders; a deep redaction sweep closes secret-leak gaps across terminal errors, .env reads, checkpoints, and ACP logs; the approval system learns Windows destructive commands; macOS permission grants survive updates via a stable TCC signing identity (hermes desktop --setup-tcc-identity); and the Blender MCP catalog entry and skill were removed after an upstream compromise. See Security Hardening for the at-tag details.³⁵³⁹
• Gateway maturation. Slack gets native live cards (real streaming replies plus opt-in plan/task cards) and outbound link-preview suppression; Telegram gains an inline picker that makes every command and skill searchable via @botname, bypassing Telegram’s command-menu cap; the relay lane matures (native plugin initialization, live-card ops with draft streaming, session-span segmentation, voice-note STT restored); a gateway control socket lets fleet consumers query the gateway and lets updaters pause it gracefully instead of tree-killing it; and the turn-reaper captures wedged worker stacks when the watchdog fires.³⁵
• A skills wave. Eight salvaged productivity skills (document-to-action-items, meeting-action-items, email-inbox-triage, github-issue-to-pr, weekly-review-planning, competitor-news-monitor, product-price-monitor, social-media-content-calendar), HAR-derived API clients (“watch a website once, then call its hidden API directly with no browser”), publish-site, session-librarian, blocked-page-recovery, merge-reconciler, plan-interrogation, and an advisory SKILL.md linter on create.³⁵

Reverted in this window (not shipping): Model Council mode (/council) and the DCP context engine both landed and were reverted; the WS-only gateway server (#94245) was merged then reverted (#96118), so FastAPI remains on the desktop boot path – but the seq-stamped event replay (#94219), lossless desktop reconnect over WebSocket, DID ship. Electron rolled back to 40.10.2. If community coverage of the v0.20.x windows mentioned any of these, they are not in this release.³⁵

Updating is unchanged: hermes update from an existing install, or the shell installer for fresh ones. The rollup subsection under the Herald release below remains the per-tag record of which window landed what.³⁵

What’s New in v0.20.0 (The Herald Release)

Hermes Agent v0.20.0 (tag v2026.8.3, August 3, 2026) was the feature release before v0.21.0 rolled the whole train up; v0.20.1 (August 13) and v0.20.2 (August 16) are stabilization tags on top of it, and v0.20.3 (tag v2026.8.16.2, published August 17), v0.20.4 (tag v2026.8.18, August 18), v0.20.5 (tag v2026.8.19, published August 21), and v0.20.6 (tag v2026.8.27, August 27) keep the rollup train running with feature-bearing windows of their own — see the subsection below. The window since v0.19.0 covers roughly 3,650 commits, 1,400 merged PRs, and 1,200 issues closed across 650+ contributors.⁵⁵

Three changes break what earlier versions of this guide told you to do. Read these before anything else:

• Node 26 is now required. The installer pins NODE_VERSION="26" and refuses older runtimes with “Node.js … is too old (Hermes requires Node >=26).” Installers, heal, and upgrade all enforce it. Note the docs site’s installation page still says Node v22 — the installer script and the release notes are the newer, authoritative sources.⁵⁵
• pip and Homebrew are retired, not merely deprecated. Verbatim: “brew + pip/PyPI wheel channels retired (shell installer / Docker / Nix are the supported channels).” If you are still on a pip or brew install, that path no longer receives releases.⁵⁵
• The default tool-calling iteration limit moved from 90 to 500. Long autonomous runs stopped hitting an artificial wall, and every budget-pressure threshold below is computed against the new ceiling. read_file also defaults to 2,000 lines instead of 500.⁵⁵

The rest of the release:

• Conversational voice. Streaming TTS with barge-in and on-device wake words.⁵⁵
• A2A v1.0. An agent-to-agent protocol plugin, closing the long-running request in issue #514.⁵⁵
• Signed outbound webhooks. hermes webhook was inbound-only before; v0.20.0 adds HMAC-signed outbound lifecycle webhooks for session, turn, and tool events.⁵⁵
• Grounded citations. A new skill with a fact-checking mode.⁵⁵
• Power-user CLI wave. !command runs a shell command instantly without spending a model turn; /init scans the project and writes or updates an AGENTS.md; /diff shows staged, all, or session changes from any surface; /context breaks down what is filling the context window; /focus gives a reduced-output view with hidden-line recovery; Ctrl+S stashes a half-written prompt. hermes import-agent migrates a Claude Code or Codex CLI setup in one command.⁵⁵
• Secrets surface additions. A command-helper secret source that composes with every vault, one-command token rotation with actionable startup errors, an opt-in encrypted break-glass cache for Bitwarden, vault-injected keys scoped per profile home, and ${env:VAR} SecretRef parity between config.yaml and MCP config. The three-path auth model below is unchanged.⁵⁵
• Faster warm start. hermes -w cold start dropped from roughly 14s to 1.8s.⁵⁵
• Desktop became a platform. Artifacts with versioned cards and sandboxed live preview, a Plugin SDK with Kanban as the founding desktop plugin, a quick-entry global hotkey, multiple GUI windows, SSH remote-backend mode, and RFC 8252 native sign-in.⁵⁵

The v0.20.3, v0.20.4, v0.20.5, and v0.20.6 rollups (August 17-27)

The project’s cadence after v0.20.0 was high-frequency tagged rollups, and they were more than stabilization. All four deferred curated notes the same way – each stated that “full curated release notes for this window will ship with v0.21.0” – and v0.21.0 has now delivered them: What’s New in v0.21.0 above is the curated record of this whole stretch (the release confirms the windows “are fully documented here”). The blocks below stay as the contemporaneous per-tag record – they preserve which tag landed what, which the curated notes fold together.^54233035

v0.20.3 (~250 commits, ~125 PRs since v0.20.2):

• MCP 2.x SDK migration, with 2026-07-28 stateless-protocol support. Hermes moves to the current MCP SDK generation and speaks the stateless revision of the protocol.⁵⁴
• Bot Mode ships as a bundled plugin (hermes-bots) carrying the core teammate protocol.⁵⁴
• A CommandCode provider plugin joins the provider catalog.⁵⁴
• Cua Driver 0.20 runtime contracts for computer use, plus subprocess Python runtime ownership hardening (PYTHONHOME/PYTHONPATH isolation).⁵⁴
• Reliability: cron scheduler self-heal (EMFILE recovery, stale-claim reconciliation, wedged-job re-arm), session-handoff data-loss fixes, desktop remote-gateway connection self-healing, and a wave of ecosystem ports (plugin install security scanning, /worktree, /rollback hand-edit preservation, UTF-16 file reads).⁵⁴

v0.20.4 (~146 commits, ~74 PRs since v0.20.3):

• The desktop’s glass surface: matte glass/translucency work with a frost picker and macOS pre-select.⁵⁴
• A tabbed SESSIONS|BOTS sidebar with per-bot hide/unhide, plus Bot Mode group-chat fixes (long-running member turns, Markdown rendering, cross-machine routing).⁵⁴
• NVIDIA SkillEvaluator Tier 1 advisory scanning on skill installs - license and security checks run when you install a skill.⁵⁴
• Cron media-send hardening (configurable timeout, manual-run attachments, missed-fire surfacing), SessionDB event-loop-thread and contention fixes, hermes update parked-branch honesty, and kanban native OS notifications.⁵⁴

v0.20.5 (~746 commits, ~323 PRs since v0.20.4):

• The keyless web tier: web search works on fresh installs with zero API keys - a 5-vendor free rotation with ring failover.²³
• A CLI polish wave: fuzzy /model picker, a Ctrl+P command palette, and a richer /status.²³
• Bot Mode grows up: group-room threads, foldable conversation summaries, blob-face avatars, and PDF/file attachments with drag & drop.²³
• Fleet and worktree tooling: hermes update receipts, hermes update --plan (the release notes call it “fleet --plan verification”; the flag lives on hermes update, not on a fleet command, and per its parser help it will “Show the update plan and exit without changing anything”), and hermes worktree list/prune.²³²⁷
• Cron jobs gain persistent memory and per-job reasoning effort, plus execution-discipline and runtime stall guards driven by the Composio eval findings, multi-question clarify, the opencode-free zero-auth provider, and desktop perf work (paint-first Bot Mode hydration, React Compiler in both renderers).²³

v0.20.6 (tag v2026.8.27, August 27 – ~1,313 commits, ~525 PRs since v0.20.5):

The release describes itself outright as a “Patch release. This tag rolls up the ~525 PRs merged since v0.20.5 into a stable tagged release for downstream consumers”, and its own description puts the window at ~1,313 commits across ~1,557 files (+177,113 / −21,682) – ~525 merged PRs.³⁰ The headline items from that description:

• Consent-gated real-profile browsing – local browsing can use your default Chromium profile, with a Windows close-with-approval flow.³⁰
• The desktop Browser gets its own OS window, plus a managed SSH remote-update engine and a fleet profile rail.³⁰
• Remote MCP catalog expansion: 50+ live-verified vendor-hosted servers, including Cloudflare, Grafana Cloud, Better Stack, and Railway.³⁰
• Opt-in OS-keychain encryption for stored secrets – no more per-launch macOS Keychain prompts.³⁰
• New models across the pickers: GLM-5.3-Flash, MiniMax M3 free, and MiniMax H3 Max video.³⁰
• TTL result caching for web_search/web_extract and multi-query tool_search with stemming.³⁰
• Lean-tail compression is now the default – the Context Compression section below documents the at-tag config.³⁰³¹
• Terminal backends became pluggable – see Terminal Backends.³⁰³²
• Updater and fleet honesty: updaters pause gateways over the control socket instead of tree-killing them, and image/package-managed installs refuse unsafe in-place updates.³⁰
• Cron durable-incident acks with clearer code-skew failures, Slack link-unfurl controls, and shared Docker container identities.³⁰

Updating is unchanged: hermes update from an existing install, or the shell installer for fresh ones.⁵⁴²³³⁰

What’s New in v0.19.0 (The Quicksilver Release)

Hermes Agent v0.19.0 (tag v2026.7.20, July 20, 2026) is named for the messenger god’s own speed: the spine of the release is raw responsiveness, with an ~80% cut in first-turn time-to-first-token on every platform. Around that spine sit terminal billing, password-manager secret sources, smart approvals by default, observable subagents, and crash-proof response delivery. The window since v0.18.0 is the project’s largest yet: ~2,245 commits, ~1,065 merged PRs, ~3,300 issues closed, and 450+ community contributors.⁵⁶

• ~80% faster to first token, everywhere. Cold submit→dispatch dropped from ~4.3s to ~0.9s across the CLI, gateway, TUI, desktop, and cron alike — Discord capability detection moved off the critical path, the Ollama probe is skipped for known non-Ollama providers, and blocking work was removed from agent init. Perceived latency got its own pass: reasoning models now stream their thinking live by default (display.show_reasoning is ON), and the response box paints per token instead of per line.⁵⁶
• Desktop and TUI rendering waves. The desktop app took a ~20-PR speed overhaul: 14× less CPU in the streaming-markdown splitter via incremental block lexing, virtualized review-pane diffs, snappy session switching on large transcripts, and no more per-token sidebar and tool-row re-renders. The TUI now renders streamed markdown incrementally per block.⁵⁶
• pip and Homebrew installs are deprecated. Both paths were flagged as “unsupported legacy” installs, with removal planned. That removal has since happened in v0.20.0 — the brew and pip/PyPI wheel channels are retired, leaving the shell installer, Docker, and Nix as the supported channels.⁵⁶⁵⁵
• Secrets can come from your password manager. A new pluggable SecretSource interface fetches secrets from Bitwarden and 1Password (op:// references) at load time, with multiple vaults enabled simultaneously, deterministic precedence, conflict warnings, and per-variable provenance — API keys no longer have to live in a plaintext .env. Future vault providers drop in as plugins.⁵⁶
• Smart approvals are now the default. When Hermes wants to run a flagged command, an independent LLM reviewer assesses it instead of prompting you for every one — and each verdict covers only that exact command. User-defined deny rules block matching commands even under YOLO mode, /deny <reason> relays your refusal reason so the agent course-corrects, and the plugin pre_tool_call approve action (re-landed with rule keys) escalates a tool call to a human gate.⁵⁶
• Terminal billing: /subscription and /topup. Manage your Nous Portal plan without leaving the terminal — see your plan and remaining allowance, preview exactly what an upgrade costs or when a downgrade takes effect, and apply it with undo. The desktop app gains a matching billing settings tab.⁵⁶
• Watch subagents work; never lose a finished answer. delegate_task dispatches return live transcript files you can tail -f the moment subagents launch — every tool call, result, and streamed reply, one human-readable log per child. Background delegation completions are durable across restarts, and final gateway responses are recorded in a delivery-obligation ledger in state.db and redelivered on the next boot if the gateway dies mid-send. The max_async_children config option is deprecated in favor of unified delegation concurrency caps.⁵⁶
• One gateway, many profiles. A single multiplexed gateway sharing one bot token can route specific guilds, channels, or threads to different profiles — each with fully isolated config, skills, memory, and secrets — with a GATEWAY_MULTIPLEX_PROFILES override. The routing index moved into state.db; sessions.json is now an optional legacy mirror.⁵⁶
• Providers and models wave. Fireworks AI lands first-class (cost estimation, #2 slot in the provider picker), joined by DeepInfra and Upstage Solar. The catalogs add GPT-5.6 (Sol/Terra/Luna + Pro, wired end-to-end), grok-4.5 (GA), kimi-k3 (kimi-k2.x retired), and fully wired Claude Sonnet 5. A per-provider enabled: false flag and excluded_providers config scrub unused providers from /model pickers and resolution.⁵⁶
• Reasoning effort becomes a dial. New max and ultra effort tiers land across every surface, with per-model overrides in config, per-slot effort in MoA presets (advisors think hard, the synthesizer stays fast), per-task effort for auxiliary models, and a session-scoped /reasoning in the CLI.⁵⁶
• CLI and MCP surface. hermes sessions export writes Markdown, Quarto, HTML, prompt-only, and Hugging Face trace formats with an opt-in --redact scrub; /model --once gives a one-turn model override; slash-skill invocations stack (/skill-a /skill-b do XYZ); --safe-mode aids troubleshooting; hermes config get/unset round out config management; hermes serve becomes a true headless backend; and MCP tools adopt the mcp__server__tool naming convention.⁵⁶

If you are upgrading from v0.18.x, two changes deserve attention before anything else: a pip or Homebrew install now warns as unsupported legacy (migrate to the one-line installer), and max_async_children is deprecated in favor of the unified delegation concurrency caps. Everything else is additive — the headline reasons to upgrade are the ~80% first-turn latency cut, smart approvals, and the delivery ledger that makes finished answers crash-proof.

What’s New in v0.18.0 (The Judgment Release)

Hermes Agent v0.18.0 (tag v2026.7.1, July 1, 2026) is named for judgment: the agent verifying its own work instead of claiming success, and ensemble reasoning you can actually inspect. It also closes the entire P0/P1 backlog — roughly 692 highest-priority items resolved in twelve days.²²

• Mixture-of-Agents as a first-class model. MoA is now selectable like any other model across all interfaces, and ensemble reasoning is visible: each reference model’s full output renders as its own labelled block with live answer streaming — you can watch the ensemble think instead of getting an opaque merged answer.²²
• Completion contracts for /goal. The agent verifies its own work by running the project’s checks before reporting a goal complete, rather than claiming success — judgment applied to itself.²²
• /learn — describe anything into a skill. Turn a workflow into a reusable skill by describing it; generated skills comply with the repo’s CONTRIBUTING.md conventions automatically.²²
• /journey timeline. A visual history of memory and skills over time, with editing, plus a memory graph on desktop.²²
• Background subagent fan-out. Delegate multiple tasks that run concurrently without blocking the conversation — the v0.17.0 single background subagent becomes a fleet.²²
• Desktop Projects. First-class coding Projects with a project/repo/lane organization model.²²
• Scale-to-zero gateway. Gateways can go dormant when idle and coordinate drains for seamless deployments — meaningful for anyone running Hermes as an always-on service.²²
• Google Vertex AI support. Gemini access through GCP service accounts with automatic OAuth2 token refresh, joining the provider catalog.²²
• /prompt editor command. Opens $EDITOR for composing multi-line prompts instead of fighting the input line.²²

If you are upgrading from v0.17.x, nothing here breaks the CLI. The headline reasons to upgrade are completion contracts (goals that verify themselves), first-class MoA with inspectable ensembles, and /learn for skill capture.

What’s New in v0.17.0 (The Reach Release)

Hermes Agent v0.17.0 (tag v2026.6.19, June 19, 2026) is named for how far the agent now reaches — new messaging channels, new model providers, and deeper desktop and dashboard control. It is additive over v0.16.x; the CLI surface is unchanged.²¹

• New messaging channels. iMessage now works without a Mac relay via Photon Spectrum (device-code OAuth, hermes photon login); the WhatsApp Business Cloud API is an official Meta adapter that replaces the bridge-process requirement; SimpleX gains groups, native attachments, text batching, and auto-accept; and Raft joins as a bundled platform plugin with a privacy-by-contract wake-channel design.²¹
• New models and providers. The catalog adds z-ai/glm-5.2 (1M context), anthropic/claude-fable-5, laguna-m.1, nemotron-3-ultra, and grok-composer-2.5-fast (Cursor’s model via xAI OAuth, 200k context). The xAI default moved to grok-build-0.1, and Anthropic adaptive models now follow the modern thinking contract (they never send a reasoning field).²¹
• Desktop and dashboard. Desktop adds background subagents with live “watch-windows” streaming delegated activity (delegate_task(background=true)), a Composer model selector, rebindable keyboard shortcuts, native OS notifications, per-thread composer drafts, VS Code Marketplace themes, and Japanese + Traditional Chinese UI. The dashboard adds a full profile builder (model/skills/MCPs without editing config.yaml), a global profile switcher, a reworked Skills Hub with a security scan, Automation Blueprints (parameterized templates across form, slash command, conversation, and docs), and a secure login that returns 401 behind the OAuth gate.²¹
• Skills and tools. image_generate can now edit and transform a source image, not only create one from scratch, across every supported image provider; the memory tool gained an operations array for atomic batch add/replace/remove in a single call; a new simplify-code skill runs a parallel three-agent review-and-cleanup pass gated by a Chesterton’s-Fence risk tier; and a boolean write_approval replaces the tri-state write_mode.²¹
• Architecture. Background subagents return a handle immediately and re-enter their result as a new turn; an MCP elicitation handler allows mid-tool-call confirmation, and late-connecting MCP tools are exposed between turns (cache-safe); cron becomes a pluggable CronScheduler with a Chronos managed-cron provider; and a new Managed scope (/etc/hermes) lets an administrator pin user-immutable config, alongside a Gateway-Gateway relay for multi-gateway topologies.²¹
• New commands. /version, /billing (interactive terminal billing), hermes photon login (iMessage auth), and hermes curator run --consolidate — consolidation is now opt-in, so routine background curation costs zero tokens.²¹
• Security. v0.17.0 closes a shell-escape denylist bypass, fails closed on missing approval modules and own-policy gateway adapters, sanitizes the environment for cron job-script subprocesses, redacts secrets in request debug dumps, screens MCP stdio configs for exfil patterns, and bumps urllib3 and PyJWT to clear CVEs.²¹

If you are upgrading from v0.16.x, nothing here breaks the CLI; it is new channels, models, and surfaces around the same agent. The relay-free iMessage and official WhatsApp adapters and the administrator Managed scope are the headline reasons to upgrade.

What’s New in v0.16.0 (The Surface Release)

Hermes Agent v0.16.0 (tag v2026.6.5, June 5, 2026) is named for the new surfaces it puts in front of the CLI-first agent. The headline is that Hermes is no longer terminal-only.²⁰

• Native desktop app. Hermes Desktop is a new Electron app for macOS, Linux, and Windows with one-click install and in-app self-update. It gives you a streaming chat window, drag-and-drop files, clipboard image paste, a Cmd+K palette, a session list with archive and search, and a status-bar model picker. It can connect to a remote Hermes gateway over a secure WebSocket, authenticating via OAuth or username/password, with per-profile remote hosts and concurrent multi-profile sessions linked by cross-profile @session references. The desktop UI also ships a full Simplified Chinese (简体中文) translation through a typed i18n layer (display.language; English remains the default).²⁰
• Browser admin panel. The local web dashboard graduated from a status view into a full administration panel: an MCP catalog with enable/disable toggles, credential management, webhook and hook creation, memory configuration, gateway controls, and a System page with check-before-update plus one-click Debug Share. A new Channels page configures every gateway messaging platform (Telegram, Discord, Slack, and the rest) from the browser. Auth is now pluggable: username/password login, a generic self-hosted OIDC provider, hermes dashboard register for a self-hosted OAuth client, and refresh-token session rotation.²⁰
• New CLI and slash commands. /undo [N] backs up the last N user turns with prefill and soft-delete, and works in the CLI, the TUI, and across messaging platforms. A configurable default interface (cli vs tui) lands with a --cli override; the TUI gains a unified /model command and a Sessions overlay. hermes portal is a human-readable alias for the Nous Portal onboarding flow, with new Quick Setup vs Full Setup first-run paths, and two diagnostics arrive: hermes prompt-size and hermes sessions optimize.²⁰
• New models and providers. The picker adds deepseek-v4-flash, MiniMax-M3 (1M context, native MiniMax providers), qwen3.7-plus (Nous + OpenRouter), and gemini-3.5-flash (Gemini OAuth + API key). A first-class xAI Grok OAuth provider joins the desktop launcher, the model picker became fuzzy across every surface, multi-endpoint providers group under one row, and catalog refresh moved from daily to hourly.²⁰ (v0.21.1 has since moved the cadence again: the picker’s remote catalogs refresh every 20 minutes, model_catalog.ttl_minutes.⁴⁶)
• Leaner skills and progressive disclosure. The default skill set dropped redundant and dead skills (Spotify moved to a native plugin, Linear to hermes mcp install linear, and several stale entries were removed), moved more into optional, and added an environments: frontmatter relevance gate (kanban/docker/s6) that keeps context-specific skills out of the index until requested. NVIDIA/skills is now a default trusted Skills Hub tap alongside OpenAI, Anthropic, and HuggingFace. MCP and plugin tools gained progressive (scoped) tool disclosure, and an MCP bug that reported false OAuth success when no token was obtained is fixed.²⁰
• Security. v0.16.0 pins patched Starlette (≥1.0.1) for CVE-2026-48710 (BadHost), moves SSRF URL checks off the event loop in async paths, strips the Bedrock inference bearer token from subprocess env, adds bws_cache.json to the file-safety read guard, adds docker restart/stop/kill to the dangerous-pattern list, and sanitizes invisible-unicode in vetted skill content. The release closed 2 P0 and 62 P1 issues, 16 of them security-tagged.²⁰

If you are upgrading from v0.15.x, none of this is a breaking change to the CLI itself; it is additive surfaces and providers around the same agent. The desktop app and admin panel are the reason to upgrade if you want to run Hermes for non-terminal users or administer a remote gateway from a browser.

What’s New in v0.14.0 (The Foundation Release)

v0.14.0 is less about one headline feature and more about reducing setup drag while widening where Hermes can run.¹⁹ The main operational changes:

• Install and startup are lighter. pip install hermes-agent works from PyPI, heavy adapters lazy-install on first use, and the launch path defers enough work to cut cold start by roughly 19 seconds. (v0.19.0 has since deprecated pip installs — see Installation.)
• Subscriptions can become local API endpoints. hermes proxy turns OAuth-backed providers such as Claude Pro, ChatGPT Pro, and SuperGrok into an OpenAI-compatible local endpoint for tools like Codex, Aider, Cline, and Continue.
• Gateway reach expands. LINE and SimpleX Chat join the gateway (the docs’ platform comparison table lists 28 platforms at tag v2026.8.31; the Messaging Gateway section states what that number counts), Microsoft Teams is wired end-to-end, Discord history backfill is on by default, and Telegram/Discord clarify prompts now use native buttons.
• Write-time verification improves. After edits, Hermes can surface per-turn file-mutation summaries and language-server semantic diagnostics before the next turn, which moves it closer to evidence-driven agent work.
• Desktop and media tooling broaden. computer_use works through cua-driver for non-Anthropic providers, video_generate is unified behind pluggable backends, and vision_analyze sends raw pixels to models that can actually see.

Installation

The one-line installer is the supported install path. It handles Python, uv, Node.js, ripgrep, ffmpeg, the repo clone, the virtual environment, and the global hermes command.⁷

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

pip and Homebrew installs are deprecated as of v0.19.0. The PyPI package that v0.14.0 introduced (pip install hermes-agent) and the Homebrew formula are now flagged as “unsupported legacy” installs — every surface warns (without blocking) when Hermes detects one, and removal of PyPI/Homebrew publishing is planned. If you installed via pip or brew, migrate to the installer above.⁵⁶

Works on Linux, macOS, WSL2, and Android/Termux (the installer auto-detects Termux and switches to a tested Android bundle).⁷ Native Windows is now a Tier 1 platform rather than the early beta v0.14.0 shipped — install it with iex (irm https://hermes-agent.nousresearch.com/install.ps1). One caveat the docs are explicit about: macOS support is Apple Silicon only, and Intel Macs are unsupported.⁵⁵ Historically, v0.14.0 added native Windows support in early beta via a PowerShell installer, but WSL2 remains the safer recommendation for production use until the Windows path matures.¹⁹

After it finishes:

source ~/.bashrc    # or ~/.zshrc
hermes              # Start chatting

The only prerequisite is git. The installer auto-provisions Python 3.11 via uv (no sudo required), Node.js 26 (for browser automation and the WhatsApp bridge), ripgrep, and ffmpeg. Node 26 is a hard floor as of v0.20.0 — the installer refuses anything older and installs a Hermes-managed Node instead.⁵⁵⁷

Verify the install

hermes --version    # Check version (global flag; there is no `version` subcommand)
hermes doctor       # Diagnose config/dependency issues
hermes status       # Show current configuration + auth state
hermes dump         # Copy-pasteable setup summary for debugging

hermes doctor tells you exactly what’s missing and how to fix it.⁷ hermes dump is the diagnostic command to paste into a GitHub issue or Discord thread when asking for help — it’s a plain-text summary of your entire setup with secrets redacted.⁸

Manual installation

If you need full control — custom Python version, specific extras, Nix/NixOS integration — the manual flow is documented step-by-step in the upstream installation guide.⁷ Key optional extras you can combine with uv pip install -e ".[<extras>]":

Termux install command is different — it uses pip with a constraints file, not uv pip:

python -m pip install -e ".[termux]" -c constraints-termux.txt

This is because .[all] on Android pulls faster-whisper via the voice extra, which depends on ctranslate2 wheels that aren’t published for Android.⁷

Authentication & Providers

At tag v2026.9.7, hermes_cli/models_catalog_static.py carries 39 static CANONICAL_PROVIDERS entries at line 311 (the September 2026 decomposition moved the list out of hermes_cli/models.py; the entries themselves are unchanged, v0.21.0’s tencent-tokenplan included) and auto-extends that list from plugins/model-providers/ (39 bundled directories; nine of them – actual, alibaba-coding-plan, commandcode, deepinfra, meta-ai, nebius-token-factory, opencode-free, router, upstage – have no static entry and are absorbed by the auto-extension because they use the default api_key auth type). The docs providers page tables 45 cloud and subscription providers plus a custom-endpoint row, and separately walks through local and self-hosted servers (Ollama, vLLM, SGLang, llama.cpp, LM Studio, LiteLLM, ClawRouter, and any OpenAI-compatible endpoint).²⁶ At tag v2026.9.24 the static list still holds 39 entries, but plugins/model-providers/ holds 38 directories: the keyless opencode-free provider was removed on September 18 because OpenCode’s free tier now rejects anonymous traffic from outside its own client.⁵³ Custom endpoints and three distinct auth paths sit on top of that. Here is the whole auth surface, organized by path so you can find the one that matches what you have.

The Three Auth Paths

Every provider in Hermes fits into one of three authentication patterns:

Path 1 — API key in .env. Put your key in ~/.hermes/.env and Hermes reads it on startup. Used by OpenRouter, AI Gateway, z.ai/GLM, Kimi/Moonshot, MiniMax (and MiniMax China), Alibaba Cloud/DashScope, Kilo Code, OpenCode Zen, OpenCode Go, DeepSeek, Hugging Face, Google/Gemini, and most third-party providers.² Since v0.19.0, the key no longer has to sit in a plaintext file: a pluggable SecretSource interface can fetch secrets from Bitwarden or 1Password (op:// references) at load time, with multiple vaults enabled simultaneously, deterministic precedence, conflict warnings, and per-variable provenance — .env remains the fallback. (This is distinct from v0.15.0’s Bitwarden Secrets Manager bootstrap token, which consolidated provider keys behind one token; SecretSource replaces the plaintext file itself, and future vault providers drop in as plugins.)⁵⁶

Path 2 — OAuth via hermes model or hermes auth. Launches a device code flow, opens a browser, stores credentials in ~/.hermes/auth.json (and can import existing credentials from tools like Claude Code or Codex CLI). Used by Nous Portal, OpenAI Codex (ChatGPT account), GitHub Copilot, and Anthropic (Claude Pro/Max).²

Path 3 — Custom endpoint in config.yaml. For any OpenAI-compatible API — Ollama, vLLM, SGLang, llama.cpp, LM Studio, LiteLLM proxy, Together AI, Groq, Azure OpenAI, or your own self-hosted server. Configured once via hermes model → Custom endpoint, then persisted to config.yaml.²

The Full Provider Matrix

This matrix covers the providers the docs page tables, with the exact setup flow for each; the picker at the tag lists more than the docs do (see the count above), and anything OpenAI-compatible fits through the custom-endpoint row.²²⁶

As of v0.19.0 you can also scrub providers you don’t use: a per-provider enabled: false flag and an excluded_providers config key remove them from /model pickers and built-in provider resolution.⁵⁶

Anthropic: Three Auth Methods

Anthropic gets its own section because Hermes supports three distinct paths into Claude, and picking the right one matters. From the upstream docs:²

# Method 1: API key (pay-per-token)
export ANTHROPIC_API_KEY=***
hermes chat --provider anthropic --model claude-sonnet-4-6

# Method 2: OAuth through hermes model (preferred)
# Uses Claude Code's credential store when available
hermes model

# Method 3: Manual setup-token (fallback/legacy)
export ANTHROPIC_TOKEN=***
hermes chat --provider anthropic

# Auto-detect Claude Code credentials
hermes chat --provider anthropic   # reads Claude Code files automatically

When you choose Anthropic OAuth through hermes model, Hermes prefers Claude Code’s own credential store over copying the token into ~/.hermes/.env. That keeps refreshable Claude credentials refreshable.² If you already use Claude Code on the same machine, this is the cleanest path.

To pin Anthropic permanently in config.yaml:

model:
  provider: "anthropic"
  default: "claude-sonnet-4-6"

--provider claude and --provider claude-code also work as shorthand for --provider anthropic.²

GitHub Copilot: Two Modes

Copilot is supported in two modes: direct Copilot API (recommended) and Copilot ACP (which spawns the local Copilot CLI as a subprocess).²

# Direct Copilot API
hermes chat --provider copilot --model gpt-5.4

# Copilot ACP (requires the Copilot CLI in PATH + an existing copilot login)
hermes chat --provider copilot-acp --model copilot-acp

Authentication is checked in this order, per the upstream docs:² 1. COPILOT_GITHUB_TOKEN environment variable 2. GH_TOKEN environment variable 3. GITHUB_TOKEN environment variable 4. gh auth token CLI fallback 5. OAuth device code login via hermes model

Token type matters. The Copilot API does not support classic Personal Access Tokens (ghp_*). Supported types are OAuth tokens (gho_*), fine-grained PATs (github_pat_* with Copilot Requests permission), and GitHub App tokens (ghu_*). If your gh auth token returns a ghp_* token, use hermes model to authenticate via OAuth instead.²

Chinese AI Providers (First-Class Support)

Hermes has built-in support for z.ai/GLM, Kimi/Moonshot, MiniMax (global + China endpoints), and Alibaba Cloud with dedicated provider IDs.²

# z.ai / ZhipuAI GLM
hermes chat --provider zai --model glm-5                 # Requires: GLM_API_KEY

# Kimi / Moonshot AI
hermes chat --provider kimi-coding --model kimi-for-coding   # Requires: KIMI_API_KEY

# MiniMax (global)
hermes chat --provider minimax --model MiniMax-M2.7          # Requires: MINIMAX_API_KEY

# MiniMax (China)
hermes chat --provider minimax-cn --model MiniMax-M2.7       # Requires: MINIMAX_CN_API_KEY

# Alibaba Cloud / DashScope (Qwen)
hermes chat --provider alibaba --model qwen3.5-plus          # Requires: DASHSCOPE_API_KEY

Base URLs can be overridden with GLM_BASE_URL, KIMI_BASE_URL, MINIMAX_BASE_URL, MINIMAX_CN_BASE_URL, or DASHSCOPE_BASE_URL environment variables.²

Z.AI auto-detects the endpoint. When using the z.ai/GLM provider, Hermes probes multiple endpoints (global, China, coding variants) to find one that accepts your API key. The working endpoint is cached automatically — no GLM_BASE_URL needed for most users.²

xAI (Grok) automatically enables prompt caching. When the base URL contains x.ai, Hermes sends the x-grok-conv-id header with every request to route to the same server within a conversation session, reusing cached system prompts and history.² Automatic; no config needed.

The hermes auth Command

hermes auth is the credential management command for pools and OAuth credentials.⁶

hermes auth                              # Interactive wizard
hermes auth list                         # Show all credential pools
hermes auth list openrouter              # Show one provider's pool
hermes auth add openrouter --api-key sk-or-v1-xxx
hermes auth add anthropic --type oauth
hermes auth remove openrouter 2          # Remove by index
hermes auth reset openrouter             # Clear cooldowns

Credential pools are how you rotate multiple API keys or OAuth tokens for the same provider — useful for distributing rate limits across multiple keys without changing code.⁶ The legacy hermes login / hermes logout commands have been removed; use hermes auth instead.⁶

Custom & Self-Hosted Endpoints

Hermes works with any OpenAI-compatible API endpoint. If a server implements /v1/chat/completions, you can point Hermes at it.²

Interactive setup (recommended):

hermes model
# Select "Custom endpoint (self-hosted / VLLM / etc.)"
# Enter: API base URL, API key, Model name

Manual config.yaml:

model:
  default: your-model-name
  provider: custom
  base_url: http://localhost:8000/v1
  api_key: your-key-or-leave-empty-for-local

Both approaches persist to config.yaml, which is the single source of truth for main-model, provider, and base URL.² The legacy env vars OPENAI_BASE_URL and LLM_MODEL are no longer read for main-model configuration — use hermes model or edit config.yaml directly.² (OPENAI_BASE_URL + OPENAI_API_KEY are still honored as a fallback for the auxiliary provider: "main" routing path, so don’t delete them blindly if you’re using them there.)⁴

Switching custom endpoints mid-session:

/model custom:qwen-2.5             # Custom endpoint with explicit model
/model custom                      # Auto-detect the model from the endpoint
/model custom:local:qwen-2.5       # Named custom provider "local"
/model custom:work:llama3          # Named custom provider "work"
/model openrouter:claude-sonnet-4  # Back to a cloud provider

/model custom (bare, no model name) queries your endpoint’s /v1/models API and auto-selects the model if exactly one is loaded — useful for local servers running a single model.²

Local LLM Servers (Setup Templates)

The upstream docs have full setup guides for Ollama, vLLM, SGLang, llama.cpp, and LM Studio. Here are the key commands you’ll actually run. Each is designed to produce a working endpoint that Hermes can point at.²

Ollama — easiest local path, zero config:

ollama pull qwen2.5-coder:32b
OLLAMA_CONTEXT_LENGTH=32768 ollama serve   # Raise from 4k default
hermes model   # Custom endpoint → http://localhost:11434/v1 → qwen2.5-coder:32b

Critical Ollama gotcha: Ollama defaults to very low context lengths (4,096 tokens under 24GB VRAM). You must raise it via OLLAMA_CONTEXT_LENGTH or a Modelfile — the OpenAI-compatible API does not accept context length from the client, so Hermes cannot set it for you.² For agent use, set at least 16k–32k.

vLLM — high-performance GPU serving:

pip install vllm
vllm serve meta-llama/Llama-3.1-70B-Instruct \
  --port 8000 \
  --max-model-len 65536 \
  --tensor-parallel-size 2 \
  --enable-auto-tool-choice \
  --tool-call-parser hermes

Tool calling requires --enable-auto-tool-choice and --tool-call-parser <name>. Supported parsers: hermes (Qwen 2.5, Hermes 2/3), llama3_json, mistral, deepseek_v3, deepseek_v31, xlam, pythonic. Without these flags, tool calls will come back as plain text.²

SGLang — fast serving with RadixAttention for KV cache reuse:

pip install "sglang[all]"
python -m sglang.launch_server \
  --model meta-llama/Llama-3.1-70B-Instruct \
  --port 30000 \
  --context-length 65536 \
  --tp 2 \
  --tool-call-parser qwen

SGLang gotcha: Default max_tokens is 128. Set --default-max-tokens on the server or configure model.max_tokens in config.yaml if responses get cut off.²

llama.cpp / llama-server — CPU and Apple Silicon Metal:

./build/bin/llama-server \
  --jinja -fa \
  -c 32768 \
  -ngl 99 \
  -m models/qwen2.5-coder-32b-instruct-Q4_K_M.gguf \
  --port 8080 --host 0.0.0.0

--jinja is required for tool calling. Without it, llama-server ignores the tools parameter entirely and the model tries to call tools by writing JSON in its response text — which Hermes can’t parse as actual tool calls.²

LM Studio — desktop app with GUI:

Start the server from the LM Studio app (Developer tab → Start Server), or via CLI: lms server start (starts on port 1234) and lms load qwen2.5-coder --context-length 32768.² Then point hermes model at http://localhost:1234/v1.

Critical LM Studio gotcha: LM Studio reads context length from model metadata, but many GGUF models report 2048 or 4096 defaults. Always set context length explicitly in the LM Studio model settings — click the gear icon next to the model picker, set “Context Length” to at least 16384 (preferably 32768), and reload the model.²

Named Custom Providers

If you work with multiple custom endpoints (a local dev server and a remote GPU server, for example), define them as named custom providers in config.yaml:²

custom_providers:
  - name: local
    base_url: http://localhost:8080/v1
    # api_key omitted — Hermes uses "no-key-required" for keyless local servers
  - name: work
    base_url: https://gpu-server.internal.corp/v1
    api_key: corp-api-key
    api_mode: chat_completions      # optional, auto-detected from URL
  - name: anthropic-proxy
    base_url: https://proxy.example.com/anthropic
    api_key: proxy-key
    api_mode: anthropic_messages    # for Anthropic-compatible proxies

Then switch between them mid-session with the triple syntax:

/model custom:local:qwen-2.5
/model custom:work:llama3-70b
/model custom:anthropic-proxy:claude-sonnet-4

You can also select named custom providers from the interactive hermes model menu.²

Pluggable Provider Architecture (v0.13.0+)

v0.13.0 ships a ProviderProfile ABC plus a plugins/model-providers/ directory so third-party inference providers can drop in without core modifications.¹⁸ If a provider speaks an OpenAI-, Anthropic-, or Codex-compatible API mode, you can implement a ProviderProfile subclass that declares the auth path, base URL, model catalog, and caching headers; Hermes resolves it through the same runtime_provider.py path the built-in providers use. This is the architectural change behind the v0.13.0 provider expansion: instead of editing core code to add a provider, you ship a plugin.

OpenAI-Compatible Local Proxy (v0.14.0+)

hermes proxy exposes an OpenAI-compatible local endpoint backed by the OAuth provider Hermes is already signed into — Claude Pro, ChatGPT Pro, SuperGrok, or another compatible configured provider.¹⁹ That means tools expecting an OpenAI-style API, including Codex CLI, Aider, Cline, Continue, or custom scripts, can reuse your subscription-backed Hermes auth without a separate API key. Treat the proxy as local developer infrastructure: bind it intentionally, do not expose it broadly, and keep provider-specific terms in mind.

Context Length Detection

Two settings get confused constantly, per the upstream docs:²

• context_length — the total context window (combined input + output token budget, e.g. 1,000,000 for Claude Opus 4.7 or 200,000 for Sonnet 4.6). Hermes uses this to decide when to compress history.
• model.max_tokens — the output cap (max tokens the model may generate in a single response). Unrelated to history length.

Set context_length when auto-detection gets the window size wrong:

model:
  default: "qwen3.5:9b"
  base_url: "http://localhost:8080/v1"
  context_length: 131072      # tokens

Hermes uses a multi-source resolution chain to detect context windows: config override → custom provider per-model → persistent cache → endpoint /models → Anthropic /v1/models → OpenRouter API → Nous Portal → models.dev (community-maintained registry for 3800+ models) → fallback defaults (128K).² The system is provider-aware, so the same model can have different context limits depending on who serves it (e.g., claude-opus-4.6 is 1M on Anthropic direct but 128K on GitHub Copilot).²

Smart Model Routing: Provider Rotation & Fallback

Hermes does not pin you to one model on one provider. Smart model routing is the set of mechanisms that decide which provider and model actually serves a given request: credential pools spread load across keys, a configured fallback takes over when the primary fails, and the auxiliary slots below route side tasks to cheaper models independently of your main model.²⁶ Configure these three together – they are the difference between an agent that stalls on a rate limit and one that keeps working.

Credential pools. When you have multiple API keys for the same provider, configure a rotation strategy via hermes auth. This is how you distribute rate limits across multiple keys.⁶

Fallback model. Configure a backup provider:model that Hermes switches to automatically when your primary model fails (rate limits, server errors, auth failures):²

fallback_model:
  provider: openrouter            # required
  model: anthropic/claude-sonnet-4  # required
  # base_url: http://localhost:8000/v1    # optional, for custom endpoints
  # api_key_env: MY_CUSTOM_KEY           # optional, env var name

The fallback swaps model and provider mid-session without losing your conversation. It fires at most once per session.² Supported providers for fallback: openrouter, nous, openai-codex, copilot, copilot-acp, anthropic, huggingface, zai, kimi-coding, minimax, minimax-cn, deepseek, ai-gateway, opencode-zen, opencode-go, kilocode, alibaba, custom.²

Auxiliary Models

Hermes uses “auxiliary” models for side tasks: image analysis (vision), dangerous-command approval classification, context compression, session-title generation, TTS audio-tag insertion, skill matching, MCP tool dispatch, and the Kanban specifier/decomposer family.⁴³⁴ By default (auxiliary.*.provider: "auto"), every auxiliary task runs on your main chat model – the same provider/model you picked in hermes model. The docs are explicit that this replaced the old cheap-provider auto-detection: “Earlier builds split aggregator users (OpenRouter, Nous Portal) onto a cheap provider-side default. That was surprising … auto now uses the main model for everyone, and per-task overrides in config.yaml still win.”³⁴ Nothing needs configuring to get started; the tradeoff is cost – on expensive reasoning models, auxiliary tasks add meaningful spend, so point individual tasks at cheap fast models when that matters.

Two former auxiliary tasks no longer use an LLM at all: web extraction (“web_extract and browser snapshots truncate long content deterministically and store the full text for read_file paging – no LLM involved”) and session search (the single-shape tool returns DB content directly). Their old auxiliary.web_extract.* and auxiliary.session_search.* blocks are gone from the defaults – leftover values in an existing config.yaml are “harmless leftovers and ignored” – and the flush_memories slot is likewise absent from the defaults at the tag.³⁴

You can configure which model and provider each auxiliary task uses. Every auxiliary slot uses the same knobs: provider, model, base_url (plus api_key, timeout, extra_body, and a per-task reasoning_effort).⁴³⁴

auxiliary:
  vision:                          # vision_analyze + browser screenshots
    provider: "auto"               # "auto" (= main model), "openrouter", "nous", "main", etc.
    model: ""                      # e.g. "openai/gpt-4o", "google/gemini-2.5-flash"
    base_url: ""                   # Custom OpenAI-compatible endpoint
    api_key: ""                    # Falls back to OPENAI_API_KEY
    timeout: 120
    download_timeout: 30
  approval:                        # dangerous-command approval classifier
    provider: "auto"
    model: ""
    timeout: 30
  compression:                     # summarizer -- legacy compression.summary_* keys migrate here (config v17)
    provider: "auto"
    model: ""
    base_url: ""
    timeout: 120
  title_generation:                # auto-generated session titles after the first exchange
    enabled: true                  # set false to disable auto-titles
    provider: "auto"
    model: ""
    language: ""                   # empty follows the conversation; e.g. "English" pins titles to one language
  tts_audio_tags:    { provider: "auto", model: "" }  # Gemini 3.1 TTS hidden audio-tag insertion
  skills_hub:        { provider: "auto", model: "" }  # skill matching and search
  mcp:               { provider: "auto", model: "" }  # MCP tool dispatch
  triage_specifier:  { provider: "auto", model: "" }  # hermes kanban specify: rough one-liner into a concrete spec, promoted to todo
  kanban_decomposer: { provider: "auto", model: "" }  # hermes kanban decompose: triage task into a graph of child tasks routed to specialist profiles
  profile_describer: { provider: "auto", model: "" }  # hermes profile describe --auto: 1-2 sentence profile descriptions

More specialist slots follow the same shape – goal_judge (judges /goal contract satisfaction), curator (the skill-usage review fork), background_review (the post-turn self-improvement fork), review (the /review reviewer subagent), moa_reference and moa_aggregator (Mixture-of-Agents), memory_query_rewrite, and monitor – and you don’t have to hand-edit YAML at all: run hermes model and pick “Configure auxiliary models” for a per-task interactive picker.³⁴

The "main" provider option means “use whatever provider my main agent uses” – valid only inside auxiliary:, compression:, and primary fallback entries (fallback_providers:, or legacy fallback_model:). It is not valid for your top-level model.provider setting. If you use a custom OpenAI-compatible endpoint as your main model, set provider: custom in your model: section.⁴

Why this matters: because auto already rides your main model, the old “configure OpenRouter or auxiliary tasks silently degrade” gotcha is gone – the tradeoff now is cost. If your main model is an expensive reasoning model, route the chatty side tasks to something cheap and fast:

auxiliary:
  vision:
    provider: "openrouter"
    model: "google/gemini-2.5-flash"
  compression:
    provider: "openrouter"
    model: "google/gemini-2.5-flash"

Configuration System

Hermes has a layered configuration system. Understanding the precedence is essential because higher layers override lower ones, and one of the layers is a global provider registry you can’t see in config.yaml.

Config File Layout

Per the upstream docs, these are the files that make up a Hermes configuration:⁴

~/.hermes/
├── config.yaml       # All settings (model, terminal, TTS, compression, memory, toolsets, ...)
├── .env              # Secrets (API keys, bot tokens, passwords)
├── auth.json         # OAuth provider credentials (Nous Portal, Codex, Anthropic)
├── SOUL.md           # Primary agent identity (slot #1 in system prompt)
├── memories/         # Persistent memory (MEMORY.md, USER.md)
├── skills/           # Bundled + agent-created + hub-installed skills
├── cron/             # Scheduled jobs
├── sessions/         # Gateway session state
└── logs/             # agent.log, gateway.log, errors.log (secrets auto-redacted)

config.yaml vs .env — when both are set, config.yaml wins for non-secret settings.⁴ The rule is:

• Secrets (API keys, bot tokens, passwords) → .env
• Everything else (model, terminal backend, compression settings, memory limits, toolsets) → config.yaml

Secrets can be referenced from config.yaml using shell-style interpolation:⁴

auxiliary:
  vision:
    api_key: ${GOOGLE_API_KEY}
    base_url: ${CUSTOM_VISION_URL}
  delegation:
    api_key: ${DELEGATION_KEY}

Managing Configuration

hermes config                # View current configuration
hermes config show           # Same as above
hermes config edit           # Open config.yaml in your editor
hermes config set KEY VAL    # Set a specific value
hermes config get KEY        # Print a single value (v0.19.0+)
hermes config unset KEY      # Remove a key so the default applies again (v0.19.0+)
hermes config path           # Print the config file path
hermes config env-path       # Print the .env file path
hermes config check          # Check for missing options (after updates)
hermes config migrate        # Interactively add missing options

Examples:⁴

hermes config set model anthropic/claude-opus-4
hermes config set terminal.backend docker
hermes config set OPENROUTER_API_KEY sk-or-...   # Saves to .env

hermes config check and hermes config migrate are the commands to run after every hermes update — they catch newly added config options that your file doesn’t yet have.⁶

Configuration Precedence

Hermes loads configuration from several sources. When multiple sources set the same value, the higher-priority source wins:⁴

1. CLI arguments — hermes chat --model anthropic/claude-sonnet-4 (per-invocation override)
2. Environment variables — applied at process startup
3. config.yaml — the primary settings file
4. .env — secrets only
5. Built-in defaults — applied when nothing else sets a value

CLI flags always win for that single invocation. config.yaml is the long-term source of truth.

Localization (v0.13.0+)

v0.13.0 added 7 locales for CLI and gateway messages: Chinese (Simplified), Japanese, German, Spanish, French, Ukrainian, and Turkish.¹⁸ v0.14.0 localizes all gateway commands and the web dashboard, adds 8 more locales, and brings the total to 16.¹⁹ At tag v2026.8.31 the locales/ tree holds 17 message catalogs – English plus 16 translations (af, ar, de, es, fr, ga, hu, it, ja, ko, pt, ru, tr, uk, zh-hant, zh).³³ Documentation is currently localized in zh-Hans only. Locale resolves from LC_ALL / LANG environment variables or an explicit locale: key in config.yaml. English remains the default and the source of truth for any string a translation hasn’t yet covered.

Profiles — Multiple Isolated Hermes Instances

Profiles give you multiple isolated Hermes instances, each with its own config, sessions, skills, memory, and gateway PID. This is how you run “work Hermes” and “personal Hermes” side-by-side without either seeing the other’s state.⁶

hermes profile list
hermes profile create work --clone                  # Clone from current profile
hermes profile use work                             # Set sticky default
hermes profile alias work --name h-work             # Create wrapper script
hermes profile export work -o work-backup.tar.gz
hermes profile import work-backup.tar.gz --name restored
hermes -p work chat -q "Hello from work profile"    # One-off without switching

Each profile gets its own HERMES_HOME (~/.hermes-<name>/ by default), so multiple profiles can run the gateway concurrently without stepping on each other.⁶³

The isolation boundary is enforced harder as of v0.21.2: a cluster of fixes closed real cross-profile leaks in multiplexed-gateway setups, where secondary profiles could inherit the default profile’s allow-lists, send credentials to its host, hand its vault secrets to stdio MCP servers, or attach another profile’s .env/auth.json/state.db to MEDIA: delivery (#107609-#107630). If you multiplex profiles, v0.21.2 is the tag where the isolation claim actually holds – see What’s New in v0.21.2.⁴⁸

CLI Commands

This section is the practitioner’s reference to top-level CLI commands. For the authoritative code-derived reference, see the upstream CLI Commands Reference.⁶

Global Options

hermes [global-options] <command> [subcommand/options]

Top-Level Commands

hermes chat — The Main Entry Point

hermes with no arguments drops you into interactive chat. hermes chat is the explicit form with options:⁶

hermes chat -q "Summarize the latest PRs" --oneshot # Answer and exit (without --oneshot, a TTY seeds an interactive session)
hermes chat --provider openrouter --model anthropic/claude-sonnet-4.6
hermes chat --toolsets web,terminal,skills          # Enable specific toolsets
hermes chat --quiet -q "Return only JSON"           # Programmatic mode
hermes chat --worktree -q "Review repo and open a PR"

Key options:

hermes setup — Full Wizard

Runs the full setup wizard or jumps into one section:⁶

hermes setup                 # Full wizard
hermes setup model           # Provider and model only
hermes setup terminal        # Terminal backend only
hermes setup gateway         # Messaging platforms only
hermes setup tools           # Tool enable/disable per platform
hermes setup agent           # Agent behavior only
hermes setup --non-interactive
hermes setup --reset         # Reset config to defaults before setup

hermes logs — Structured Log Querying

hermes logs is more powerful than tail -f on the log files because it supports filtering by level, session ID, and time range simultaneously.⁶

hermes logs                          # Last 50 lines of agent.log
hermes logs -f                       # Follow in real time
hermes logs gateway -n 100           # Last 100 lines of gateway.log
hermes logs --level WARNING --since 1h   # Warnings from the last hour
hermes logs --session abc123         # Filter by session ID substring
hermes logs errors --since 30m -f    # Follow errors.log from 30m ago
hermes logs list                     # List all log files with sizes

Log files live in ~/.hermes/logs/:⁶

• agent.log — all agent activity (API calls, tool dispatch, session lifecycle, INFO+)
• errors.log — warnings and errors only (a filtered subset of agent.log)
• gateway.log — messaging gateway activity (platform connections, dispatch, webhooks)

Rotation is automatic via Python’s RotatingFileHandler — look for agent.log.1, agent.log.2, etc.⁶

hermes doctor — Diagnostics

hermes doctor [--fix] is the first command to run when something is wrong. It checks config validity, dependency presence, API key availability, service status, and can attempt automatic repairs with --fix.⁶

For sharing diagnostics with someone else, use hermes dump — it produces a compact plain-text summary with redacted API keys, ready to paste into a GitHub issue or Discord thread.⁶

Slash Commands

Slash commands run inside an active chat session (CLI or messaging platform). They’re dispatched from a shared COMMAND_REGISTRY in hermes_cli/commands.py, which is why most commands work identically across surfaces.⁹

Session Control

Configuration & Model

The /model command is the workhorse for mid-session provider switching:⁹

/model                              # Show current model and options
/model claude-sonnet-4              # Switch model (auto-detect provider)
/model zai:glm-5                    # Switch provider:model
/model custom:qwen-2.5              # Use model on custom endpoint
/model custom                       # Auto-detect model from custom endpoint
/model custom:local:qwen-2.5        # Named custom provider
/model openrouter:anthropic/claude-sonnet-4   # Back to cloud

v0.19.0 adds /model --once — a one-turn model override that reverts to your previous model automatically after the response.⁵⁶ Since the v0.20.5 window the /model picker is also fuzzy: it filters as you type.²³³⁵

Tools, Skills & Info

Dynamic Skill Slash Commands

Every installed skill is automatically exposed as a slash command:⁹

/gif-search funny cats
/axolotl help me fine-tune Llama 3 on my dataset
/github-pr-workflow create a PR for the auth refactor
/excalidraw       # Just the skill name loads it and lets the agent ask what you need

Since v0.19.0, slash-skill invocations stack: /skill-a /skill-b do XYZ loads both skills in order in a single turn, with autocomplete and ghost text for the chained names.⁵⁶

You can also define quick commands in config.yaml that alias a short name to a longer prompt:⁹

quick_commands:
  review: "Review my latest git diff and suggest improvements"
  deploy: "Run the deployment script at scripts/deploy.sh and verify the output"
  morning: "Check my calendar, unread emails, and summarize today's priorities"

Then type /review, /deploy, or /morning in the CLI.

Prefix Matching

Commands support prefix matching: typing /h resolves to /help, /mod resolves to /model. When a prefix is ambiguous, the first registration in registry order wins. Full command names and registered aliases always take priority over prefix matches.⁹

Messaging-Specific Commands

Some commands only work on messaging platforms (Telegram, Discord, Slack, WhatsApp, Signal, Email, Home Assistant):⁹

• /status — show session info (no longer messaging-only; see Session Control)
• /sethome (alias /set-home) — mark the current chat as platform home
• /approve [session|always] — approve a pending dangerous command
• /deny [reason] — reject a pending dangerous command. Since v0.19.0, /deny <reason> relays your refusal reason to the agent so it course-corrects instead of retrying blind⁵⁶
• /update — update Hermes Agent to latest
• /commands [page] — browse all commands and skills (paginated)

And some are CLI-only: /skin, /tools, /toolsets, /browser, /config, /cron, /skills, /platforms, /paste, /statusbar, /plugins.⁹

Tools & Toolsets

Hermes ships with a broad built-in tool registry covering web search, browser automation, terminal execution, file editing, memory, delegation, RL training, messaging delivery, Home Assistant integration, and more.¹⁰ Tools are organized into logical toolsets that can be enabled or disabled per platform.

High-Level Categories

Common toolset names include web, terminal, file, browser, vision, image_gen, moa, skills, tts, todo, memory, session_search, cronjob, code_execution, delegation, clarify, homeassistant, and rl.¹⁰

Managing Tools

hermes chat --toolsets "web,terminal"       # Use specific toolsets
hermes tools                                # Interactive per-platform tool config
hermes tools --summary                      # Print enabled-tools summary

Tools can also be toggled mid-session via /tools disable <name> and /tools enable <name>, which resets the session so the new tool set takes effect.⁹

Terminal Backends

The terminal tool ships seven built-in execution backends – and as of v0.20.6 the set is plugin-extensible, the way the provider picker is (see below):¹⁰²⁴

Switch backends with hermes config set terminal.backend <name> or in config.yaml:

terminal:
  backend: docker      # or: local, ssh, singularity, modal, daytona, vercel_sandbox
  cwd: "."             # Working directory
  timeout: 180         # Command timeout in seconds

Plugin backends (v0.20.6+). Third-party sandbox vendors no longer need to land in the core repo: a plugin registers a TerminalEnvironmentProvider at load time via PluginContext.register_terminal_environment_provider, and the registered name becomes selectable through terminal.backend exactly like a built-in. Built-in names are reserved – the registry rejects a provider whose name collides with an in-tree backend – and a registered backend automatically participates in every core surface (the hermes setup backend picker, dashboard probe status, hermes doctor checks, container path/cwd handling, secret stripping) because the core consults the registry at each classification site instead of a hardcoded list of names.³²

SSH backend (recommended for security — the agent can’t modify its own code):¹⁰

terminal:
  backend: ssh

# In ~/.hermes/.env
TERMINAL_SSH_HOST=my-server.example.com
TERMINAL_SSH_USER=myuser
TERMINAL_SSH_KEY=~/.ssh/id_rsa

Docker backend:

terminal:
  backend: docker
  docker_image: python:3.11-slim

Container resources (applies to docker, singularity, modal, daytona):¹⁰

terminal:
  container_cpu: 1
  container_memory: 5120          # MB (default 5GB)
  container_disk: 51200           # MB (default 50GB)
  container_persistent: true      # Persist filesystem across sessions

With container_persistent: true, installed packages, files, and config survive across sessions.¹⁰

All container backends run with security hardening: read-only root filesystem (Docker), all Linux capabilities dropped except DAC_OVERRIDE, CHOWN, and FOWNER, no privilege escalation, PID limits (256 processes), full namespace isolation, persistent workspace via volumes.¹⁰

Background Processes

The terminal tool supports background execution with explicit process management:¹⁰

terminal(command="pytest -v tests/", background=true)
# Returns: {"session_id": "proc_abc123", "pid": 12345}

process(action="list")                            # Show all running processes
process(action="poll", session_id="proc_abc123")  # Check status
process(action="wait", session_id="proc_abc123")  # Block until done
process(action="log", session_id="proc_abc123")   # Full output
process(action="kill", session_id="proc_abc123")  # Terminate
process(action="write", session_id="proc_abc123", data="y")  # Send input

PTY mode (pty=true) enables interactive CLI tools like Codex and Claude Code.¹⁰

Sudo

If a command needs sudo, Hermes prompts for your password (cached for the session). Or set SUDO_PASSWORD in ~/.hermes/.env.¹⁰

Multi-Agent Kanban (v0.13.0+)

v0.13.0 turns multi-agent collaboration into a first-class primitive: a durable Kanban board that tracks tasks, status, and worker identity across agents and across restarts.¹⁸ The board is what makes a swarm of Hermes workers actually finish work instead of stalling on dead handoffs.

The Kanban board pairs naturally with /goal (locked-target Ralph loop) for the target side and with the existing delegate_task tool for spawn semantics. The result is a swarm pattern where every agent shares one source of truth for what to do next, who is doing it, and what is stuck.

What Is a Hermes Swarm?

A swarm is several Hermes workers running in parallel against one shared Kanban board. It is not a separate subsystem you enable – it is what the board makes possible. The board supplies the one thing parallel agents cannot supply themselves: a single authoritative answer to what should I pick up next, and is anyone already on it?

v0.15.0 promoted this from a pattern to a supported topology, adding swarm topology for parallel worker coordination, auto-decomposition of a high-level goal into subtasks, per-task model overrides, scheduled tasks, and worktree management so parallel workers do not collide in the same checkout.⁵⁹

The practical shape: give the swarm a goal, let auto-decomposition break it into board tasks, and let workers claim, execute, and return results. Retry budget is per-task (max_retries), so one fragile subtask does not consume the whole run’s tolerance. Because the board is durable, a swarm survives restarts – workers reattach and resume against the same state.

A swarm is only as good as its decomposition. The board coordinates workers; it does not make a badly-split goal into a good one. Tasks that share hidden state will still fight, worktrees or not.

Skills System

Skills are on-demand knowledge documents the agent can load when needed. They follow a progressive disclosure pattern to minimize token usage and are compatible with the agentskills.io open standard.¹¹

All skills live in ~/.hermes/skills/ — the primary directory and source of truth. On fresh install, bundled skills are copied from the repo. Hub-installed and agent-created skills also go here.¹¹

Progressive Disclosure

Level 0: skills_list()           → [{name, description, category}, ...]   (~3k tokens)
Level 1: skill_view(name)        → Full content + metadata                 (varies)
Level 2: skill_view(name, path)  → Specific reference file                 (varies)

The agent only loads the full skill content when it actually needs it.¹¹

SKILL.md Format

---
name: my-skill
description: Brief description of what this skill does
version: 1.0.0
platforms: [macos, linux]      # Optional — restrict to OS platforms
metadata:
  hermes:
    tags: [python, automation]
    category: devops
    fallback_for_toolsets: [web]     # Conditional activation
    requires_toolsets: [terminal]    # Conditional activation
    config:                          # Config.yaml settings
      - key: my.setting
        description: "What this controls"
        default: "value"
        prompt: "Prompt for setup"
---

# Skill Title

## When to Use
Trigger conditions for this skill.

## Procedure
1. Step one
2. Step two

## Pitfalls

- Known failure modes and fixes

## Verification
How to confirm it worked.

Conditional Activation

Skills can show or hide themselves based on which tools are available. This is most useful for fallback skills — free or local alternatives that should only appear when a premium tool is unavailable:¹¹

Example: the built-in duckduckgo-search skill uses fallback_for_toolsets: [web]. When you have FIRECRAWL_API_KEY set, the web toolset is available and the agent uses web_search — the DuckDuckGo skill stays hidden. Without the API key, the DuckDuckGo skill automatically appears as a fallback.¹¹

Agent-Managed Skills

The agent can create, update, and delete its own skills via the skill_manage tool. This is the agent’s procedural memory — when it figures out a non-trivial workflow, it saves the approach as a skill for future reuse.¹¹

When the agent creates skills:¹¹

• After completing a complex task (5+ tool calls) successfully
• When it hit errors or dead ends and found the working path
• When the user corrected its approach
• When it discovered a non-trivial workflow

Actions:¹¹

Skill Hub

Browse, search, install, and manage skills from online registries:⁶¹¹

hermes skills browse                          # Browse all hub skills
hermes skills browse --source official        # Browse official optional skills
hermes skills search kubernetes               # Search all sources
hermes skills search react --source skills-sh # Search skills.sh directory
hermes skills inspect openai/skills/k8s       # Preview before installing
hermes skills install openai/skills/k8s       # Install with security scan
hermes skills install skills-sh/anthropics/skills/pdf --force
hermes skills check                           # Check for upstream updates
hermes skills update                          # Reinstall changed hub skills
hermes skills audit                           # Re-scan installed hub skills
hermes skills uninstall k8s
hermes skills publish skills/my-skill --to github --repo owner/repo
hermes skills tap add myorg/skills-repo       # Add custom GitHub source

Integrated hub sources:¹¹

Default GitHub taps (browsable without setup): openai/skills, anthropics/skills, huggingface/skills, NVIDIA/skills, garrytan/gstack. The claude-marketplace source was removed in v0.20.0; browse-sh replaced it in the source list.¹¹⁵⁵

Security Scanning

All hub-installed skills go through a security scanner that checks for data exfiltration, prompt injection, destructive commands, supply-chain signals, and other threats.¹¹

Trust levels:¹¹

--force can override non-dangerous policy blocks for community skills. It does not override a dangerous scan verdict.¹¹

External Skill Directories

You can point Hermes at additional skill directories scanned alongside the local one:¹¹

skills:
  external_dirs:
    - ~/.agents/skills
    - /home/shared/team-skills
    - ${SKILLS_REPO}/skills

Paths support ~ expansion and ${VAR} environment variable substitution. External directories are read-only — when the agent creates or edits a skill, it always writes to ~/.hermes/skills/. Local precedence wins if a skill name exists in both places.¹¹

Pinned Skills: skills.auto_load (v0.21.4 window)

Skill names listed under skills.auto_load in config.yaml are pinned as fully loaded in every new session – CLI, TUI, gateway, cron, and API alike:⁵¹

skills:
  auto_load:
    - team-conventions
    - deploy-checklist

The list resolves once, when the agent’s prompt is first built; a missing or disabled name warns and skips rather than failing the session, and HERMES_IGNORE_RULES (the machinery behind --ignore-rules) suppresses the list like the rest of the auto-injected context. This is the standing-orders complement to -s/--skills, which preloads skills for one session only.⁵¹

Persistent Memory

Hermes has bounded, curated memory that persists across sessions. Two files make up the agent’s memory, both stored in ~/.hermes/memories/:¹²

Both are injected into the system prompt as a frozen snapshot at session start. The agent manages its own memory via the memory tool — add, replace, or remove.¹²

Frozen snapshot pattern: the system prompt injection is captured once at session start and never changes mid-session. This is intentional — it preserves the LLM’s prefix cache for performance. Changes made during a session are persisted to disk immediately but don’t appear in the system prompt until the next session.¹²

What to Save

Save these (the agent does this proactively):¹²

• User preferences: “I prefer TypeScript over JavaScript” → user
• Environment facts: “This server runs Debian 12 with PostgreSQL 16” → memory
• Corrections: “Don’t use sudo for Docker commands, user is in docker group” → memory
• Conventions: “Project uses tabs, 120-char line width, Google-style docstrings” → memory
• Completed work: “Migrated database from MySQL to PostgreSQL on 2026-01-15” → memory

Skip these:¹²

• Trivial/obvious info
• Easily re-discovered facts
• Raw data dumps (too big for memory)
• Session-specific ephemera
• Information already in context files

Session Search

Beyond MEMORY.md and USER.md, the agent can search its past conversations using the session_search tool. All CLI and messaging sessions are stored in SQLite (~/.hermes/state.db) with FTS5 full-text search. Since the v0.15.0 redesign the tool involves no LLM at all – it returns stored conversation content directly (the source’s phrase: the “single-shape tool returns DB content directly”), which is what made it 4,500x faster and removed its API cost.¹²⁵⁹³⁴

Two v0.21.4-window additions, both verified at tag v2026.9.21. First, time bounds: the discovery shape takes after (an inclusive lower bound on session start time) and before (an exclusive upper bound), each an ISO date/datetime – a date-only value means midnight UTC that day – or a relative duration (7d, 24h, 2w), meant only for queries that actually name a time frame; sort remains a ranking bias, not a bound. Second, a zero-result recall retry: FTS5’s implicit AND between terms means a paraphrased multi-word query can miss a stored sentence that lacks even one of its words, so when the exact query and the substring fallbacks all come up empty, the search retries the index matching ANY term, with rank order putting rows that cover more terms first. Hits keep exact-match semantics (the retry is gated on a zero-result miss), and explicit OR/NOT, single-term, and CJK-routed queries are left alone.⁵¹

External Memory Providers

For deeper persistent memory beyond MEMORY.md and USER.md, Hermes ships with seven external memory provider plugins: Honcho, OpenViking, Mem0, Holographic, RetainDB, ByteRover, and Supermemory. More, such as Hindsight, install from the plugin catalog.¹²

Hindsight shipped in the core tree through v0.21.4 and moved to the catalog in v0.21.5, maintained by Vectorize. Existing setups migrate on their own: if memory.provider: hindsight is set, hermes update installs the catalog plugin into every profile home that names it, and the first agent start installs it if it is still missing. With security.allow_lazy_installs: false, the agent-start path only logs a message, so run hermes plugins install hindsight yourself. The plugin lands in ~/.hermes/plugins/hindsight/ and is added to plugins.enabled; memory.provider, memory.hindsight.*, HINDSIGHT_API_KEY, and your memory data stay as they were. Check with hermes memory status and hermes plugins list. The hermes-agent[hindsight] pip extra is gone.⁵³

External providers run alongside built-in memory (never replacing it) and add capabilities like knowledge graphs, semantic search, automatic fact extraction, and cross-session user modeling:⁶¹²

hermes memory setup         # Pick a provider and configure it
hermes memory status        # Check what's active
hermes memory off           # Disable external provider (built-in only)

Only one external provider can be active at a time. Built-in memory is always active.⁶

Session Auto-Resume (v0.13.0+)

v0.13.0 makes mid-agent interruption survivable. The gateway auto-resumes interrupted sessions after a restart; /update restarts preserve session state through the upgrade; source-file reloads during dev keep the active session alive instead of forcing a new one.¹⁸ Practical effect: long-running gateway work and cron-driven jobs no longer reset their context window when the process restarts.

Checkpoints v2 (v0.13.0+)

State persistence is rewritten in v0.13.0 as a single-store design with real pruning, disk guardrails, and no orphan shadow repos.¹⁸ The previous checkpoint system accumulated state on disk across long-running profiles; the v2 store puts a hard ceiling on local checkpoint storage and removes the duplicated bookkeeping that drove that growth. No user-facing config change is required; the next checkpoint write uses the v2 path.

Personality & SOUL.md

SOUL.md is the primary identity of a Hermes instance. It occupies slot #1 in the system prompt, replacing the hardcoded default identity.¹³

Hermes seeds a default SOUL.md automatically at ~/.hermes/SOUL.md (or $HERMES_HOME/SOUL.md for custom profiles). Existing user files are never overwritten. Hermes only loads SOUL.md from HERMES_HOME — it does not look in the current working directory. This makes personality predictable across projects.¹³

What Belongs in SOUL.md

Use it for durable voice and personality guidance:¹³

• tone
• communication style
• level of directness
• default interaction style
• what to avoid stylistically
• how Hermes should handle uncertainty, disagreement, ambiguity

Use it less for:¹³

• one-off project instructions
• file paths
• repo conventions
• temporary workflow details

Those belong in AGENTS.md, not SOUL.md.

SOUL.md vs AGENTS.md

This is the most important distinction in Hermes identity management:¹³

SOUL.md — identity, tone, style, communication defaults, personality-level behavior.

AGENTS.md — project architecture, coding conventions, tool preferences, repo-specific workflows, commands, ports, paths, deployment notes.

A useful rule: if it should follow you everywhere, it belongs in SOUL.md. If it belongs to a project, it belongs in AGENTS.md.¹³

Built-in Personalities

Hermes ships with built-in personalities you can switch to with /personality:¹³³³

Custom personalities in config.yaml:¹³

agent:
  personalities:
    codereviewer: >
      You are a meticulous code reviewer. Identify bugs, security issues,
      performance concerns, and unclear design choices. Be precise and constructive.

Then switch with /personality codereviewer.

SOUL.md vs /personality

SOUL.md is the baseline voice. /personality is a session-level overlay.¹³ Keep a pragmatic default SOUL.md, then use /personality teacher for a tutoring conversation or /personality creative for brainstorming.

Nous Tool Gateway (v0.10.0+)

As of Hermes Agent v0.10.0 (2026-04-16), paid Nous Portal subscribers gain managed access to a curated set of tools through their existing Portal credentials — no extra API keys to manage.⁶¹ The Hermes CLI itself remains MIT-licensed and fully open source. What changed is that your Portal auth now unlocks more than model inference.

The fastest route in is hermes setup --portal, which the README introduces as “One command from a fresh install”: it logs you in via OAuth, sets Nous as your provider, and turns on the Tool Gateway. From then on hermes portal manages the relationship. hermes portal login (the default when no subcommand is given) runs the same one-shot onboarding; hermes portal info prints the “Portal auth + Tool Gateway routing summary”; hermes portal open opens the subscription page in your default browser; hermes portal tools lists the gateway tools and which are routed via Nous. hermes portal status survives as a hidden back-compat alias for info, and the docs’ CLI reference at the tag still spells the subcommand status, so both work.²⁸

What’s in the gateway

How it works

The gateway is opt-in per tool via a new use_gateway config field. If you have Portal credentials in hermes auth and enable the gateway for a tool, that tool’s calls route through Portal. Otherwise your direct API key (if present) is used.

# config.yaml — per-tool gateway opt-in
tools:
  web_search:
    provider: firecrawl
    use_gateway: true          # route via Nous Portal subscription
  image_generation:
    provider: fal
    use_gateway: true

Runtime precedence: when the gateway is available and a tool has use_gateway: true, Hermes prefers the gateway even if you also have a direct API key configured. This matters for billing — gateway calls draw from your Portal subscription, not from your direct API key’s balance.

Enabling the gateway

hermes model                      # select Nous Portal (OAuth flow)
hermes tools                      # per-platform tool picker integrates gateway tools
hermes status                     # confirms gateway/subscription detection

The subscription is detected automatically from the Portal OAuth credentials you already have in hermes auth — there is no separate login step. Since v0.19.0 you can also manage the subscription itself from inside a session: /subscription shows your plan and remaining allowance, previews exactly what an upgrade costs or when a downgrade takes effect, and applies the change with scheduled-change banners and undo; /topup adds credit. The desktop app has a matching billing settings tab.⁵⁶

Pricing and access

Pricing and tier names are published on the Nous Portal pricing page (https://portal.nousresearch.com/pricing). This guide does not enumerate tiers because they’re the responsibility of the Portal product, not the Hermes CLI, and they change independently of Hermes releases. Sign up at https://portal.nousresearch.com/ and check the pricing page for current tiers.

Nous free tier and guided first launch (v0.21.2+)

Since v0.21.2 a fresh install does not need a paid plan or an API key to produce a working agent: free inference and connectors come out of the box, with one command to sign in, and /login starts the sign-in from inside a chat. Connector tools (Gmail, Linear, Notion, and the rest) are searchable through tool_search like any other tool. The desktop adds a guided first launch behind HERMES_GUEST_ONBOARDING=1; only the literal value 1 enables it – the desktop’s own test asserts that 'true', '0', and an empty value all leave it off, and the launch decision is stamped into the spawned backend’s environment so an inherited value never leaks through.⁴⁸

Since the v0.21.4 window, connecting those connectors is one backend-owned operation rather than scattered per-frontend logic: a manage_connections tool call drives a pure-data connection state machine on the backend (with a fixed 300-second operation deadline – deliberately not a config key), and Desktop, TUI, and CLI all render it as the same setup card. The card draws a field per missing credential (name, prompt, required) and holds its verb until every required field has text, and the backend enforces the same secrets-only split on every frontend.⁵¹

Deprecation notice

• HERMES_ENABLE_NOUS_MANAGED_TOOLS env var is removed in v0.10.0. Managed tools are now enabled via the per-tool use_gateway config field and gated on your Portal subscription state.⁶¹

Framing: what this release is not

The Hermes Agent CLI is not gated behind a subscription. The project is still MIT-licensed, all core features (CLI, skills, memory, messaging gateway, cron, MCP, local dashboard, BYOK for every provider) work end-to-end without paying anyone. v0.10.0 adds a convenience path for users who already pay for Nous Portal — it doesn’t remove anything from the free path.

Messaging Gateway

Hermes can run as a long-running gateway process that connects to 28 messaging platforms from a single gateway process: Telegram, Discord, Slack, WhatsApp, Signal, SMS, Email, Home Assistant, Mattermost, Matrix, DingTalk, Feishu/Lark, WeCom, Weixin (WeChat), BlueBubbles (iMessage), QQBot, Microsoft Teams, Tencent Yuanbao, Google Chat, LINE, SimpleX Chat, Photon (iMessage), WhatsApp Cloud API, WeCom Callback, Raft, IRC, ntfy, Buzz, and a generic Webhook adapter.^360171819 That 28 is the docs’ Platform Comparison table at tag v2026.8.31; underneath it, gateway/config.py defines 24 built-in Platform enum members (including non-chat entries such as local, api_server, webhook, msgraph_webhook, and relay) and resolves any other name on demand to one of the 22 bundled adapter directories under plugins/platforms/, so a bare enum or directory count will not match the docs number.²⁵ v0.9.0 added iMessage via BlueBubbles (auto-webhook registration, setup wizard, crash resilience) and native WeChat support via iLink Bot API with WeCom callback mode for enterprise apps.¹⁶ v0.11.0 added QQBot.⁶⁰ v0.12.0 added Microsoft Teams and Tencent Yuanbao.¹⁷ v0.13.0 added Google Chat as the 20th platform, riding the same pluggable adapter architecture; IRC and Microsoft Teams were also migrated onto the new adapter pattern with generic env_enablement_fn / cron_deliver_env_var plugin hooks.¹⁸ v0.14.0 adds LINE and SimpleX Chat and completes the Microsoft Teams stack end-to-end with Graph auth, webhook listener, pipeline runtime, and outbound delivery.¹⁹ v0.17.0 (June 19, 2026) adds relay-free iMessage via Photon Spectrum (device-code OAuth with hermes photon login — no Mac/BlueBubbles relay required), the official WhatsApp Business Cloud API adapter (replacing the bridge-process requirement), SimpleX groups and native attachments, and Raft as a bundled platform plugin.²¹ Two more sit in the docs table with no release-note fanfare: ntfy is a lightweight HTTP pub-sub push channel (subscribe to a topic from the ntfy mobile app, message the topic to talk to the agent, and get the reply back on your phone; works with the public ntfy.sh server or a self-hosted instance, no SDK or daemon required), and Buzz connects Hermes to a Buzz community, Block’s open-source human-plus-agent collaboration platform on the Nostr protocol, shelling out to the buzz CLI for outbound messages and using a native Nostr WebSocket subscription inbound. Both are wired through hermes gateway setup.²⁵

Setup

hermes gateway setup                # Interactive platform configuration
hermes gateway install              # Install as user service (systemd/launchd)
hermes gateway start                # Start the installed service
hermes gateway stop
hermes gateway restart
hermes gateway status
hermes gateway run                  # Run in foreground (debugging)

The interactive setup walks you through connecting each platform: API tokens, bot IDs, channel mappings, allowlists.⁶

How Messages Flow

From the upstream architecture docs:³

Platform event → Adapter.on_message() → MessageEvent
  → GatewayRunner._handle_message()
    → authorize user
    → resolve session key
    → create AIAgent with session history
    → AIAgent.run_conversation()
    → deliver response back through adapter

Every messaging platform runs through the same AIAgent conversation loop as the CLI. That’s why slash commands work identically in both places and why a cron job scheduled in Telegram can deliver its output to Discord — the platform difference is just at the edge.³

v0.19.0 adds profile-based message routing and durable delivery. A single multiplexed gateway sharing one bot token can route specific guilds, channels, or threads to different profiles — each with fully isolated config, skills, memory, and secrets — with a GATEWAY_MULTIPLEX_PROFILES override, and a hardening wave means one misconfigured profile can no longer take down the whole gateway. Under the hood, the routing index moved into state.db (sessions.json is now an optional legacy mirror), and final responses are recorded in a durable delivery-obligation ledger around the platform send — a finished answer that hits a gateway crash is redelivered on the next boot instead of silently lost.⁵⁶ The isolation between routed profiles was hardened at v0.21.2, which closed a cluster of cross-profile leaks in exactly this multiplex setup: inherited allow-lists, credentials sent to the default profile’s host, the default profile’s vault secrets reaching stdio MCP servers, cross-profile MEDIA: attachments, and a sibling’s Nous bearer surviving in per-process memos (#107609-#107630).⁴⁸

v0.21.1 makes conversation boundaries explicit-only. The session-lifecycle doc at tag v2026.9.7 states the contract in four sentences: “Inactivity and wall-clock time never rotate a conversation. /new and /reset create an explicit boundary; context compression continues to manage long histories. Legacy timer configuration is ignored. The existing SessionResetPolicy datatype is inert compatibility data, not a runtime policy.” Explicit suspension still creates a boundary on the next inbound turn, recovery respects finalized boundaries rather than reopening them, and resource-only eviction leaves conversations resumable. If a session on your gateway seems to “never expire,” that is the design now; rotate it yourself with /new.⁴³

Since the v0.21.4 window, a second hermes gateway run attaches or refuses instead of double-binding. The rule is one hermes serve and one hermes gateway run per host per OS user, each multiplexing every profile. Starting a gateway for a profile the running multiplexer already serves just attaches and exits 0; if it does not serve that profile yet, Hermes asks it to rescan profiles/ and attaches once it does; if it cannot be made to serve the profile, the command refuses rather than silently starting a second gateway. --replace now targets that host process, whichever profile launched it, and --force skips the question entirely when the owner is wedged. Standalone gateways still coexist: if the running gateway is another profile’s standalone (non-multiplexing) one, your profile starts its own beside it as before, until that migration is forced (#109417). If two gateways launch at the same moment, the one that loses the host lock exits 75, which every supervisor Hermes generates retries; by then the winner’s record exists, so the retry attaches or refuses by the rules above. The locks and the rendezvous record live under $HERMES_GATEWAY_LOCK_DIR, else $XDG_STATE_HOME/hermes/gateway-locks (default ~/.local/state/hermes/gateway-locks), scoped to the OS user; a record whose PID is dead, or was recycled by another process, is treated as stale and ignored, so a crashed gateway does not block the next start. The Desktop app follows the same rule, attaching to the running host backend instead of spawning a second one.⁵¹

Since v0.21.5, multiplexing is no longer optional. gateway.multiplex_profiles has one valid value, true: an unset key resolves on and is written into the default profile’s config.yaml, and an explicit false is rewritten to true in place with a one-time boxed notice at that gateway start and again in the next hermes update summary. Two controls replace the old opt-out. To take one profile offline without stopping everyone’s bots, run hermes -p <name> gateway stop: the host parks it (a profiles/<name>/gateway.parked marker), and hermes -p <name> gateway start unparks it; the dashboard and Desktop Stop/Start buttons do the same. A named profile that still needs its own gateway sets gateway.standalone: true in its own config.yaml; the host never serves it, and its stop/start act on its own process. The docs call this key “a temporary compatibility shim”, not a supported topology, and it is ignored with a warning on the default profile. A split across OS users, or a HERMES_HOME outside the default home’s profiles/, still takes --force.⁵³

User Authorization & Pairing

hermes pairing list                    # Show pending and approved users
hermes pairing approve <platform> <code>
hermes pairing revoke <platform> <user-id>
hermes pairing clear-pending

Pairing codes prevent random strangers from talking to your gateway. A user sends a pairing code from their messaging platform; you approve it with hermes pairing approve; from then on they’re authorized.⁶

unauthorized_dm_behavior decides what a stranger’s DM gets before pairing: pair DMs a pairing code, ignore drops the message silently, and decline, the value added in the v0.21.4 window, sends one polite refusal and then goes silent toward that sender for 24 hours (#88028). The refusal is deduplicated per platform and sender, across aliases, and its text comes from unauthorized_dm_decline_message (a global key; empty means the built-in reply: “Hi! I’m a personal assistant and can only chat with my owner, so I can’t help you directly. Sorry!”). Set the behavior globally, or per platform where the setup wizard writes it:

# ~/.hermes/config.yaml
unauthorized_dm_behavior: decline      # global; gateway.unauthorized_dm_behavior also works
unauthorized_dm_decline_message: ""    # empty = built-in reply
platforms:
  telegram:
    unauthorized_dm_behavior: pair     # per-platform value always wins

When nothing is set, the effective default depends on your allowlists. With none configured it is pair; once any allowlist is set (GATEWAY_ALLOWED_USERS, or a platform’s allowed-users, group allowed-users, or group allowed-chats variable), it becomes ignore, because the allowlist signals a deliberately restricted gateway, and sending codes to unknown contacts is noisy and a potential information leak (#9337). A global ignore or decline overrides that rule, but a global pair cannot, since it reads the same as the default; to keep pairing alongside an allowlist, set pair per platform. (A platform adapter’s own dm_policy, where one is set, is consulted before the allowlist rule.) Email is inbox-shaped and defaults to ignore unless its own per-platform key opts in; a global value does not reach it. hermes gateway setup offers decline as one of its answers when you configure a platform without an allowlist.⁵¹

Scheduled Tasks (Cron)

Hermes has a first-class cron system where jobs are agent tasks, not shell commands. Each scheduled job runs through a fresh AIAgent with the configured prompt, optional attached skills, and delivers results to any platform:³⁶

hermes cron list
hermes cron create --prompt "Check HN for AI news and summarize" --schedule "0 9 * * *" --deliver telegram
hermes cron edit <id>
hermes cron pause <id>
hermes cron resume <id>
hermes cron run <id>         # Trigger now on the next tick
hermes cron remove <id>
hermes cron status           # Check if scheduler is running
hermes cron tick             # Run due jobs once and exit

Or create one conversationally inside a messaging chat:

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

The agent will set up the cron job via its tools. Jobs persist in JSON and survive restarts.³

v0.21.0 gave scheduled jobs memory and judgment. Four mechanisms, all verified at tag v2026.8.31:³⁵³⁷

• Continuity. continuity=true injects a job’s own most recent output into each run, so a scout or monitor “wakes up seeing what it reported last time and can dedupe and continue where it left off” – the injected framing is “avoid repeating what was already reported”, the first run is unchanged, and internally the flag is stored as the reserved self entry in context_from. Toggle it with hermes cron create ... --continuity and hermes cron edit <job_id> --continuity / --no-continuity.³⁷
• Durable notepads. Every job gets a small KV scratchpad for cursors, watermarks, and watchlists (16 KB per value, 64 KB per job – it is prompt-injected each run, so the caps are deliberate), written via hermes cron notepad <job_id> set <key> <value>, which the running agent invokes through its terminal tool.³⁷
• Monitor mode. A job can attach a cheap monitor_script/monitor_url source that runs first each tick: unchanged output (compared as exact bytes) suppresses the agent run entirely – no LLM call, no delivery, a silent no_change run – while a change injects a diff block and runs the agent normally. Emit stable output from monitor scripts, or every tick looks like a change.³⁷
• Per-job reasoning effort and Bot Chat delivery. --reasoning-effort pins a job’s thinking level (none through ultra), overriding the global and per-model settings for that job’s runs; and deliver=bot-chat lands the output in a profile’s canonical Bot Chat session as a real incoming message, where the bot “acts on anything that needs action, and responds in its chat” instead of a human just reading a channel.³⁷

MCP Integration

Hermes supports the Model Context Protocol as both a client and a server:⁶

As a client — connect Hermes to external MCP servers to extend its tool surface:

hermes mcp add <name> --url https://example.com/mcp
hermes mcp add <name> --command npx --args "-y,@modelcontextprotocol/server-github"
hermes mcp list
hermes mcp test <name>
hermes mcp remove <name>
hermes mcp configure <name>   # Toggle individual tool selection
hermes mcp login <name>       # Force re-auth for an OAuth server (--flow browser|device)
hermes mcp reauth [--all]     # Re-authenticate one OAuth server, or every one

Or manually in config.yaml:¹⁴

mcp_servers:
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxx"

As of v0.19.0, MCP tools are exposed to the model under the mcp__server__tool naming convention — every tool name carries its server name, so two servers exposing the same tool no longer collide — and MCP server log notifications are surfaced in agent.log.⁵⁶

v0.21.1 adds a device-code path to MCP OAuth: hermes mcp login <name> takes --flow {browser,device} – browser is the standing PKCE flow, device is an RFC 8628 device-code login for headless or remote machines – and the flag overrides the server’s oauth.flow config. The same window enforces profile ownership throughout OAuth sessions, ignores malformed OAuth metadata caches instead of wedging a server, and relays desktop MCP OAuth through client-local callbacks; -t/--toolsets now also filters which configured MCP servers are spawned, so a scoped invocation skips cold-starting servers it does not need.⁴⁴

v0.21.0 turns the desktop’s MCP surface into a command center: servers and the catalog merge into one page with drag-in “paste anything” import, background health checks that surface expiring auth before a tool call fails, a fleet cost/usage overlay showing schema token estimates and 30-day usage per server, and hermes:// deep links that install an MCP server with explicit confirmation.³⁵

The v0.21.4 window adds mcp.discovery_concurrency (default 4; 0 = unlimited, #117373): a cap on how many configured MCP servers the discovery pass connects to simultaneously. Every server still connects – the cap only stops them all arriving at once – and a non-integer or negative value logs a warning and falls back to the default.⁵¹

As a server — expose Hermes conversations to other agents:

hermes mcp serve
hermes mcp serve -v    # Verbose

Context Compression

Hermes automatically compresses long conversations to stay within your model’s context window. The compression summarizer is a separate LLM call – you can point it at any provider or endpoint.⁴ As of v0.20.6, the retained-tail policy defaults to lean (compression.tail_mode: lean), and at the tag the summarizer’s model/provider/endpoint knobs live under auxiliary.compression.* rather than the older compression.summary_* – legacy keys are migrated automatically on first load (config version 17).³⁰³¹

compression:
  enabled: true
  threshold: 0.50          # Compress at this % of context limit
  threshold_tokens: null   # Optional absolute token cap -- trigger fires at the lower of ratio vs cap
  target_ratio: 0.20       # Fraction of threshold to preserve as recent tail (legacy tail mode)
  tail_mode: lean          # Tail retention: "lean" (default) or "legacy"
  protect_last_n: 20       # Min recent messages to keep uncompressed
  protect_first_n: 3       # Non-system head messages pinned across compactions

auxiliary:
  compression:
    model: ""              # Empty = main chat model; e.g. "google/gemini-3-flash-preview"
    provider: "auto"       # "auto", "openrouter", "nous", "codex", "main", etc.
    base_url: null         # Custom OpenAI-compatible endpoint (overrides provider)

What tail_mode decides. legacy keeps a target_ratio-sized verbatim tail – on big-window or raised-threshold setups that hoards 100-240K tokens per compaction. lean keeps a clamped verbatim tail of 2.5% of the context window (10K floor, 25K cap) and carries continuity in the summary instead: a detailed identifier-preserving session log of the compacted region (one auxiliary summarizer call per attempt), a mechanically extracted anchor index (PR numbers, SHAs, paths, error strings – regex, never paraphrased), every real user message quoted verbatim, and a session_search recovery pointer so the agent can re-access anything summarized away. The docs’ measured result on 500K-token real sessions: ~49K tokens retained instead of ~162K. Old tool results inside the lean tail are demoted to one-line stubs carrying a recovery pointer, and unknown tail_mode values fall back to lean.³¹

Provider options:⁴³¹