Related Pages

Related topics: System Architecture and Agent Loop, Deployment, Profiles, and Operations

Overview and Quickstart

What is Hermes Agent?

Hermes Agent is an autonomous, locally-installable agent platform that combines a tool-using LLM loop with persistent memory, a procedural "skills" system, scheduled tasks, and pluggable transports. The repository's top-level README.md advertises a feature surface organized around seven pillars: 40+ tools with a toolset system and multiple terminal backends, a Skills Hub for procedural memory, persistent memory with user profiles and best practices, MCP server integration, cron-based scheduling with platform delivery, project-level context files, and React/Ink-based interactive interfaces. A built-in migration path lets users moving from OpenClaw import existing settings, memories, and skills automatically — this is called out explicitly in the README as a first-class onboarding concern.

The repository is a polyglot workspace. The root package.json declares node >= 20.0.0 and pulls in @streamdown/math and agent-browser as top-level dependencies, with a security overrides pin for lodash to 4.18.1. The Python half (the agent runtime and CLI) lives in hermes_cli/, while desktop, web, and terminal UIs are separate sub-projects under apps/, web/, and ui-tui/.

Quickstart

The fastest path to a running agent is the Python entry point. Per web/README.md, the backend is started with:

python -m hermes_cli.main web --no-open

This boots the FastAPI backend on 127.0.0.1:9119. The same file documents the equivalent shell command hermes dashboard, which serves the built SPA bundle from hermes_cli/web_dist/ rather than the Vite dev server. For frontend iteration, two terminals are required — one for the backend, one for Vite:

# Terminal 1 — backend
python -m hermes_cli.main web --no-open

# Terminal 2 — Vite dev server with HMR
cd web/
npm install
npm run dev

The Vite dev server proxies /api traffic to 127.0.0.1:9119, so the React app talks to the Python backend transparently. Build output from npm run build lands in ../hermes_cli/web_dist/ and is shipped inside the Python wheel via pyproject.toml package-data.

High-Level Architecture

Hermes Agent is a single backend serving multiple front-ends and a CLI. The FastAPI server is the source of truth for sessions, tools, memory, and scheduling; the desktop, web, and TUI clients are thin consumers. The web/README.md makes this explicit: hermes dashboard (port 9119) is a static SPA host, not a development server, and live edits to web/src/ only appear after npm run build and a dashboard restart, or by running web --no-open paired with the Vite dev server.

graph LR
  A[User] --> B[Desktop / Web / TUI]
  B -->|REST + /api/ws| C[FastAPI Backend<br/>hermes_cli on :9119]
  C --> D[Agent Loop]
  C --> E[Tools & Toolsets]
  C --> F[Memory & Skills]
  C --> G[MCP Servers]
  C --> H[Cron / Scheduler]
  C --> I[Context Files]
  D --> J[LLM Providers]

The desktop client is a packaged Electron app. apps/desktop/src/lib/desktop-slash-commands.ts enumerates the slash-command vocabulary exposed to the user — /compact, /config, /cron, /gateway, /history, /image, /logs, /plugins, /tools, /update, /verbose, and many more — partitioned into ownership buckets such as PICKER_OWNED_COMMANDS, TERMINAL_ONLY_COMMANDS, MESSAGING_ONLY_COMMANDS, SETTINGS_OWNED_COMMANDS, and ADVANCED_COMMANDS. The set of "advanced" desktop commands includes /curator, /fast, /insights, /kanban, /personality, /reasoning, /reload-mcp, /reload-skills, and /voice, giving a useful map of the deeper surface area the desktop app exposes beyond chat.

The TUI is a separate, terminal-friendly renderer. ui-tui/src/lib/mathUnicode.ts implements a pure-regex LaTeX-to-Unicode pipeline so that math emitted by models is legible in a terminal where LaTeX cannot be typeset — the design rules in the file's comment (longest-match-first, word-boundary lookahead, and verbatim fallback for unrecognized commands) explain why a partial \frac or a made-up \pix survives intact instead of being mangled.

The desktop renderer is similarly careful about input. apps/desktop/src/lib/markdown-preprocess.ts treats math as a render fence but not latex or tex, deliberately preserving LaTeX source in code blocks that are *discussing* LaTeX rather than embedding it. The same file strips reasoning blocks like <think>...</think> and preview markers like Preview:… before display.

The desktop app also ships an in-app changelog generator. apps/desktop/src/lib/commit-changelog.ts parses Conventional Commits 1.0 headers (type(scope)!: subject), filters internal noise (chore/ci/docs/…), and groups the rest into user-facing buckets: "What's new", "Fixed", "Faster", "Improved", and "Other improvements". The file's own comment notes it is inlined rather than depending on conventional-commits-parser because that package re-exports a Node stream helper that fails to load in the sandboxed Electron renderer.

Optional Skills and Templates

A large portion of the repository is an opt-in Skills Hub. optional-skills/software-development/code-wiki/templates/README.md is the starter for the code-wiki skill, which generates project wiki pages from source code — exactly the kind of capability a quickstart guide benefits from. skills/research/research-paper-writing/templates/README.md ships LaTeX templates for ICML 2026, ICLR 2026, NeurIPS 2025, ACL, AAAI 2026, and COLM 2025, with notes on compilation, anonymization, and Overleaf links. skills/creative/comfyui/workflows/README.md provides ready-to-run ComfyUI workflow JSON files covering SD 1.5, SDXL, Flux Dev, img2img, inpainting, ESRGAN upscale, and AnimateDiff video, with explicit VRAM minima (4 GB for SD1.5, 8 GB for SDXL, 24 GB for Flux Dev).

Community Signals and Common Failure Modes

Recent release notes (community context) describe a fast-moving project: v0.10.0 introduced the Nous Tool Gateway, v0.11.0 was "The Interface release" with a full React/Ink CLI rewrite, v0.12.0 added the autonomous Curator, v0.13.0 was "The Tenacity" release (finishes what it starts), v0.14.0 was the "Foundation" release (installs and runs anywhere), and v0.16.0 was "The Surface Release". The most recent visible regressions in community issues are:

• Skills index staleness — the /docs/skills Skills Hub reads from /docs/api/skills-index.json, which is rebuilt by .github/workflows/skills-index.yml (cron 6/18 UTC) and .github/workflows/deploy-site.yml. If the unified index shows github: 0 < 30 for an extended period, the hub renders as degraded and the skills page appears empty.
• Desktop WebSocket 4403 — packaged Electron clients in "Remote gateway" mode can be rejected at the /api/ws upgrade even when REST succeeds, leaving the UI on "Could not connect to Hermes gateway." This is a known regression in v0.16.0 and tracks the apps/desktop WebSocket path against the FastAPI backend.
• NeuTTS setup failure — a clean install that enables the optional NeuTTS feature can fail with No module named pip inside the bootstrap virtualenv at ~/.hermes/hermes-agent/venv/, which blocks pip install -U 'neutts[all]'.

See Also

• Tools & Toolsets — 40+ tools, toolset system, terminal backends
• Skills System — procedural memory and the Skills Hub
• Memory — persistent memory, user profiles, best practices
• MCP Integration — connecting external MCP servers
• Cron Scheduling — scheduled tasks with platform delivery
• Context Files — project context that shapes every conversation
• Architecture — agent loop and key classes
• CLI Reference — all commands and flags
• Environment Variables — complete env var reference

Related Pages

Related topics: Providers and Model Integrations, Messaging Gateway and Platforms, Tools, Toolsets, and Plugins

System Architecture and Agent Loop

Overview

Hermes Agent is structured as a multi-surface Python application with a thin, swappable frontend layer. The top-level workspace declaration in package.json lists three Node-managed areas — apps/* (Electron desktop clients), ui-tui (Ink-based terminal UI), and web (Vite/React dashboard) — and a single Python entry point surfaced through the postinstall script that points users at python run_agent.py --help (package.json). The Python package owns the agent runtime; the JavaScript workspaces are pure presentation and transport layers.

The agent loop itself is the heart of the system: it is the repeating cycle that takes user input, builds a model prompt, dispatches tool calls, ingests tool results, and streams the next assistant turn. Around it sit orthogonal subsystems — skills, memory, MCP, cron, and context files — that the loop queries or invokes at well-defined points (see the feature index in README.md).

flowchart LR
  User --> UI[UI Surface<br/>Web / TUI / Desktop]
  UI -->|transport| GW[Pluggable Transport Layer]
  GW --> Loop[Agent Loop<br/>prompt → model → tool dispatch]
  Loop --> Skills[Skills Hub]
  Loop --> Memory[Memory Subsystem]
  Loop --> MCP[MCP Servers]
  Loop --> Cron[Cron Scheduler]
  Loop --> Tools[Toolsets + Terminal Backends]
  Tools -->|results| Loop
  Loop -->|stream| UI

Repository Layout and Surfaces

The package.json workspaces field is the authoritative source for what ships in the JavaScript tree (package.json). The Python package (the agent itself) is installed separately and exposes a CLI plus a FastAPI server that the JS surfaces consume.

The release history shows this layout was not accidental. v0.11.0 introduced a "pluggable transport architecture" so any of the three surfaces can talk to the same backend (v0.11.0 release notes), and v0.14.0 framed itself as "Hermes installs and runs anywhere" — meaning the same agent binary should boot under any of the three surfaces.

The Agent Loop

The agent loop is the central state machine: it owns the conversation transcript, decides when to call a tool, executes that tool, folds the result back into the transcript, and continues until the model emits a final assistant message or a stop condition is hit. The features documented in the main README are precisely the subsystems the loop can call into (README.md):

• Tools & Toolsets — 40+ tools grouped into named toolsets, with pluggable terminal backends.
• Skills System — procedural memory: when the loop recognizes a task, it can load a skill (a named, versioned bundle of instructions) into the prompt (skills/creative/manim-video/README.md).
• Memory — persistent user profile and best-practice store; the loop prefetches relevant memory before each turn (plugins/memory/supermemory/README.md).
• MCP Integration — the loop can call any Model Context Protocol server as if it were a local tool.
• Cron Scheduling — the loop is also driven by scheduled triggers, not just chat input.
• Context Files — project-level files the loop prepends to every conversation.

A typical turn has the loop: (1) resolve context files, (2) prefetch memory, (3) assemble the prompt with active skill, (4) call the model, (5) on a tool call, dispatch to the matching toolset, (6) append the tool result, (7) repeat from step 4 until done. The memory plugin documentation describes a complementary outer loop: at session end (or on /reset, branch, compression, or shutdown) the full conversation is buffered and ingested as one session so that profile and graph state stay coherent (plugins/memory/supermemory/README.md).

Transport Layer

The transport layer is the contract between a UI surface and the agent loop. The TUI exemplifies the design: gatewayClient.ts spawns the gateway as a child process and bridges it via JSON-RPC, while the React/Ink tree is purely a consumer of events (ui-tui/README.md). The web surface proxies /api to the FastAPI backend on port 9119 (web/README.md). The desktop surface, when run as a "Remote gateway," must connect to both the REST layer and the WebSocket leg /api/ws; a recent bug report (issue #38412) shows that a packaged Electron client can be rejected with HTTP 4403 on the WebSocket handshake even when REST works, which is the most common failure mode users hit at the transport boundary.

The renderer is expected to receive a stream of structured events from the loop. In the desktop client, markdown-preprocess.ts normalizes these before display: it strips <think>/<thinking>/<reasoning>/<scratchpad>/<analysis> blocks from the rendered view (keeping them only in raw mode), scrubs local preview URLs, and treats ``math fenced blocks as math but `latex / ``tex as syntax-highlighted code — a deliberate divergence from GitHub's renderer (apps/desktop/src/lib/markdown-preprocess.ts). This preprocessing sits on the consumer side of the transport, not inside the loop itself.

Self-Maintenance: The Curator

A distinctive architectural concern is the background Curator introduced in v0.12.0 ("The Curator release — Hermes Agent now maintains itself. An autonomous background Curator grades, prunes, and c[...]") (v0.12.0 release notes). The Curator runs alongside the user-facing agent loop and is responsible for keeping skills, memories, and toolset definitions healthy — grading usefulness, pruning dead entries, and curating the registry. It is a sibling loop, not a step inside the user-facing one: when the user-facing loop ends, the Curator can still be evaluating what just happened.

The Skills Hub depends on a unified index rebuilt by the skills-index.yml and deploy-site.yml GitHub workflows, and the watchdog issue (#38240) reports "github: 0 < 30" entries — a failure that surfaces to users as a degraded Skills Hub even though the agent loop itself is healthy. This separation of concerns (live loop vs. background curator) is what allows the curator to detect and fix that class of failure without interrupting an in-flight conversation.

See Also

• Tools & Toolsets
• Skills System
• Memory
• MCP Integration
• Cron Scheduling
• Context Files
• Architecture (official docs)

Related Pages

Related topics: System Architecture and Agent Loop, Tools, Toolsets, and Plugins

Providers and Model Integrations

Overview

Providers and model integrations are the layer that connects Hermes Agent to external language-model APIs, tool services, and protocol bridges. The agent is designed as a flexible runtime that can talk to multiple model backends and capability gateways without coupling the agent loop to any single vendor. The top-level repository layout supports this separation: a Python package (hermes_cli) ships the backend, while the web/ dashboard and ui-tui/ terminal UI are independent workspaces under the same monorepo.

The README documents the broad surface area of integrations: a "Tools & Toolsets" system (40+ tools), the Skills System, persistent Memory, MCP Integration, Cron Scheduling, and Context Files — all of which are *consumed* by whichever provider the user selects. Provider selection therefore determines which models are reachable, which tools are invocable, and which transport (REST, WebSocket, local IPC) carries the request.

Source: README.md

Provider Surfaces

Hermes exposes three primary integration surfaces that providers plug into:

The dashboard at hermes dashboard (port 9119) and the Vite dev server (port 5173) both surface provider configuration. The web README explicitly notes that the dashboard is where API keys and active sessions are managed, while the Vite dev server proxies /api requests to the FastAPI backend on 127.0.0.1:9119.

Source: web/README.md

The Nous Tool Gateway

Released in v0.10.0 (2026.4.16) — The Tool Gateway release, the Nous Tool Gateway lets paid Nous Portal subscribers use web search, image generation, text-to-speech, and browser automation through their existing subscription with zero additional API keys. The design intent is that a single authentication context unlocks multiple hosted capabilities, removing the need for users to provision separate vendor credentials for each tool family.

Source: Hermes Agent v0.10.0 release notes (community context)

This pattern is significant for provider design because it inverts the usual flow: instead of the user adding API keys per tool, the gateway acts as a *meta-provider* that fans out to underlying services on behalf of the authenticated user. Subsequent releases (v0.11.0 "Interface", v0.13.0 "Tenacity", v0.16.0 "Surface") continued to expand the surface area, adding a pluggable transport architecture (v0.11.0) and the autonomous Curator subsystem (v0.12.0) — both of which depend on a stable provider abstraction to call out to models and tools reliably.

Source: Hermes Agent v0.11.0, v0.12.0, v0.13.0, v0.16.0 release notes (community context)

MCP and External Servers

MCP (Model Context Protocol) integration is documented as a first-class feature. The README lists it as a way to "connect any MCP server for extended capabilities." From a provider perspective, MCP servers are *user-managed* providers — the agent does not own their lifecycle, only the protocol-level handshake and tool discovery.

A known operational issue illustrates a boundary case: in issue #38412, the Hermes Desktop client in "Remote gateway" mode connects to the remote backend's REST layer, but the WebSocket leg (/api/ws) is rejected with code 4403, leaving the UI on "Could not connect to Hermes gateway." This is a transport-handshake failure, not a model-provider failure, but it sits in the same provider-adjacent stack because the WebSocket is the channel the desktop client uses to subscribe to streaming provider events.

Source: README.md; issue #38412 (community context)

Workspace and Packaging

The monorepo is organised as npm workspaces declared in the root package.json: apps/*, ui-tui, ui-tui/packages/*, and web. The shared library @hermes/shared is a workspace package that provides cross-app TypeScript types and utilities. Python packaging is separate — the CLI is shipped via pyproject.toml and the web SPA is bundled into the Python package as static assets (per the web README: "The built assets are included in the Python package via pyproject.toml package-data").

Source: package.json; web/README.md; apps/shared/package.json

This layout has a direct consequence for providers: any new model provider or gateway integration must be importable from the Python backend (so the agent loop can call it) *and* its configuration must be reachable from the web dashboard (so the user can manage keys and toggle it on/off). The shared package provides the TypeScript side of that contract.

Failure Modes and Community-Reported Issues

Two recurring themes in the community context are relevant to provider reliability:

1. Stale skills index (issue #38240) — The Skills Hub at /docs/skills depends on /docs/api/skills-index.json, which is rebuilt by .github/workflows/skills-index.yml on a 6/18-UTC cron. When the probe finds github: 0 < 30 records, the index is marked degraded. Providers that depend on the skills catalog to expose tools will surface this as missing capabilities rather than as a model error.

1. Setup-time dependency failures (issue #3002) — A clean install with NeuTTS enabled fails because the venv Python at ~/.hermes/hermes-agent/venv/bin/python has no pip module, and the setup command attempts to run python -m pip install -U 'neutts[all]'. This is not a model-provider failure, but it is a provider-adjacent setup failure: NeuTTS is a TTS provider, and the failure blocks its installation entirely. The fix is environmental (ensure pip is bootstrapped into the venv) rather than a code change.

Source: issues #38240, #3002 (community context)

Configuration Approach

While the provider-specific configuration files are not included in this context, the public documentation surfaces indicate the configuration model:

• API keys are managed through the web dashboard (web/README.md).
• Tools, toolsets, and tool backends are documented at https://hermes-agent.nousresearch.com/docs/user-guide/features/tools (per the main README link table).
• Environment variables are documented at https://hermes-agent.nousresearch.com/docs/reference/environment-variables.
• Migration from OpenClaw is supported by an auto-import flow that carries over settings, memories, and skills — implying the configuration schema is version-stable across upgrades.

Source: README.md; web/README.md

See Also

• Tools & Toolsets (referenced from the main README link table)
• Skills System
• MCP Integration
• Memory & Profiles
• Architecture overview
• Hermes Agent v0.10.0 release notes (Nous Tool Gateway) — community context
• Hermes Agent v0.11.0 release notes (pluggable transports) — community context
• Hermes Agent v0.16.0 release notes (Surface release) — community context

Related Pages

Related topics: Frontend Surfaces (Desktop, Web, TUI), System Architecture and Agent Loop

Messaging Gateway and Platforms

Overview

In Hermes Agent, a gateway is the transport layer that sits between a user-facing client (TUI, Web dashboard, Desktop app) and the agent runtime. The v0.11.0 release notes describe a "pluggable transport architecture" that decouples the interactive surfaces from the agent loop, and v0.10.0 introduced the Nous Tool Gateway, a separate concept that routes third-party paid APIs (web search, image generation, TTS, browser automation) through a single Nous Portal subscription Source: [README.md].

This page documents the transport-style messaging gateway as implemented in the open-source tree, including the TUI's local gateway bridge, the web-based dashboard gateway, and the Desktop "Remote gateway" mode.

Gateway Surfaces

TUI Gateway Client

The terminal UI ships its own gateway bridge as a child process and JSON-RPC client. Per the TUI module map, ui-tui/src/lib/gatewayClient.ts is the "child process + JSON-RPC bridge" that the Ink-based frontend uses to talk to the running agent Source: [ui-tui/README.md]. The rest of the TUI wraps this client in a React context (app/gatewayContext.tsx), an event handler (app/createGatewayEventHandler.ts), and a slash-command dispatcher (app/createSlashHandler.ts). This is the canonical "local" gateway: the TUI spawns the gateway as a subprocess, exchanges JSON-RPC messages with it, and renders the responses through the app/turnState and app/composerState hooks.

Web Dashboard Gateway

The browser dashboard reuses the same gateway protocol over HTTP. The web workspace is a Vite + React 19 + Tailwind v4 SPA that proxies /api requests to the FastAPI backend running on 127.0.0.1:9119 during development Source: [web/README.md]. In production, the built assets are served from hermes_cli/web_dist/ by the gateway itself. The dashboard is the primary surface for managing API keys, configuration, and monitoring active sessions.

Desktop Remote Gateway

The Electron-based Desktop client can run in two modes: loopback (talking to a local gateway) or Remote gateway, where it connects to a Hermes gateway hosted elsewhere. Community bug reports indicate that the REST leg of the remote connection works, but the WebSocket leg at /api/ws is rejected with status 4403, leaving the UI stuck on "Could not connect to Hermes gateway" Source: [issue #38412]. The same packaged client that succeeds against a loopback gateway fails against a remote one, pointing to a handshake or origin check specific to the WS upgrade path.

Transport Architecture

flowchart LR
  User[User] -->|keystrokes| TUI[ui-tui<br/>Ink + React]
  User -->|HTTPS| Web[web/<br/>Vite + React 19]
  User -->|Electron| Desktop[apps/desktop<br/>Remote gateway mode]
  TUI -->|JSON-RPC<br/>stdin/stdout| GatewayChild[gateway<br/>child process]
  Web -->|HTTP /api| FastAPI[FastAPI<br/>:9119]
  Desktop -->|HTTP + WS /api/ws| FastAPI
  GatewayChild --> Agent[Agent loop<br/>+ tools]
  FastAPI --> Agent
  Agent --> Tools[Toolsets<br/>terminal, browser, memory]

The gateway owns the agent loop; the clients own the presentation. The TUI talks JSON-RPC over the child-process boundary, while the web and desktop clients speak the same logical protocol over HTTP and WebSocket. This is the "pluggable transport" introduced in v0.11.0.

Tools Gateway (v0.10.0+)

Distinct from the transport gateway, the Nous Tool Gateway is a routing layer for third-party APIs. Per the v0.10.0 release ("The Tool Gateway release"), paid Nous Portal subscribers gain access to web search, image generation, text-to-speech, and browser automation through their existing subscription, with no extra API keys required Source: [v0.10.0 release notes]. From the agent's perspective, these capabilities appear as ordinary tools in the toolsets system, but the actual HTTP calls are proxied through Nous-hosted infrastructure.

Known Failure Modes

Configuration & Development

The monorepo organizes the gateway-adjacent code in named workspaces: apps/* (including the Desktop app), ui-tui, ui-tui/packages/*, and web Source: [package.json]. Workspace-scoped install scripts (install:tui, install:web, install:desktop) and audit scripts make it possible to work on a single surface without touching the rest.

For the TUI, the gateway client is the single integration point: every screen component ultimately renders state derived from gatewayClient events, routed through app/createGatewayEventHandler.ts into the nanostores-backed uiStore and overlayStore Source: [ui-tui/README.md]. The Desktop app reuses the same logical model in a sandboxed renderer, which is why issues like the WS rejection only manifest in the packaged Electron build and not in the TUI.

See Also

• Architecture overview — project structure, agent loop, key classes
• Tools & Toolsets — the 40+ tool system that the gateway exposes
• MCP Integration — pluggable transport for additional capabilities
• Environment Variables — gateway host/port/auth configuration
• Hermes Agent v0.11.0 release notes — introduction of the pluggable transport architecture
• Hermes Agent v0.10.0 release notes — introduction of the Nous Tool Gateway

Related Pages

Related topics: System Architecture and Agent Loop, Skills, Memory, and the Learning Loop

Tools, Toolsets, and Plugins

Overview

Hermes Agent exposes its capabilities to the underlying LLM through a layered system of tools, toolsets, and plugins. The project README advertises a "flexible toolsets system for organizing and managing tools" with "40+ tools, toolset system, terminal backends" out of the box. Source: README.md:5-7

The three layers have distinct, complementary roles:

• Tools are the smallest indivisible units of agent capability (a single function call the model can emit, e.g. terminal, browser, web_search).
• Toolsets are named, curated bundles of tools plus their runtime configuration (allowed paths, sandboxing, model preferences). A toolset is what a session or profile actually enables.
• Plugins are packaging units. They are discovered, distributed, and enabled through a plugin.yaml manifest that the wheel/sdist ships with (see v0.15.2 packaging fix, release notes).

The relationship is: *plugin → contains toolset → references tools*. The agent loop, at the start of a turn, asks the registry which toolsets are active and surfaces only those tools to the model.

High-Level Architecture

flowchart TB
    A[Plugin package<br/>plugin.yaml] --> B[Toolset definition<br/>toolsets.py]
    B --> C[Toolset distribution<br/>toolset_distributions.py]
    B --> D[Tool registry<br/>tools/registry.py]
    D --> E[Browser tool<br/>tools/browser_tool.py]
    D --> F[Terminal tool<br/>tools/terminal_tool.py]
    D --> G[Browser supervisor<br/>tools/browser_supervisor.py]
    D --> H[MCP servers]
    D --> I[Nous Tool Gateway<br/>v0.10.0]
    B --> J[Active session]
    J --> K[Agent loop / model prompt]

The agent loop resolves the active toolset, asks the registry for the matching tool implementations, and serializes their JSON-Schema descriptions into the model prompt. Source: README.md:9-15 describes the wider feature surface (Tools, Toolsets, MCP, Skills) that this resolves into.

Built-In Tool Categories

Browser & Web Automation

The desktop and TUI both ship a browser tool, backed by an external Node bridge. The agent-browser package is pinned as a top-level dependency. Source: package.json:31-34

"dependencies": {
  "@streamdown/math": "^1.0.2",
  "agent-browser": "^0.26.0"
}

The postinstall script confirms the intended user flow: install the npm workspaces, then invoke the agent entrypoint. Source: package.json:15-17

"postinstall": "echo '✅ Browser tools ready. Run: python run_agent.py --help'",

A browser_supervisor module exists alongside browser_tool to manage the long-lived browser child process and recover from crashes. Source: tools/browser_supervisor.py and tools/browser_tool.py.

Terminal Backends

Terminal execution is exposed as its own tool family rather than a generic "shell" call. The README groups this under "40+ tools, toolset system, terminal backends", which implies multiple backends (local PTY, sandboxed subprocess, remote SSH) selectable per toolset. Source: README.md:9-11, tools/terminal_tool.py.

MCP-Connected Tools

Hermes treats MCP servers as first-class tool sources. The documentation surfaces an mcp feature page and the registry transparently merges MCP-exposed functions with locally registered tools. Source: README.md:11-13.

Nous Tool Gateway

Starting with v0.10.0 (the "Tool Gateway release"), paid Nous Portal subscribers can route web search, image generation, text-to-speech, and browser automation through their existing subscription, "with zero additional API keys". This is a toolset that talks to a hosted gateway instead of a local implementation. Source: release notes for v0.10.0.

Toolset Distribution & Configuration

Registries and Distributions

The split between toolsets.py and toolset_distributions.py mirrors the split between *what a toolset is* and *how a toolset is delivered* (bundled, user-defined, marketplace). This separation is what enables the plugin/packaging layer in v0.15.2, where plugin.yaml manifests are now shipped inside both the wheel and the sdist. Source: toolsets.py, toolset_distributions.py, v0.15.2 release notes.

Workspace Layout

The monorepo declares several workspaces that each host a UI or packaging variant. Source: package.json:9-14

"workspaces": [
  "apps/*",
  "ui-tui",
  "ui-tui/packages/*",
  "web"
]

Each UI surface (desktop app, TUI, web dashboard) consumes the same underlying toolset definitions; the registry is the single source of truth, so enabling a toolset in one surface is reflected in the others.

User-Facing Changelog Surface

The desktop app ships a small in-process Conventional Commits parser that turns raw commit messages into a grouped "What's new / Fixed / Faster / Improved" changelog. This is the same data model used to advertise new tools and toolsets to end users after an upgrade. Source: apps/desktop/src/lib/commit-changelog.ts:1-15.

Common Failure Modes

See Also

• Skills System — Procedural memory layered on top of tools.
• MCP Integration — Extending the tool registry with external servers.
• Environment Variables — Toolset/feature flag toggles.
• CLI Reference — Commands for listing, enabling, and invoking toolsets.

Related Pages

Related topics: Tools, Toolsets, and Plugins, Overview and Quickstart

Skills, Memory, and the Learning Loop

Hermes Agent treats every conversation as an opportunity to *learn*. The project ships three interlocking subsystems that together form a continuous learning loop: a Skills System (procedural memory — how to do things), a Memory System (semantic/episodic memory — who the user is and what has happened), and a Curator background process that grades, prunes, and curates both. The v0.12.0 release notes describe this as "the Curator release — Hermes Agent now maintains itself. An autonomous background Curator grades, prunes, and c[ontinues to evolve the skill library]." Source: README.md:1-40

This page explains how those three pieces fit together, how to extend them, and what failure modes the community has already hit.

High-Level Architecture

flowchart LR
    User[User / Conversation] -->|prompt| Agent[Hermes Agent Loop]
    Agent -->|injects| Memory[Memory Layer<br/>user profile + best practices]
    Agent -->|selects| Skills[Skill Bundle<br/>procedural instructions]
    Agent -->|executes| Tools[Tools & MCP Servers]
    Tools -->|results + feedback| Curator[Background Curator]
    Skills --> Curator
    Memory --> Curator
    Curator -->|prune / grade / promote| Skills
    Curator -->|summarize / dedupe| Memory
    Curator -->|publish| Hub[Skills Hub<br/>/docs/skills]

The agent loop reads from Memory and Skills on every turn, then hands the resulting artifacts and traces back to the Curator for the next cycle.

The Skills System

Skills are procedural memory — reusable, named playbooks the agent pulls into context when it recognizes a matching task. The project README lists the Skills System as a first-class feature alongside Tools, Memory, and MCP integration. Source: README.md:1-40

Skill Format and Layout

A skill is a directory under skills/ (built-in) or optional-skills/ (opt-in), containing a README.md and usually a scripts/ or references/ subtree. Examples found in the repo:

• skills/creative/manim-video/README.md — math/animation pipeline; depends on Python 3.10+, Manim CE, LaTeX, ffmpeg. Source: skills/creative/manim-video/README.md:1-15
• skills/creative/p5js/README.md — generative art skill, exports a self-contained HTML file via saveCanvas() / saveGif(). Source: skills/creative/p5js/README.md:1-40
• skills/creative/comfyui/workflows/README.md — API-format ComfyUI workflows with VRAM requirements. Source: skills/creative/comfyui/workflows/README.md:1-15
• skills/research/research-paper-writing/templates/ — LaTeX templates for ICML, ICLR, NeurIPS, ACL, AAAI, COLM. Source: skills/research/research-paper-writing/templates/README.md:1-40
• optional-skills/mlops/saelens/ — optional mechanistic interpretability tooling. Source: optional-skills/mlops/saelens/references/README.md:1-20

Skills Hub and Indexing

The published Skills Hub at /docs/skills is driven by a static skills-index.json artifact at /docs/api/skills-index.json. The index is rebuilt by .github/workflows/skills-index.yml (cron at 06:00 and 18:00 UTC) and by .github/workflows/deploy-site.yml on every deploy. A separate automated probe (the skills-index-watchdog) verifies that the index has at least 30 entries sourced from GitHub. Source: README.md:1-40

Community signal: Issue #38240 reports the watchdog flipping to degraded with detail github: 0 < 30 — meaning the index is stale. If /docs/skills looks empty, the first thing to check is whether the index cron has run since the last skill was added.

Slash Commands

In the desktop client, skill management is exposed through slash commands. The desktop command surface registers /skills as settings-owned, and groups /reload-skills under the advanced set alongside /curator, /memory, and /personality. Source: apps/desktop/src/lib/desktop-slash-commands.ts:1-40

The Memory System

Memory is semantic and episodic — durable facts about the user, prior conclusions, and "best practices" the agent has earned. The README lists Memory as a top-level feature with "persistent memory, user profiles, best practices." Source: README.md:1-40

Pluggable Memory Providers

Memory is provider-pluggable. The default provider is configured via hermes config set memory.provider <name>. The Honcho plugin (plugins/memory/honcho/) is one such provider and is documented as an integration with https://docs.honcho.dev/v3/guides/integrations/hermes. Source: plugins/memory/honcho/README.md:1-20

Setup is one command on a fresh install:

hermes memory setup honcho
# or
hermes config set memory.provider honcho
echo "HONCHO_API_KEY=***" >> ~/.hermes/.env

Source: plugins/memory/honcho/README.md:10-30

Two-Layer Context Injection

The Honcho provider documents the project's preferred injection pattern, which is provider-agnostic in spirit:

1. A static mode header lives in the system prompt (cache-friendly).
2. A dynamic context block is injected into the *user message* at API-call time, wrapped in <memory-context> fences with a system note clarifying that the block is background data, not new user input.

The block is refreshed on a configurable cadence (contextCadence turns). Layer 1 carries a SESSION SUMMARY first; additional layers follow. Source: plugins/memory/honcho/README.md:30-50

The Learning Loop (Curator)

The Curator is the closed-loop component that connects Skills and Memory back to themselves. The v0.12.0 release notes describe it as "an autonomous background Curator [that] grades, prunes, and c[ontinues to evolve the skill library]." Source: README.md:1-40

Operationally the loop looks like this:

1. Trace collection — the agent loop emits per-turn artifacts (tool calls, results, successes, failures).
2. Grading — the Curator scores those artifacts against rubric signals (did the skill produce a working artifact? did the memory recall match a real user fact?).
3. Pruning — low-utility skills and stale memory items are deprecated; broken skills are demoted to optional-skills/.
4. Promotion — repeatedly-successful patterns are distilled into new skills or codified into memory "best practices."
5. Publishing — surviving skills feed back into the Skills Hub index.

The v0.13.0 "Tenacity Release" followed on top of this with the theme "Hermes Agent now finishes what it start[ed]" — implying the Curator's grading signal is also used to drive tasks to completion rather than abandoning them. Source: README.md:1-40

Curator as a User-Facing Command

The Curator is not only a background process; it is also a first-class interactive surface. The desktop slash-command registry lists /curator as an *advanced* command (grouped with /fast, /insights, /kanban, /personality, /reasoning, /reload-mcp, /reload-skills, /voice). Source: apps/desktop/src/lib/desktop-slash-commands.ts:10-40

Common Failure Modes

See Also

• README.md — top-level feature list and release history
• plugins/memory/honcho/README.md — reference memory provider implementation
• Hermes Agent v0.12.0 release notes — Curator introduction
• Hermes Agent v0.13.0 release notes — Tenacity/learning-loop refinements
• apps/desktop/src/lib/desktop-slash-commands.ts — full desktop command surface

Related Pages

Related topics: Messaging Gateway and Platforms, Deployment, Profiles, and Operations

Frontend Surfaces (Desktop, Web, TUI)

Overview

Hermes Agent exposes a single Python gateway backend (FastAPI on port 9119) to three distinct frontend surfaces, each tailored to a different deployment context: a browser-based dashboard, a terminal UI, and a packaged Electron desktop app. The surfaces are organized as separate workspaces in the monorepo and they share a common transport contract rather than shared code, allowing each to evolve independently. The v0.16.0 "Surface Release" (2026.6.5) consolidated this architecture, while v0.11.0's "Interface release" introduced the full React/Ink TUI rewrite and the pluggable transport layer. Source: README.md:1-1.

flowchart LR
    U[User] -->|browser| W[Web Dashboard<br/>Vite + React 19]
    U -->|terminal| T[TUI<br/>Ink + React]
    U -->|native app| D[Desktop<br/>Electron]
    W -->|HTTPS / WS| G[FastAPI Gateway<br/>:9119]
    T -->|JSON-RPC / WS| G
    D -->|HTTPS / WS| G
    G --> A[Agent Core<br/>Python]

The root package.json declares the three workspaces (apps/*, ui-tui, web) and provides per-surface install and audit scripts such as install:web, install:tui, and install:desktop. Source: package.json:5-19.

Web Dashboard

The web surface is a single-page application built with Vite, React 19, and TypeScript, styled with Tailwind CSS v4 and a custom dark theme. UI primitives are hand-rolled in a shadcn/ui style without the CLI dependency. Source: web/README.md:5-9.

Two run modes are supported. Development uses the Vite dev server with hot module reload on http://localhost:5173 and an /api proxy pointing at http://127.0.0.1:9119, started alongside python -m hermes_cli.main web --no-open. Production uses hermes dashboard, which serves the pre-built bundle from hermes_cli/web_dist/. Source: web/README.md:11-21.

# Development
python -m hermes_cli.main web --no-open &
cd web/ && npm install && npm run dev

# Production build (output to ../hermes_cli/web_dist/)
cd web/ && npm run build

The build output is included in the Python package via pyproject.toml package-data so the FastAPI server can serve it as a static SPA. Source: web/README.md:31-35. Note that v0.15.0 shipped a dashboard infinite-reload loop on loopback deployments that was patched the same day in v0.15.1 — a reminder that gateway/UI version mismatches manifest in the web surface first.

Terminal UI

The TUI is a React/Ink application with its own workspace under ui-tui/. The top-level tree composes the Ink application from src/app/* modules and renders it through src/main.tsx. Communication with the gateway happens through a dedicated child process and JSON-RPC bridge defined in gatewayClient.ts. Source: ui-tui/README.md:1-16.

The app layer is decomposed into focused hooks and stores: useComposerState for multiline drafts and queued edits, useInputHandlers for keypress routing, useTurnState for the agent turn lifecycle, plus uiStore and overlayStore nanostores for transient UI flags. Source: ui-tui/README.md:18-28.

Component responsibilities map cleanly to the visible chrome:

Source: ui-tui/README.md:30-43.

The markdown renderer is paired with a best-effort LaTeX-to-Unicode pipeline in mathUnicode.ts. Because the terminal cannot typeset LaTeX, the pipeline uses a pure regex approach with longest-match-first ordering, word-boundary lookaheads, and verbatim fallback for unrecognized commands, covering Greek letters, blackboard/fraktur/calligraphic capitals, set-theory and logic operators, common arrows, and \frac{a}{b} collapsed to a/b. Source: ui-tui/src/lib/mathUnicode.ts:7-21.

Desktop App

The desktop surface is an Electron application under apps/desktop/. It packages the gateway experience for end users who prefer a native window, and the renderer is a TypeScript/React tree rooted at src/main.tsx. The Electron main process lives in electron/main.cjs with a matching electron/preload.cjs bridging Node and renderer contexts. Source: apps/desktop/src/lib/markdown-preprocess.ts:1-3.

Two renderer-side libraries are notable. markdown-preprocess.ts normalizes fenced code blocks before they reach the markdown view; it deliberately maps `math to math rendering while leaving `latex and `tex as syntax-highlighted source, so users discussing LaTeX still see it as code. Source: apps/desktop/src/lib/markdown-preprocess.ts:1-19. commit-changelog.ts builds the in-app "What's new" view by parsing Conventional Commits 1.0 headers in a small regex (avoiding the conventional-commits-parser package, which pulls in a Node stream helper that will not load in the sandboxed Electron renderer) and groups commits into new, fixed, faster, improved, and other buckets. Source: apps/desktop/src/lib/commit-changelog.ts:1-23.

A known regression in remote-gateway mode is tracked in issue #38412: the packaged Electron client can reach the REST surface but the WebSocket leg at /api/ws is rejected with code 4403, leaving the UI on "Could not connect to Hermes gateway." This is the canonical example of transport-version drift between the desktop renderer and the gateway.

Shared Transport and Common Failure Modes

All three surfaces converge on the same FastAPI gateway, but each speaks a slightly different dialect during development: the web dashboard uses REST plus a proxied /api, the TUI uses JSON-RPC over a child-process bridge, and the desktop app uses REST plus WebSocket at /api/ws. When the gateway rejects the upgrade, the desktop client fails immediately while the web dashboard degrades to polling — which is why loopback regressions tend to be reported as web reload loops first, then as desktop 4403s once the user switches modes.

Markdown fidelity is the other shared concern. The web view ships full LaTeX support through the documentation site, the TUI downgrades to Unicode glyphs, and the desktop renderer sits between them with explicit fence-language normalization. Contributors changing markdown handling should review all three pipelines together.

See Also

• Architecture — gateway and agent-loop structure
• CLI Reference — hermes web and hermes dashboard flags
• Environment Variables — gateway port and CORS configuration
• Skills System — surfaces the Skills Hub in the web dashboard

Related Pages

Related topics: Overview and Quickstart, Messaging Gateway and Platforms, Frontend Surfaces (Desktop, Web, TUI)

Deployment, Profiles, and Operations

Hermes Agent ships as a multi-surface system that can be run from a terminal, a web dashboard, a packaged desktop client, or a React/Ink TUI, with profile-scoped memory and a long-lived operations vocabulary. This page documents how those surfaces are wired together, how user profiles are isolated, and how operators interact with a running Hermes instance. Community evidence (Remote gateway WebSocket failures, dashboard reload loops, NeuTTS venv setup issues, skills index staleness) shapes the failure modes and design constraints called out below.

Deployment Surfaces

Hermes Agent is a polyglot monorepo. The root package.json declares four workspaces — apps/*, ui-tui, ui-tui/packages/*, and web — and top-level install scripts that target each of them individually (install:root, install:web, install:tui, install:desktop) Source: package.json. The engines field pins Node >=20.0.0, and a post-install hook prints a one-line reminder pointing at the Python entry point: python run_agent.py --help Source: package.json.

The canonical surface is the Python CLI: python -m hermes_cli.main web --no-open starts the FastAPI backend on port 9119, which serves both the REST/WebSocket API and a pre-built static SPA Source: web/README.md. The web workspace is a Vite + React 19 + TypeScript SPA with Tailwind v4, built into hermes_cli/web_dist/ and shipped as Python package data Source: web/README.md. During development, npm run dev (in web/) brings up Vite on port 5173 with HMR and an /api proxy back to the loopback FastAPI server, while hermes dashboard (port 9119) serves the *built* bundle rather than the dev server Source: web/README.md.

A second surface, the Electron Hermes Desktop client, ships as a separate workspace (apps/desktop). Its slash-command registry groups deployment-relevant verbs into categories: PICKER_OWNED_COMMANDS (e.g. /tools, /toolsets, /plugins, /skills), TERMINAL_ONLY_COMMANDS (/config, /logs, /gateway, /update, /restart, /reload), and ADVANCED_COMMANDS (/curator, /personality, /reasoning, /voice, /reload-mcp, /reload-skills) Source: apps/desktop/src/lib/desktop-slash-commands.ts. Commands blocked in a given context are computed by spreading these sets into a single BLOCKED_COMMANDS union Source: apps/desktop/src/lib/desktop-slash-commands.ts.

A third surface, the ui-tui workspace, provides an interactive React/Ink CLI, introduced in the v0.11.0 "Interface" release. A fourth, the v0.10.0 "Tool Gateway" release, exposes web search, image generation, TTS, and browser automation as remote-capable tools that paid Nous Portal subscribers can drive without extra API keys.

flowchart LR
  CLI[Python CLI<br/>run_agent.py]
  Web[Web Dashboard<br/>Vite + React 19]
  Desktop[Hermes Desktop<br/>Electron]
  TUI[ui-tui<br/>React/Ink]
  Backend[FastAPI backend<br/>:9119 /api & /api/ws]
  GW[Nous Tool Gateway<br/>v0.10.0]
  CLI --> Backend
  Web --> Backend
  Desktop -->|REST + WS| Backend
  TUI --> Backend
  Backend --> GW

The community-reported Remote gateway WebSocket failure — Desktop in remote-gateway mode is rejected with HTTP 4403 on /api/ws even though the REST leg succeeds Source: Issue #38412 — sits exactly on the edge between the Desktop node and the Backend node in this diagram and is the most important real-world failure mode for the "Remote gateway" deployment topology.

Profile System

Profiles are the unit of identity and memory isolation. The default profile resolves to hermes-default; any named profile (for example coder) is interpolated into the container_tag of external memory backends via the {identity} placeholder Source: plugins/memory/supermemory/README.md. With "container_tag": "hermes-{identity}", a coder profile writes to hermes-coder, and a missing {identity} causes all profiles to share a single container — a common footgun in multi-workspace deployments Source: plugins/memory/supermemory/README.md.

Advanced operators can opt into multi-container mode by setting enable_custom_container_tags: true and listing custom_containers (e.g. project-alpha, project-beta, shared-knowledge), which lets the agent read and write across named containers — the configuration pattern that OpenClaw users are most often migrating from Source: README.md, Source: plugins/memory/supermemory/README.md.

The migration path is explicitly first-class: Hermes detects an existing OpenClaw installation and imports settings, memories, and skills automatically, as documented in the main README Source: README.md. This makes profile renaming, container re-tagging, and re-keying routine operations rather than data-loss events.

Operations and the Update Pipeline

The desktop client exposes an opinionated operations vocabulary. BLOCKED_COMMANDS and the per-context command sets in desktop-slash-commands.ts are the single source of truth for which verbs are visible in which surface Source: apps/desktop/src/lib/desktop-slash-commands.ts. Deployment-critical verbs include /gateway (switch between loopback and remote gateway), /config (open the settings picker), /restart, /reload, /reload-mcp, /reload-skills, /update, and /platforms (delivery targets for cron output) Source: apps/desktop/src/lib/desktop-slash-commands.ts.

When /update completes, the desktop UI presents a user-facing changelog built by commit-changelog.ts. The parser is intentionally minimal — a regex over the Conventional Commits 1.0 header (type(scope)!: subject) — because the richer conventional-commits-parser package re-exports a Node stream helper that will not load in the sandboxed Electron renderer Source: apps/desktop/src/lib/commit-changelog.ts. Commits are bucketed into What's new (new), Fixed (fixed), Faster (faster), Improved (improved), and Other improvements (other), each with a stable display order, so operators see a consistent grouping across releases Source: apps/desktop/src/lib/commit-changelog.ts.

Two operational failure modes recur in the community context and are worth designing around:

Operators running Hermes at scale should also remember two packaging facts: the v0.15.2 fix shipped bundled plugin.yaml manifests in both wheel and sdist Source: Release v0.15.2, and the v0.12.0 "Curator" release added an autonomous background process that grades, prunes, and curates the agent's own artifacts — which means long-running deployments self-maintain but should still be monitored for curator-side regressions Source: Release v0.12.0.

See Also

• Architecture — Project structure, agent loop, key classes
• CLI Reference — All commands and flags
• Environment Variables — Complete env var reference
• Memory — Persistent memory, user profiles, best practices
• Tools & Toolsets — 40+ tools and the toolset system

Doramagic Pitfall Log

Found 25 structured pitfall item(s), including 3 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

1. Installation risk: Installation risk requires verification

• Severity: high
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/NousResearch/hermes-agent/issues/3002

2. Configuration risk: Configuration risk requires verification

• Severity: high
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/NousResearch/hermes-agent/issues/38240

3. Security or permission risk: Security or permission risk requires verification

• Severity: high
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/NousResearch/hermes-agent/issues/38412

4. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: Hermes Agent v0.12.0 (2026.4.30)
• User impact: Upgrade or migration may change expected behavior: Hermes Agent v0.12.0 (2026.4.30)
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Hermes Agent v0.12.0 (2026.4.30). Context: Observed during installation or first-run setup.
• Evidence: failure_mode_cluster:github_release | https://github.com/NousResearch/hermes-agent/releases/tag/v2026.4.30

5. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: Hermes Agent v0.13.0 (2026.5.7) — The Tenacity Release
• User impact: Upgrade or migration may change expected behavior: Hermes Agent v0.13.0 (2026.5.7) — The Tenacity Release
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Hermes Agent v0.13.0 (2026.5.7) — The Tenacity Release. Context: Observed when using windows
• Evidence: failure_mode_cluster:github_release | https://github.com/NousResearch/hermes-agent/releases/tag/v2026.5.7

6. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: Hermes Agent v0.14.0 (2026.5.16)
• User impact: Upgrade or migration may change expected behavior: Hermes Agent v0.14.0 (2026.5.16)
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Hermes Agent v0.14.0 (2026.5.16). Context: Observed when using python, windows
• Evidence: failure_mode_cluster:github_release | https://github.com/NousResearch/hermes-agent/releases/tag/v2026.5.16

7. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: Hermes Agent v0.15.1 (2026.5.29) — The Patch Release
• User impact: Upgrade or migration may change expected behavior: Hermes Agent v0.15.1 (2026.5.29) — The Patch Release
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Hermes Agent v0.15.1 (2026.5.29) — The Patch Release. Context: Observed when using node, docker
• Evidence: failure_mode_cluster:github_release | https://github.com/NousResearch/hermes-agent/releases/tag/v2026.5.29

8. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: Hermes Agent v0.16.0 (2026.6.5) — The Surface Release
• User impact: Upgrade or migration may change expected behavior: Hermes Agent v0.16.0 (2026.6.5) — The Surface Release
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Hermes Agent v0.16.0 (2026.6.5) — The Surface Release. Context: Observed when using windows, macos, linux
• Evidence: failure_mode_cluster:github_release | https://github.com/NousResearch/hermes-agent/releases/tag/v2026.6.5

9. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: Hermes Agent v0.9.0 (v2026.4.13)
• User impact: Upgrade or migration may change expected behavior: Hermes Agent v0.9.0 (v2026.4.13)
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Hermes Agent v0.9.0 (v2026.4.13). Context: Observed during installation or first-run setup.
• Evidence: failure_mode_cluster:github_release | https://github.com/NousResearch/hermes-agent/releases/tag/v2026.4.13

10. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: [Bug]: Fails to install NeuTTS during setup
• User impact: Developers may fail before the first successful local run: [Bug]: Fails to install NeuTTS during setup
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: [Bug]: Fails to install NeuTTS during setup. Context: Observed when using python, docker, linux
• Evidence: failure_mode_cluster:github_issue | https://github.com/NousResearch/hermes-agent/issues/3002

11. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | github_repo:1024554267 | https://github.com/NousResearch/hermes-agent

12. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Developers should check this configuration risk before relying on the project: Hermes Agent v0.10.0 (2026.4.16)
• User impact: Upgrade or migration may change expected behavior: Hermes Agent v0.10.0 (2026.4.16)
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Hermes Agent v0.10.0 (2026.4.16). Context: Source discussion did not expose a precise runtime context.
• Evidence: failure_mode_cluster:github_release | https://github.com/NousResearch/hermes-agent/releases/tag/v2026.4.16

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using hermes-agent with real data or production workflows.

• fix: skills hub hangs on network timeout + hermes update intermittent - github / github_issue
• [[Feature] goal_mode: remove hard turn cap — keep running until goal achi](https://github.com/NousResearch/hermes-agent/issues/41050) - github / github_issue
• [[skills-index-watchdog] Skills index is stale or degraded (degraded)](https://github.com/NousResearch/hermes-agent/issues/38240) - github / github_issue
• [[Bug]: Desktop "Remote gateway" can't connect over WebSocket — /api/ws a](https://github.com/NousResearch/hermes-agent/issues/38412) - github / github_issue
• [[Bug]: Fails to install NeuTTS during setup](https://github.com/NousResearch/hermes-agent/issues/3002) - github / github_issue
• Hermes Agent v0.16.0 (2026.6.5) — The Surface Release - github / github_release
• Hermes Agent v0.15.2 (2026.5.29.2) - github / github_release
• Hermes Agent v0.15.1 (2026.5.29) — The Patch Release - github / github_release
• Hermes Agent v0.15.0 (2026.5.28) — The Velocity Release - github / github_release
• Hermes Agent v0.14.0 (2026.5.16) - github / github_release
• Hermes Agent v0.13.0 (2026.5.7) — The Tenacity Release - github / github_release
• Hermes Agent v0.12.0 (2026.4.30) - github / github_release