# Plugin Catalog

> Give Hermes new powers with reviewed plugins you can install in one click

- 网址：https://funcoding.ai/agents/hermes-agent/user-guide/features/plugin-catalog/
- 来源：Hermes Agent 官方文档原文（英文），MIT 许可，同步于 2026-10-11
- 官方原文：https://hermes-agent.nousresearch.com/docs/zh-Hans/user-guide/features/plugin-catalog

---
The plugin catalog is a curated, human-reviewed directory of Hermes plugins you
can install by name with a single command:

```bash
hermes plugins install <name>
```

Browse it visually at **[/docs/plugins](https://hermes-agent.nousresearch.com/plugins)** — entries are shelved by
category (Memory, Desktop, Platforms, Web & Browser, Tools, Voice, Automation,
Models), with search, tier filters (Official / Community), capability chips, and
copyable install commands for every entry.

Every entry also has its own page at `/docs/plugins/<name>` (click a card):
the full description and any disclosure, the pinned commit, tools, hooks and
environment variables, the Desktop install button and CLI command, optional
screenshots and the README from the reviewed commit, plus a **More by this
author** shelf. Authors have a page at `/docs/plugins/by/<maintainer>` listing
everything they maintain in the catalog. Both are generated at build time from
the same catalog files, so a merged PR is the only way a page changes.

The catalog complements — it does not replace — the existing
[plugin system](https://funcoding.ai/agents/hermes-agent/user-guide/features/plugins/). Anything you can install from the catalog is a
normal plugin under the hood; the catalog just adds discovery and a review
layer on top.

During desktop onboarding, the setup guide can also offer catalog plugins and skills through an
approval card. Each row installs into your `default` profile only when you click Install, at the
same reviewed commit this page describes.

## What's in an entry

Each catalog entry is a small YAML file in the
[`plugin-catalog/`](https://github.com/NousResearch/hermes-agent/tree/main/plugin-catalog)
directory of the hermes-agent repository, declaring:

| Field | Meaning |
|---|---|
| `name` | The catalog key you pass to `hermes plugins install` |
| `description` | One-line summary shown on cards and in the install prompt, including any reviewer disclosure |
| `repo` | The plugin's public git repository |
| `sha` | The **exact 40-hex commit** that was reviewed — installs check out this pin, not a branch tip |
| `subdir` | Path to the plugin inside the repo for monorepos — a plain relative path matching `[A-Za-z0-9._/-]+` (no `..`, `.`, empty segments, absolute or backslash forms) (optional, default repo root) |
| `tier` | `official` (maintained by NousResearch) or `community` |
| `category` | Browse shelf: `desktop` (default), `memory`, `platform`, `web`, `tools`, `voice`, `automation`, `models` or `general` |
| `maintainer` | Who owns the plugin |
| `capabilities` | Declared tools, hooks, middleware, and required env vars |
| `requires_hermes` | Minimum Hermes version, e.g. `>=0.19` (optional) |
| `platforms` | OS restrictions, empty = all (optional) |
| `title` | Human name shown on cards, e.g. `NVIDIA App` (optional; defaults to `name`) |
| `onboarding` | `true` offers the plugin on the desktop onboarding card, beside the hosted connectors, on the platforms it lists. Curated: official entries only (optional, default `false`) |
| `docs_url` | External documentation link (optional) |
| `known_issues` | Short notes shown at the install prompt, e.g. an unsupported install mode. Informational; they never block the install (optional) |
| `version` | Human-readable label for the pinned sha, e.g. `"1.4.0"`; shown as `1.4.0 @ abcd1234` in the CLI, on the catalog card and on the Desktop **Update to** button (optional, cosmetic) |
| `image` | Banner image for the catalog card and the plugin page hero, shown at 2:1 (1200×600 works; other shapes are centre-cropped); an `https` URL on `raw.githubusercontent.com`, `github.com` or `*.githubusercontent.com` (optional). Pin it to the entry's commit (`raw.githubusercontent.com/owner/repo/<sha>/...`) so it never changes under the review |
| `screenshots` | Up to 6 images shown as a gallery on the plugin page, same host rule as `image` (optional). Pin them to the entry's commit too |
| `readme` | The plugin page renders the repository README (the entry's `subdir` first, else the repo root) by default. It is fetched **from the pinned commit** at docs build time — never from a branch — so the page shows the README the reviewer read and changes only when the pin does. Set `false` to hide it. GitHub and GitLab repos (optional, default `true`) |

## Trust model

The catalog is designed so you know exactly what you're installing:

- **Human-merged admission.** Every entry (and every pin update) lands via a
  pull request reviewed by a maintainer. Nothing enters the catalog
  automatically.
- **Exact SHA pins.** Entries pin a specific commit, not a branch. A plugin
  author pushing new code to their repo does **not** change what the catalog
  installs — updating the pin requires another reviewed PR.
- **Scanned at admission, trusted at install.** Admission CI runs the same
  security scanner the installer runs (`hermes plugins validate` includes a
  `security scan` check): a `dangerous` verdict fails the entry, `caution`
  findings are listed for the reviewer. Because the reviewer saw them, a
  catalog install checked out at exactly the pinned SHA does not stop to ask
  about `caution` again; `dangerous` still blocks, and anything installed from
  a raw URL or at another revision gets the normal prompt.
- **Desktop plugins run with the app's authority — review is the boundary.**
  A plugin's `desktop/plugin.js` is evaluated inside the Desktop app itself,
  in the same realm as the app's own code: there is no sandbox, and it can
  do anything the app can (gateway RPC, the full `window.hermesDesktop`
  bridge, storage of other plugins). What protects you is the trust model
  above — a human read the exact pinned commit, and the install is that
  commit — plus two tripwires: admission's `desktop surface` lint refuses
  the obvious moves outside the plugin SDK (patching built-in prototypes,
  `eval`, importing anything other than `@hermes/plugin-sdk`/`react`,
  including remote scripts), and the app's loader refuses every non-SDK
  import again at load time. The lint reads a `<script` regex — a literal, or
  the pattern string of a `new RegExp(...)` passed straight to
  `.replace()`/`.split()`/`.match()` or used as `.test()`/`.exec()` — as the
  sanitiser it is, not as injection; a `<script` string written into the DOM,
  including one built from `new RegExp(...).source`, still fails. Treat the
  lint as a review aid, not a
  guarantee; give Desktop halves the same scrutiny you'd give a Python half.
- **No runtime overrides of Hermes.** Listed plugins extend Hermes through
  its public surfaces (hooks, middleware, provider profiles, Desktop SDK slots)
  and never replace core functions, methods or Desktop UI in place: two plugins
  patching the same seam would break each other, and a core release could break
  both. Admission's `no core override` check refuses Python that rebinds Hermes
  modules, classes or their tables at runtime, and the `desktop surface` lint
  refuses `desktop/plugin.js` code that queries the app's own markup to restyle,
  hide, click or rewrite core UI.
- **Capability declarations.** Entries state up front which tools, hooks, and
  middleware the plugin provides and which environment variables (API keys
  etc.) it needs, so you can judge its blast radius before installing.
- **Removed list.** Plugins pulled from the catalog (for example after a
  security incident) go on `plugin-catalog/removed.yaml` with a reason and
  date. Matching is by name or repository identity — `git@`, `ssh://`,
  `http://` and `www.` spellings of the same repo all match. The installer
  refuses to install anything on the removed list, and a plugin that lands on
  the list *after* you installed it stops updating, cannot be enabled and is
  refused at load time (`hermes plugins remove <name>`, or reinstall with
  `--allow-removed` to keep it knowingly).
- **Installed ≠ enabled.** Installing a catalog plugin puts it on disk; like
  any plugin it must still be enabled before it loads. See
  [Plugins → Enabling and disabling](https://funcoding.ai/agents/hermes-agent/user-guide/features/plugins/).

<div class="callout callout-warning">

**Catalog review is a point-in-time review**

A catalog entry means the pinned commit was looked at by a human, capability
declarations were checked, and the repo met the submission bar. It is not a
security audit, and it says nothing about other commits in the same
repository. Review the code of anything you give credentials to.

</div>

## Installing from the catalog

```bash
# Install a reviewed catalog entry by name (checks out the pinned SHA)
hermes plugins install <name>

# Then enable it, as with any plugin
hermes plugins enable <name>
```

The install prompt shows the entry's capability summary — declared tools,
hooks, and required env vars — before anything is cloned. In a terminal it
then asks "Enable now?", so the two commands above are one step when you
answer yes (`--enable` / `--no-enable` answer it for scripts).

The catalog name and the plugin's own manifest name can differ. Every later
command (`enable`, `disable`, `show`, `capabilities`, `update`, `remove`)
accepts either one: the catalog name resolves through the install record
Hermes wrote when it cloned the entry, never through a file in the plugin's
own repo. For example the `touchdesigner` entry (a portable Agent Plugins v1
package that bundles the twozero MCP server with the `touchdesigner-mcp`
skill) installs as `td`, kept short so its generated MCP tool names stay
under provider function-name limits:

```bash
hermes plugins install touchdesigner
hermes plugins enable touchdesigner   # same as: hermes plugins enable td
```

In the Desktop app a package with both an agent half and a Desktop half
(`desktop/plugin.js`) is one row with one switch per half. Turning the
package on (the install dialog's **Enable agent plugin after install**, or
the row's **Agent** switch) turns its Desktop half on as well, unless you
switched that half off yourself. Turning it off stays per half, because the
Desktop half is shared by every profile.

Portable packages can also carry a stdio MCP server. The `snyk` entry pins the
Snyk CLI (`npx -y snyk@<version> mcp`) and bundles the `snyk-security-scan`
skill, so one install gives Hermes code, dependency, container and IaC scanning
plus the workflow for using it; the catalog name and manifest name match:

```bash
hermes plugins install snyk
hermes plugins enable snyk
```

### Updating a catalog install

`hermes plugins update <name>` never runs `git pull` for catalog installs —
it compares your installed pin against the current catalog pin and, when the
catalog moved (via a reviewed PR), prepares and dependency-validates the new SHA
before publishing it. Your
enabled/disabled state is preserved, and so are files the plugin's repo does
not track (the `config.yaml` created from its `.example`, data files, `.env`).
Symlinks among those untracked files are never followed into the new code: the
update stops before publishing and names them, so replace each with a regular file.
Dependency and cache directories (`.venv/`, `venv/`, `node_modules/`, tool caches)
are not carried at all, links included; the updated plugin rebuilds its dependencies.
For monorepo/subdirectory installs, which do not carry a local Git checkout,
update preserves user-state files the new revision does not ship. Plugin code and
control surfaces remain revision-owned and are not resurrected from the old install:
source files (Python, JavaScript/TypeScript including `.mjs`/`.cjs`/`.jsx`/`.tsx`,
shell, Ruby, Perl, PHP), the top-level `dashboard/`, `desktop/`, `skills/`,
`sidecar/` and `node_modules/` directories, the plugin manifest, `mcp.json` and
dependency metadata (`pyproject.toml`, `package.json`, lockfiles). If a user-state
path conflicts with the new tree's file/directory layout, the update stops before
publication so the installed copy — and the user's data — remain intact.
Edits you made to *tracked* files are not carried onto the new code; copies are
saved under `~/.hermes/plugins-backup/<name>-<sha>/` and the update warns you.
If the new pin renames the plugin's manifest, the old directory is removed and
your enabled flag follows the new name. `hermes plugins list` shows catalog
installs as `catalog:<tier>@<sha>` so you can see provenance at a glance.

PM validates the dependencies of an active plugin before its new code replaces
the installed version. A version, scan, dependency, or publication failure keeps
the working code and dependency selection. Disabled plugins stay disabled.
Provenance is recorded by the installer in `~/.hermes/plugins/.install-metadata.json`,
outside the plugin's own tree — a repository cannot ship a file that makes it
look like a reviewed catalog install. (The `.hermes-catalog.json` inside the
plugin directory is a convenience copy only.) Installing a catalog entry with
`--ref <sha>` records the SHA you actually checked out, so `list`, the Desktop
Plugins tab and `update` all report it as off the reviewed pin.
Custom Git plugins retain their recorded Git/feed update policy but use the same
PM validation and publication path.

### Names not in the catalog

A bare name that isn't a catalog entry is an error: there is no second,
unreviewed name index. Install such plugins by `owner/repo` or Git URL instead
(custom source, see below), or submit them to the catalog.

### Live refresh

The docs build publishes the catalog as one JSON document
(`https://hermes-agent.nousresearch.com/docs/api/plugin-catalog.json`).
`search`/`install`/`update` fetch it at most every six hours and cache it under
`~/.hermes/cache/`, so new entries and removals reach installed clients without
updating Hermes. Offline, the cached copy is used for up to 24 hours, then the
copy shipped with your checkout takes over (a failed fetch is remembered for a
minute, so `plugins list` and the dashboard's Plugins page pay at most one
connection timeout, not one per installed plugin). When the cached document and
your checkout disagree on an entry's pin, the newer of the two wins — a git
checkout whose catalog was committed after the document was published (a fresh
`hermes update`) installs its own pin, never the cached older one. Removals
from the in-tree list and the live list are always both enforced, whatever the
cache's age.

### Custom git URLs are different

`hermes plugins install <git-url>` still works for any repository, but it
bypasses the catalog entirely:

- **No review** — you get whatever is at the branch tip, not a reviewed pin.
- **A warning banner** is shown to make clear the code is unvetted.
- The removed list is still consulted (a known-bad repo is refused by URL).

Use the git-URL path for your own plugins and repos you already trust; use the
catalog for discovery.

## Submitting a plugin to the catalog

Submissions are pull requests that add one `plugin-catalog/<name>.yaml` file.
The complete guidelines live in
**[Submitting to the plugin catalog](https://funcoding.ai/agents/hermes-agent/developer-guide/plugins/catalog-submission/)**:
what to check before you submit, how the PR and review work, every admission
rule, and how pin updates, delisting and removal work. That page mirrors the
canonical rules in the
[plugin-catalog README](https://github.com/NousResearch/hermes-agent/tree/main/plugin-catalog).

In short, a listed plugin is submitted by its owner (or added in a reviewed
maintainer sweep), lives in a public repository, pins an exact commit, passes
`hermes plugins validate` in catalog CI, never updates itself, and extends
Hermes only through public hooks and the Desktop SDK, never by patching core
code or Desktop UI at runtime.

## See also

- [Plugins](https://funcoding.ai/agents/hermes-agent/user-guide/features/plugins/) — the plugin system itself: manifest format, enabling,
  configuration
- [Built-in Plugins](https://funcoding.ai/agents/hermes-agent/user-guide/features/built-in-plugins/) — plugins that ship with Hermes
- [Build a Hermes Plugin](https://funcoding.ai/agents/hermes-agent/developer-guide/plugins/) — write your own
- [Plugin Catalog page](https://hermes-agent.nousresearch.com/plugins) — the browsable catalog
- [Submitting to the plugin catalog](https://funcoding.ai/agents/hermes-agent/developer-guide/plugins/catalog-submission/) — admission rules and the submission guide