Teknium
41b4555ed9
- hermes_cli/plugins_cmd_catalog.py: new sibling owning resolution, the
.hermes-catalog.json provenance sidecar, search/info/validate, re-pin on
update, and the dashboard/TUI payload builders. plugins_cmd.py only
gains the hooks (cmd_install catalog branch, cmd_update / dashboard
update re-pin, dashboard_install_plugin catalog_name + kill list,
dispatch entries); the community index (plugin_index.py) is gone.
- hermes_cli/plugin_catalog.py: catalog_dir parameter replaces the
test-only HERMES_PLUGIN_CATALOG_DIR env var; live refresh reads ONE
published document (/docs/api/plugin-catalog.json, 6h cache, in-tree
fallback) instead of the unauthenticated GitHub contents API (60 req/h,
1 request per entry); in-tree and live removals are unioned so a stale
cache can never un-block.
- Catalog route lives in web_routers/dashboard_ui.py (the facade is off
limits); _plugin_runtime_status shared from web_server_dashboard.py;
hub rows carry removed_reason. TUI plugins.manage gains catalog_name
install, catalog row fields and an update action.
- plugin_validate: the probe context honours ctx.get_config defaults
(real plugins do int(ctx.get_config("timeout", 180)) in register()).
- Installed-state merge matches through the sidecar's catalog_name
first — catalog names rarely equal manifest names.
- extract-plugins.py emits plugin-catalog.json; deploy-site triggers on
plugin-catalog/** so entry merges republish it.
144 lines
6.0 KiB
Markdown
144 lines
6.0 KiB
Markdown
---
|
|
sidebar_position: 13
|
|
sidebar_label: "Plugin Catalog"
|
|
title: "Plugin Catalog"
|
|
description: "Browse and install reviewed, SHA-pinned Hermes plugins from the curated catalog"
|
|
---
|
|
|
|
# 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](/plugins)** — search, tier filters
|
|
(Official / Community), capability chips, and copyable install commands for
|
|
every entry.
|
|
|
|
The catalog complements — it does not replace — the existing
|
|
[plugin system](plugins.md). 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.
|
|
|
|
## 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` |
|
|
| `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 |
|
|
| `tier` | `official` (maintained by NousResearch) or `community` |
|
|
| `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) |
|
|
| `docs_url` | External documentation link (optional) |
|
|
|
|
## 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.
|
|
- **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. The installer refuses to install anything on the removed list.
|
|
- **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](plugins.md).
|
|
|
|
:::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.
|
|
:::
|
|
|
|
## 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.
|
|
|
|
### 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), force-reinstalls at the new SHA. Your
|
|
enabled/disabled state is preserved. `hermes plugins list` shows catalog
|
|
installs as `catalog:<tier>@<sha>` so you can see provenance at a glance.
|
|
|
|
### 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 copy shipped with your checkout is used. Removals
|
|
from the in-tree list and the live list are always both enforced.
|
|
|
|
### 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 full checklist lives in the
|
|
[plugin-catalog README](https://github.com/NousResearch/hermes-agent/tree/main/plugin-catalog);
|
|
in short, an entry must be:
|
|
|
|
1. **Owner-submitted** — the PR author owns or maintains the plugin repo.
|
|
2. **A public repository** — the `repo` URL is publicly cloneable.
|
|
3. **Released** — the repo has real releases/tags, not just a default branch.
|
|
4. **Passing validation** — the catalog validation GitHub Action is green on
|
|
the PR (schema, SHA format, reachability).
|
|
5. **Pinned to settled code** — the pinned SHA is at least **2 weeks old**, so
|
|
the catalog never points at code pushed moments before review.
|
|
|
|
Pin updates (bumping `sha` to a newer commit) follow the same PR + review
|
|
process.
|
|
|
|
## See also
|
|
|
|
- [Plugins](plugins.md) — the plugin system itself: manifest format, enabling,
|
|
configuration
|
|
- [Built-in Plugins](built-in-plugins.md) — plugins that ship with Hermes
|
|
- [Build a Hermes Plugin](/developer-guide/plugins) — write your own
|
|
- [Plugin Catalog page](/plugins) — the browsable catalog
|