# https://github.com/NousResearch/hermes-agent Project Manual

Generated at: 2026-06-07 06:54:18 UTC

## Table of Contents

- [Overview and Quickstart](#page-1)
- [System Architecture and Agent Loop](#page-2)
- [Providers and Model Integrations](#page-3)
- [Messaging Gateway and Platforms](#page-4)
- [Tools, Toolsets, and Plugins](#page-5)
- [Skills, Memory, and the Learning Loop](#page-6)
- [Frontend Surfaces (Desktop, Web, TUI)](#page-7)
- [Deployment, Profiles, and Operations](#page-8)

<a id='page-1'></a>

## Overview and Quickstart

### Related Pages

Related topics: [System Architecture and Agent Loop](#page-2), [Deployment, Profiles, and Operations](#page-8)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/NousResearch/hermes-agent/blob/main/README.md)
- [package.json](https://github.com/NousResearch/hermes-agent/blob/main/package.json)
- [web/README.md](https://github.com/NousResearch/hermes-agent/blob/main/web/README.md)
- [apps/desktop/src/lib/desktop-slash-commands.ts](https://github.com/NousResearch/hermes-agent/blob/main/apps/desktop/src/lib/desktop-slash-commands.ts)
- [apps/desktop/src/lib/commit-changelog.ts](https://github.com/NousResearch/hermes-agent/blob/main/apps/desktop/src/lib/commit-changelog.ts)
- [apps/desktop/src/lib/markdown-preprocess.ts](https://github.com/NousResearch/hermes-agent/blob/main/apps/desktop/src/lib/markdown-preprocess.ts)
- [ui-tui/src/lib/mathUnicode.ts](https://github.com/NousResearch/hermes-agent/blob/main/ui-tui/src/lib/mathUnicode.ts)
- [optional-skills/software-development/code-wiki/templates/README.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/software-development/code-wiki/templates/README.md)
- [skills/research/research-paper-writing/templates/README.md](https://github.com/NousResearch/hermes-agent/blob/main/skills/research/research-paper-writing/templates/README.md)
- [skills/creative/comfyui/workflows/README.md](https://github.com/NousResearch/hermes-agent/blob/main/skills/creative/comfyui/workflows/README.md)
</details>

# 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](https://github.com/NousResearch/hermes-agent/blob/main/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](https://github.com/NousResearch/hermes-agent/blob/main/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](https://github.com/NousResearch/hermes-agent/blob/main/web/README.md), the backend is started with:

```bash
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:

```bash
# 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](https://github.com/NousResearch/hermes-agent/blob/main/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.

```mermaid
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](https://github.com/NousResearch/hermes-agent/blob/main/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](https://github.com/NousResearch/hermes-agent/blob/main/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](https://github.com/NousResearch/hermes-agent/blob/main/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:…](#preview:…)` before display.

The desktop app also ships an in-app changelog generator. [apps/desktop/src/lib/commit-changelog.ts](https://github.com/NousResearch/hermes-agent/blob/main/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](https://github.com/NousResearch/hermes-agent/blob/main/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](https://github.com/NousResearch/hermes-agent/blob/main/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](https://github.com/NousResearch/hermes-agent/blob/main/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](https://hermes-agent.nousresearch.com/docs/user-guide/features/tools) — 40+ tools, toolset system, terminal backends
- [Skills System](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills) — procedural memory and the Skills Hub
- [Memory](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory) — persistent memory, user profiles, best practices
- [MCP Integration](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp) — connecting external MCP servers
- [Cron Scheduling](https://hermes-agent.nousresearch.com/docs/user-guide/features/cron) — scheduled tasks with platform delivery
- [Context Files](https://hermes-agent.nousresearch.com/docs/user-guide/features/context-files) — project context that shapes every conversation
- [Architecture](https://hermes-agent.nousresearch.com/docs/developer-guide/architecture) — agent loop and key classes
- [CLI Reference](https://hermes-agent.nousresearch.com/docs/reference/cli-commands) — all commands and flags
- [Environment Variables](https://hermes-agent.nousresearch.com/docs/reference/environment-variables) — complete env var reference

---

<a id='page-2'></a>

## System Architecture and Agent Loop

### Related Pages

Related topics: [Providers and Model Integrations](#page-3), [Messaging Gateway and Platforms](#page-4), [Tools, Toolsets, and Plugins](#page-5)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/NousResearch/hermes-agent/blob/main/README.md)
- [package.json](https://github.com/NousResearch/hermes-agent/blob/main/package.json)
- [web/README.md](https://github.com/NousResearch/hermes-agent/blob/main/web/README.md)
- [ui-tui/README.md](https://github.com/NousResearch/hermes-agent/blob/main/ui-tui/README.md)
- [apps/desktop/src/lib/markdown-preprocess.ts](https://github.com/NousResearch/hermes-agent/blob/main/apps/desktop/src/lib/markdown-preprocess.ts)
- [apps/desktop/src/lib/commit-changelog.ts](https://github.com/NousResearch/hermes-agent/blob/main/apps/desktop/src/lib/commit-changelog.ts)
- [plugins/memory/supermemory/README.md](https://github.com/NousResearch/hermes-agent/blob/main/plugins/memory/supermemory/README.md)
- [skills/creative/manim-video/README.md](https://github.com/NousResearch/hermes-agent/blob/main/skills/creative/manim-video/README.md)
</details>

# 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](https://github.com/NousResearch/hermes-agent/blob/main/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](https://github.com/NousResearch/hermes-agent/blob/main/README.md)).

```mermaid
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](https://github.com/NousResearch/hermes-agent/blob/main/package.json)). The Python package (the agent itself) is installed separately and exposes a CLI plus a FastAPI server that the JS surfaces consume.

| Surface | Tech | Role |
|---|---|---|
| `web/` | Vite + React 19 + TypeScript | Browser dashboard for config, keys, session monitoring ([web/README.md](https://github.com/NousResearch/hermes-agent/blob/main/web/README.md)) |
| `ui-tui/` | Ink (React-for-CLI) | Interactive terminal UI with a `gatewayClient` JSON-RPC bridge ([ui-tui/README.md](https://github.com/NousResearch/hermes-agent/blob/main/ui-tui/README.md)) |
| `apps/desktop/` | Electron | Packaged desktop client, including remote-gateway mode over WebSocket |
| Python runtime | FastAPI on port 9119 | Serves REST + WebSocket; Vite dev server proxies `/api` to it ([web/README.md](https://github.com/NousResearch/hermes-agent/blob/main/web/README.md)) |

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](https://github.com/NousResearch/hermes-agent/releases/tag/v2026.4.23)), 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](https://github.com/NousResearch/hermes-agent/blob/main/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](https://github.com/NousResearch/hermes-agent/blob/main/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](https://github.com/NousResearch/hermes-agent/blob/main/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](https://github.com/NousResearch/hermes-agent/blob/main/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](https://github.com/NousResearch/hermes-agent/blob/main/ui-tui/README.md)). The web surface proxies `/api` to the FastAPI backend on port 9119 ([web/README.md](https://github.com/NousResearch/hermes-agent/blob/main/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](https://github.com/NousResearch/hermes-agent/blob/main/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](https://github.com/NousResearch/hermes-agent/releases/tag/v2026.4.30)). 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](https://hermes-agent.nousresearch.com/docs/user-guide/features/tools)
- [Skills System](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills)
- [Memory](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory)
- [MCP Integration](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp)
- [Cron Scheduling](https://hermes-agent.nousresearch.com/docs/user-guide/features/cron)
- [Context Files](https://hermes-agent.nousresearch.com/docs/user-guide/features/context-files)
- [Architecture (official docs)](https://hermes-agent.nousresearch.com/docs/developer-guide/architecture)

---

<a id='page-3'></a>

## Providers and Model Integrations

### Related Pages

Related topics: [System Architecture and Agent Loop](#page-2), [Tools, Toolsets, and Plugins](#page-5)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/NousResearch/hermes-agent/blob/main/README.md)
- [web/README.md](https://github.com/NousResearch/hermes-agent/blob/main/web/README.md)
- [package.json](https://github.com/NousResearch/hermes-agent/blob/main/package.json)
- [ui-tui/README.md](https://github.com/NousResearch/hermes-agent/blob/main/ui-tui/README.md)
- [apps/shared/package.json](https://github.com/NousResearch/hermes-agent/blob/main/apps/shared/package.json)
- [apps/desktop/src/lib/markdown-preprocess.ts](https://github.com/NousResearch/hermes-agent/blob/main/apps/desktop/src/lib/markdown-preprocess.ts)
- [apps/desktop/src/lib/commit-changelog.ts](https://github.com/NousResearch/hermes-agent/blob/main/apps/desktop/src/lib/commit-changelog.ts)
- [ui-tui/src/lib/mathUnicode.ts](https://github.com/NousResearch/hermes-agent/blob/main/ui-tui/src/lib/mathUnicode.ts)
</details>

# 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`](README.md)) ships the backend, while the [`web/`](web/README.md) dashboard and [`ui-tui/`](ui-tui/README.md) 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](README.md)

## Provider Surfaces

Hermes exposes three primary integration surfaces that providers plug into:

| Surface | Role | Where it is wired |
|---|---|---|
| **Model providers** | LLM API backends (chat, completion, streaming) | Backend Python package, configured per-session |
| **Tool gateways** | Hosted capabilities such as web search, image generation, TTS, and browser automation | Nous Tool Gateway (v0.10.0 release) |
| **MCP servers** | User-supplied Model Context Protocol servers that extend tool inventory | `mcp_servers` config block in the agent config |

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](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](README.md); issue #38412 (community context)

## Workspace and Packaging

The monorepo is organised as npm workspaces declared in the root [`package.json`](package.json): `apps/*`, `ui-tui`, `ui-tui/packages/*`, and `web`. The shared library [`@hermes/shared`](apps/shared/package.json) 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](package.json); [web/README.md](web/README.md); [apps/shared/package.json](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.

2. **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`](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](README.md); [web/README.md](web/README.md)

## See Also

- [Tools & Toolsets](README.md) (referenced from the main README link table)
- [Skills System](README.md)
- [MCP Integration](README.md)
- [Memory & Profiles](README.md)
- [Architecture overview](README.md)
- 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

---

<a id='page-4'></a>

## Messaging Gateway and Platforms

### Related Pages

Related topics: [Frontend Surfaces (Desktop, Web, TUI)](#page-7), [System Architecture and Agent Loop](#page-2)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/NousResearch/hermes-agent/blob/main/README.md)
- [package.json](https://github.com/NousResearch/hermes-agent/blob/main/package.json)
- [ui-tui/README.md](https://github.com/NousResearch/hermes-agent/blob/main/ui-tui/README.md)
- [web/README.md](https://github.com/NousResearch/hermes-agent/blob/main/web/README.md)
- [apps/desktop/src/lib/markdown-preprocess.ts](https://github.com/NousResearch/hermes-agent/blob/main/apps/desktop/src/lib/markdown-preprocess.ts)
- [apps/desktop/src/lib/commit-changelog.ts](https://github.com/NousResearch/hermes-agent/blob/main/apps/desktop/src/lib/commit-changelog.ts)
- [ui-tui/src/lib/mathUnicode.ts](https://github.com/NousResearch/hermes-agent/blob/main/ui-tui/src/lib/mathUnicode.ts)
- [plugins/memory/supermemory/README.md](https://github.com/NousResearch/hermes-agent/blob/main/plugins/memory/supermemory/README.md)
</details>

# 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](https://github.com/NousResearch/hermes-agent/blob/main/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](https://github.com/NousResearch/hermes-agent/blob/main/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](https://github.com/NousResearch/hermes-agent/blob/main/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](https://github.com/NousResearch/hermes-agent/issues/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

```mermaid
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](https://github.com/NousResearch/hermes-agent/releases/tag/v2026.4.16)]. 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

| Symptom | Surface | Likely cause | Reference |
|---|---|---|---|
| `/api/ws` rejected with 4403 | Desktop Remote gateway | WS upgrade rejected for packaged Electron client (origin/handshake) | [issue #38412](https://github.com/NousResearch/hermes-agent/issues/38412) |
| Dashboard infinite-reload loop | Loopback mode after v0.15.0 | Same-day hotfix shipped in v0.15.1 | [v0.15.1 release notes](https://github.com/NousResearch/hermes-agent/releases/tag/v2026.5.29) |
| Skills index `degraded` | `/docs/skills` and `/docs/api/skills-index.json` | Automated freshness probe failing; index rebuilt by `.github/workflows/skills-index.yml` (cron 6/18 UTC) | [issue #38240](https://github.com/NousResearch/hermes-agent/issues/38240) |
| `No module named pip` during NeuTTS install | First-run setup | venv bootstrap step missing `ensurepip` | [issue #3002](https://github.com/NousResearch/hermes-agent/issues/3002) |

## 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](https://github.com/NousResearch/hermes-agent/blob/main/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](https://github.com/NousResearch/hermes-agent/blob/main/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](https://hermes-agent.nousresearch.com/docs/developer-guide/architecture) — project structure, agent loop, key classes
- [Tools & Toolsets](https://hermes-agent.nousresearch.com/docs/user-guide/features/tools) — the 40+ tool system that the gateway exposes
- [MCP Integration](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp) — pluggable transport for additional capabilities
- [Environment Variables](https://hermes-agent.nousresearch.com/docs/reference/environment-variables) — gateway host/port/auth configuration
- [Hermes Agent v0.11.0 release notes](https://github.com/NousResearch/hermes-agent/releases/tag/v2026.4.23) — introduction of the pluggable transport architecture
- [Hermes Agent v0.10.0 release notes](https://github.com/NousResearch/hermes-agent/releases/tag/v2026.4.16) — introduction of the Nous Tool Gateway

---

<a id='page-5'></a>

## Tools, Toolsets, and Plugins

### Related Pages

Related topics: [System Architecture and Agent Loop](#page-2), [Skills, Memory, and the Learning Loop](#page-6)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/NousResearch/hermes-agent/blob/main/README.md)
- [package.json](https://github.com/NousResearch/hermes-agent/blob/main/package.json)
- [web/README.md](https://github.com/NousResearch/hermes-agent/blob/main/web/README.md)
- [ui-tui/README.md](https://github.com/NousResearch/hermes-agent/blob/main/ui-tui/README.md)
- [apps/desktop/src/lib/commit-changelog.ts](https://github.com/NousResearch/hermes-agent/blob/main/apps/desktop/src/lib/commit-changelog.ts)
- [skills/creative/comfyui/workflows/README.md](https://github.com/NousResearch/hermes-agent/blob/main/skills/creative/comfyui/workflows/README.md)
- [tools/registry.py](https://github.com/NousResearch/hermes-agent/blob/main/tools/registry.py)
- [toolsets.py](https://github.com/NousResearch/hermes-agent/blob/main/toolsets.py)
- [toolset_distributions.py](https://github.com/NousResearch/hermes-agent/blob/main/toolset_distributions.py)
- [tools/browser_tool.py](https://github.com/NousResearch/hermes-agent/blob/main/tools/browser_tool.py)
- [tools/browser_supervisor.py](https://github.com/NousResearch/hermes-agent/blob/main/tools/browser_supervisor.py)
- [tools/terminal_tool.py](https://github.com/NousResearch/hermes-agent/blob/main/tools/terminal_tool.py)
</details>

# 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](https://github.com/NousResearch/hermes-agent/releases/tag/v2026.5.29.2)).

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

```mermaid
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]()

```json
"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]()

```json
"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](https://github.com/NousResearch/hermes-agent/releases/tag/v2026.4.16).

## 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](https://github.com/NousResearch/hermes-agent/releases/tag/v2026.5.29.2).

### Workspace Layout

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

```json
"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

| Symptom | Likely cause | Where to look |
|---|---|---|
| Browser tool runs but pages never load | `agent-browser` not installed or version skew | [package.json:31-34]() and `npm install` workspace output |
| WebSocket rejected (4403) in Desktop "Remote gateway" mode | Gateway rejects the Electron client's `/api/ws` upgrade; works on REST | [issue #38412](https://github.com/NousResearch/hermes-agent/issues/38412) |
| NeuTTS install fails with "No module named pip" | Bundled venv missing pip; needs bootstrapping | [issue #3002](https://github.com/NousResearch/hermes-agent/issues/3002) |
| Skills index goes `degraded` | `/docs/api/skills-index.json` not rebuilt; the skills hub depends on the same registration pipeline as toolsets | [issue #38240](https://github.com/NousResearch/hermes-agent/issues/38240) |
| `plugin.yaml` missing after `pip install` | Wheel/sdist doesn't include the manifest (fixed in v0.15.2) | [v0.15.2 release notes](https://github.com/NousResearch/hermes-agent/releases/tag/v2026.5.29.2) |

## See Also

- [Skills System](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills) — Procedural memory layered on top of tools.
- [MCP Integration](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp) — Extending the tool registry with external servers.
- [Environment Variables](https://hermes-agent.nousresearch.com/docs/reference/environment-variables) — Toolset/feature flag toggles.
- [CLI Reference](https://hermes-agent.nousresearch.com/docs/reference/cli-commands) — Commands for listing, enabling, and invoking toolsets.

---

<a id='page-6'></a>

## Skills, Memory, and the Learning Loop

### Related Pages

Related topics: [Tools, Toolsets, and Plugins](#page-5), [Overview and Quickstart](#page-1)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/NousResearch/hermes-agent/blob/main/README.md)
- [plugins/memory/honcho/README.md](https://github.com/NousResearch/hermes-agent/blob/main/plugins/memory/honcho/README.md)
- [skills/creative/manim-video/README.md](https://github.com/NousResearch/hermes-agent/blob/main/skills/creative/manim-video/README.md)
- [skills/creative/p5js/README.md](https://github.com/NousResearch/hermes-agent/blob/main/skills/creative/p5js/README.md)
- [skills/creative/comfyui/workflows/README.md](https://github.com/NousResearch/hermes-agent/blob/main/skills/creative/comfyui/workflows/README.md)
- [skills/research/research-paper-writing/templates/README.md](https://github.com/NousResearch/hermes-agent/blob/main/skills/research/research-paper-writing/templates/README.md)
- [optional-skills/mlops/saelens/references/README.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops/saelens/references/README.md)
- [apps/desktop/src/lib/desktop-slash-commands.ts](https://github.com/NousResearch/hermes-agent/blob/main/apps/desktop/src/lib/desktop-slash-commands.ts)
- [package.json](https://github.com/NousResearch/hermes-agent/blob/main/package.json)
</details>

# 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

```mermaid
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:

```bash
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

| Symptom | Likely cause | Where to look |
|---|---|---|
| `/docs/skills` hub is empty or stale | Skills index cron hasn't run, or workflow failed | Issue tracker for `skills-index-watchdog` `degraded` reports; check `.github/workflows/skills-index.yml` and `deploy-site.yml` runs |
| Agent ignores a freshly added skill | Skill not reloaded in current session | Run `/reload-skills` in the desktop client |
| Agent hallucinates a user fact | Memory provider is the wrong one, or context injection is disabled | `hermes config get memory.provider`; verify the `<memory-context>` block in the outgoing API call |
| Skill works locally but breaks in CI | Skill lives under `optional-skills/` and is not auto-installed | Move to `skills/` or document the opt-in install step in the skill's `README.md` |

## See Also

- [README.md](https://github.com/NousResearch/hermes-agent/blob/main/README.md) — top-level feature list and release history
- [plugins/memory/honcho/README.md](https://github.com/NousResearch/hermes-agent/blob/main/plugins/memory/honcho/README.md) — reference memory provider implementation
- [Hermes Agent v0.12.0 release notes](https://github.com/NousResearch/hermes-agent/releases/tag/v2026.4.30) — Curator introduction
- [Hermes Agent v0.13.0 release notes](https://github.com/NousResearch/hermes-agent/releases/tag/v2026.5.7) — Tenacity/learning-loop refinements
- [apps/desktop/src/lib/desktop-slash-commands.ts](https://github.com/NousResearch/hermes-agent/blob/main/apps/desktop/src/lib/desktop-slash-commands.ts) — full desktop command surface

---

<a id='page-7'></a>

## Frontend Surfaces (Desktop, Web, TUI)

### Related Pages

Related topics: [Messaging Gateway and Platforms](#page-4), [Deployment, Profiles, and Operations](#page-8)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/NousResearch/hermes-agent/blob/main/README.md)
- [package.json](https://github.com/NousResearch/hermes-agent/blob/main/package.json)
- [web/README.md](https://github.com/NousResearch/hermes-agent/blob/main/web/README.md)
- [ui-tui/README.md](https://github.com/NousResearch/hermes-agent/blob/main/ui-tui/README.md)
- [apps/desktop/src/lib/markdown-preprocess.ts](https://github.com/NousResearch/hermes-agent/blob/main/apps/desktop/src/lib/markdown-preprocess.ts)
- [apps/desktop/src/lib/commit-changelog.ts](https://github.com/NousResearch/hermes-agent/blob/main/apps/desktop/src/lib/commit-changelog.ts)
- [ui-tui/src/lib/mathUnicode.ts](https://github.com/NousResearch/hermes-agent/blob/main/ui-tui/src/lib/mathUnicode.ts)
</details>

# 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]().

```mermaid
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`](https://github.com/NousResearch/hermes-agent/blob/main/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]().

```bash
# 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:

| Component | Role |
|---|---|
| `appChrome.tsx` | Status bar, input row, completions |
| `markdown.tsx` | Markdown-to-Ink renderer with math fallback |
| `prompts.tsx` | Approval and clarification flows |
| `modelPicker.tsx` / `sessionPicker.tsx` | Model switch and session resume pickers |
| `maskedPrompt.tsx` | Masked input for sudo and secret entry |
| `useCompletion.ts` | Tab completion for slash commands and paths |

Source: [ui-tui/README.md:30-43]().

The markdown renderer is paired with a best-effort LaTeX-to-Unicode pipeline in [`mathUnicode.ts`](https://github.com/NousResearch/hermes-agent/blob/main/ui-tui/src/lib/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`](https://github.com/NousResearch/hermes-agent/blob/main/apps/desktop/src/lib/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`](https://github.com/NousResearch/hermes-agent/blob/main/apps/desktop/src/lib/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](https://hermes-agent.nousresearch.com/docs/developer-guide/architecture) — gateway and agent-loop structure
- [CLI Reference](https://hermes-agent.nousresearch.com/docs/reference/cli-commands) — `hermes web` and `hermes dashboard` flags
- [Environment Variables](https://hermes-agent.nousresearch.com/docs/reference/environment-variables) — gateway port and CORS configuration
- [Skills System](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills) — surfaces the Skills Hub in the web dashboard

---

<a id='page-8'></a>

## Deployment, Profiles, and Operations

### Related Pages

Related topics: [Overview and Quickstart](#page-1), [Messaging Gateway and Platforms](#page-4), [Frontend Surfaces (Desktop, Web, TUI)](#page-7)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/NousResearch/hermes-agent/blob/main/README.md)
- [package.json](https://github.com/NousResearch/hermes-agent/blob/main/package.json)
- [web/README.md](https://github.com/NousResearch/hermes-agent/blob/main/web/README.md)
- [apps/desktop/src/lib/desktop-slash-commands.ts](https://github.com/NousResearch/hermes-agent/blob/main/apps/desktop/src/lib/desktop-slash-commands.ts)
- [apps/desktop/src/lib/commit-changelog.ts](https://github.com/NousResearch/hermes-agent/blob/main/apps/desktop/src/lib/commit-changelog.ts)
- [plugins/memory/supermemory/README.md](https://github.com/NousResearch/hermes-agent/blob/main/plugins/memory/supermemory/README.md)
</details>

# 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.

```mermaid
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](https://github.com/NousResearch/hermes-agent/issues/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:

| Symptom | Source | Mitigation |
|---|---|---|
| Dashboard infinite-reload loop in loopback/Docker mode | v0.15.1 release notes | Upgrade to v0.15.1; the hotfix release closed this regression |
| `/docs/api/skills-index.json` flagged `degraded` by the skills-index watchdog | Issue #38240 | Re-run `.github/workflows/skills-index.yml` (cron 6/18 UTC) or trigger `.github/workflows/deploy-site.yml` |
| `neutts` setup fails: `No module named pip` inside `~/.hermes/hermes-agent/venv` | Issue #3002 | Recreate the venv with a Python that ships `ensurepip`, or `python -m ensurepip` before the NeuTTS install step |
| Desktop `Remote gateway` mode → `/api/ws` 4403 | Issue #38412 | Match the desktop build's expected WebSocket auth path against the deployed backend's allowlist before rolling out remote-gateway |

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](https://github.com/NousResearch/hermes-agent/releases/tag/v2026.5.29.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](https://github.com/NousResearch/hermes-agent/releases/tag/v2026.4.30).

## See Also

- [Architecture](https://hermes-agent.nousresearch.com/docs/developer-guide/architecture) — Project structure, agent loop, key classes
- [CLI Reference](https://hermes-agent.nousresearch.com/docs/reference/cli-commands) — All commands and flags
- [Environment Variables](https://hermes-agent.nousresearch.com/docs/reference/environment-variables) — Complete env var reference
- [Memory](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory) — Persistent memory, user profiles, best practices
- [Tools & Toolsets](https://hermes-agent.nousresearch.com/docs/user-guide/features/tools) — 40+ tools and the toolset system

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: NousResearch/hermes-agent

Summary: 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
- Evidence strength: source_linked
- 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.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_ebdf0d00876046d89748da04ed227c7e | https://github.com/NousResearch/hermes-agent/issues/3002

## 2. Configuration risk - Configuration risk requires verification

- Severity: high
- Evidence strength: source_linked
- 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.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_0b1cf269e8544779854a23690e9187be | https://github.com/NousResearch/hermes-agent/issues/38240

## 3. Security or permission risk - Security or permission risk requires verification

- Severity: high
- Evidence strength: source_linked
- 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.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_533af3ccff3243efbc8a4a049fb486f8 | https://github.com/NousResearch/hermes-agent/issues/38412

## 4. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- 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)
- Suggested 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.
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_release | fmev_1ab5e40250fb7bb7500a78bfac6921ce | https://github.com/NousResearch/hermes-agent/releases/tag/v2026.4.30

## 5. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- 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
- Suggested 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
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_release | fmev_abceb1a94a2e1f07743c8878577f695b | https://github.com/NousResearch/hermes-agent/releases/tag/v2026.5.7

## 6. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- 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)
- Suggested 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
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_release | fmev_94f238ed56ebeb1d4c3cc44c330f6166 | https://github.com/NousResearch/hermes-agent/releases/tag/v2026.5.16

## 7. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- 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
- Suggested 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
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_release | fmev_42c8eb734be226f0ea2754c6ec441b49 | https://github.com/NousResearch/hermes-agent/releases/tag/v2026.5.29

## 8. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- 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
- Suggested 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
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_release | fmev_cd46b9a84f20e3a44f6b2422437a74b8 | https://github.com/NousResearch/hermes-agent/releases/tag/v2026.6.5

## 9. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- 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)
- Suggested 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.
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_release | fmev_ebc5e39694eba4ae912d57e33b801fbc | https://github.com/NousResearch/hermes-agent/releases/tag/v2026.4.13

## 10. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- 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
- Suggested 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
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_aa0532f69fee3ba2c93ab682a2a9d932 | https://github.com/NousResearch/hermes-agent/issues/3002

## 11. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- 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.
- Suggested 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
- Evidence strength: source_linked
- 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)
- Suggested 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.
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_release | fmev_b7814ac23ad116ffc89c5c84de52d640 | https://github.com/NousResearch/hermes-agent/releases/tag/v2026.4.16

## 13. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: Hermes Agent v0.11.0 (2026.4.23)
- User impact: Upgrade or migration may change expected behavior: Hermes Agent v0.11.0 (2026.4.23)
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Hermes Agent v0.11.0 (2026.4.23). Context: Observed when using python
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_release | fmev_682469568c053ba9d4541275da2f3a7a | https://github.com/NousResearch/hermes-agent/releases/tag/v2026.4.23

## 14. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: Hermes Agent v0.15.0 (2026.5.28) — The Velocity Release
- User impact: Upgrade or migration may change expected behavior: Hermes Agent v0.15.0 (2026.5.28) — The Velocity Release
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Hermes Agent v0.15.0 (2026.5.28) — The Velocity Release. Context: Source discussion did not expose a precise runtime context.
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_release | fmev_b143f7fe51c8e3b04b46ced013277c58 | https://github.com/NousResearch/hermes-agent/releases/tag/v2026.5.28

## 15. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: [Bug]: Desktop "Remote gateway" can't connect over WebSocket — /api/ws always rejected (4403) for packaged Electron client
- User impact: Developers may misconfigure credentials, environment, or host setup: [Bug]: Desktop "Remote gateway" can't connect over WebSocket — /api/ws always rejected (4403) for packaged Electron client
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: [Bug]: Desktop "Remote gateway" can't connect over WebSocket — /api/ws always rejected (4403) for packaged Electron client. Context: Observed when using python, macos, linux
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_4474a22161ce67918a103e3a46b3eb5d | https://github.com/NousResearch/hermes-agent/issues/38412

## 16. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: capability.assumptions | github_repo:1024554267 | https://github.com/NousResearch/hermes-agent

## 17. Runtime risk - Runtime risk requires verification

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

## 18. Maintenance risk - Maintenance risk requires verification

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

## 19. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: downstream_validation.risk_items | github_repo:1024554267 | https://github.com/NousResearch/hermes-agent

## 20. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: risks.scoring_risks | github_repo:1024554267 | https://github.com/NousResearch/hermes-agent

## 21. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- 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.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_480a48c0230941ad98930d4a5261ec5e | https://github.com/NousResearch/hermes-agent/issues/41053

## 22. Capability evidence risk - Capability evidence risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this conceptual risk before relying on the project: [skills-index-watchdog] Skills index is stale or degraded (degraded)
- User impact: Developers may hit a documented source-backed failure mode: [skills-index-watchdog] Skills index is stale or degraded (degraded)
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_67c9459bf558bd4c6d02e9d7b9f434a2 | https://github.com/NousResearch/hermes-agent/issues/38240

## 23. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: evidence.maintainer_signals | github_repo:1024554267 | https://github.com/NousResearch/hermes-agent

## 24. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: evidence.maintainer_signals | github_repo:1024554267 | https://github.com/NousResearch/hermes-agent

## 25. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this maintenance risk before relying on the project: Hermes Agent v0.15.2 (2026.5.29.2)
- User impact: Upgrade or migration may change expected behavior: Hermes Agent v0.15.2 (2026.5.29.2)
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Hermes Agent v0.15.2 (2026.5.29.2). Context: Source discussion did not expose a precise runtime context.
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_release | fmev_d6b7af62a9cd2afad3287b2ede57124e | https://github.com/NousResearch/hermes-agent/releases/tag/v2026.5.29.2

<!-- canonical_name: NousResearch/hermes-agent; human_manual_source: deepwiki_human_wiki -->