covey-plugins — the target-system plugin index

The catalogue Covey instances read to find and install target-system plugins: helpdesks, issue trackers, mail, chat, and anything else an agent should be able to work in.

This repository holds no plugins. It holds one entry file per plugin, and each entry points at an artefact that lives wherever its author keeps it — pinned by digest, so what an instance installs cannot change behind its back.

plugins/redmine.json  ──── url + sha256 ────►  github.com/example/covey-redmine  (any host)
        │
        └──► catalog.json   ← generated by CI; this is what an instance fetches

Using it

A Covey instance reads one file over plain HTTP. Nothing else — no API, no token, no clone.

COVEY_MARKETPLACE_URL=https://raw.githubusercontent.com/benjaminLedel/covey-plugins/main/catalog.json

That is the default. Two other settings are just as valid:

• Your own catalogue. Fork this repository, or serve your own catalog.json from GitLab, S3, an internal web server or a file:// path. This is also how you distribute internal plugins that must not be public — the same file, a different URL.
• Empty. The marketplace is off; the store shows only what is compiled in and what the organisation uploaded by hand.

Installing never activates. A plugin arrives disabled, and somebody has to switch it on and store its credentials before an agent can use it. Updates are never automatic either: a newer version shows up as a note with a diff, and a human confirms it.

Listing a plugin

Open a pull request that adds plugins/<name>.json. See CONTRIBUTING.md for the full walk-through; the short version:

{
  "name": "redmine",
  "label": "Redmine",
  "description": "Issue tracker: read issues, comment, change status.",
  "category": "ticketing",
  "kind": "custom",
  "publisher": "example-gmbh",
  "homepage": "https://github.com/example-gmbh/covey-redmine",
  "license": "MIT",
  "versions": [
    {
      "version": "1.2.0",
      "url": "https://raw.githubusercontent.com/example-gmbh/covey-redmine/v1.2.0/covey/redmine.json",
      "sha256": "…",
      "covey_min_version": "0.9.0"
    }
  ]
}

CI validates the entry, fetches the artefact, verifies the digest and lints the plugin. On merge it regenerates catalog.json.

What may be listed

Three kinds of plugin are installable at runtime, and those three are what this index distributes:

kind	Artefact	What it is
custom	a JSON manifest	REST actions, webhook mapping and auth headers, interpreted by Covey's generic engine
mcp	an MCP server configuration	a reachable MCP endpoint whose tools become agent actions
wasm	a WebAssembly module	real code — Go, TinyGo, Rust — for plugins a declarative file cannot express. Start from covey-plugin-template

builtin entries may also appear, for findability: those ship compiled into Covey and are activated rather than installed. Their code goes to the Covey repository, not here.

Code is welcome; unconfined code is not. A wasm module has no sockets and no filesystem, and it never sees the credential — it names a path, and Covey adds the base URL and the token. Native code (.so, platform binaries) is not distributed here and will not be: it would run unconfined inside the control plane's process.

Because nobody can review a compiled binary, wasm entries are rebuilt from source by CI and refused unless the result matches the pinned digest byte for byte. See CONTRIBUTING.

What a manifest plugin can reach

A manifest cannot name a host. Every action path is relative to the base URL, and the base URL comes from the credential the installing organisation stored (<name>_url). A listed plugin therefore cannot redirect anybody's brokered token to a server of its choosing.

MCP entries are the exception: they name an endpoint. Expect a review of that host, and expect instances to put it through their egress allowlist.

Trust

• Every version is pinned by sha256. The linked repository may be force-pushed, retagged or deleted; a changed artefact simply stops installing.
• Published versions are append-only. Fixing a bug means a new version, never an edit to an old one.
• Every change that reaches an instance is a merge here — a reviewable diff, in one place, with a history.

Report a plugin that misbehaves by opening an issue. An entry can be withdrawn from the catalogue; that stops further installations but does not reach into instances where it is already installed.

Layout

Path	Contents
plugins/	one entry file per plugin — the only place a pull request normally touches
catalog.json	generated from plugins/ by CI; do not edit
schema/entry.schema.json	the entry schema, also what CI validates against
schema/catalog.schema.json	the shape of the generated catalogue, for anyone writing a reader or serving their own
scripts/build_catalog.py	validation and catalogue assembly (also runnable locally)
examples/	complete example entries, one manifest and one MCP, excluded from the catalogue
SECURITY.md	reporting, and what withdrawing a plugin does and does not do

Running the checks locally needs Python 3 and two packages:

pip install jsonschema referencing
python3 scripts/build_catalog.py --verify

Without them the script still runs and still builds the catalogue — it says which checks it skipped rather than passing quietly.

Licence

The schema and the tooling in this repository are MIT (see LICENSE). Each listed plugin carries its own licence, declared in its entry and owned by its publisher.