docs: document the plugin marketplace

Add a public Plugin Marketplace page covering both audiences: operators
using the in-app catalog (Browse/Installed tabs, one-click install,
Update to vX, the Sources dialog for team/corporate registries, plugin
icons, feature-flag gating, sideloading still works) and plugin authors
publishing into it (one-repo-per-plugin GitHub Release assets, the
optional manifest icon field, submitting a plugins.yaml PR to the
official catalog, GitHub-stars-only ranking, and hosting your own
index.json source).

Also cross-link the new page from plugins.md (replacing the now-false
"No plugin marketplace" security note), plugins-authoring.md, and
plugins-manifest.md (new icon field row); register it in meta.json and
coverage.json.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Kandev Agent
2026-07-19 17:16:26 +01:00
parent bc2f310e73
commit b0382e77ae
6 changed files with 220 additions and 10 deletions
+8
View File
@@ -273,6 +273,14 @@
"sources": ["apps/backend/internal/plugins/handlers.go", "apps/backend/pkg/pluginsdk/host.go", "apps/web/lib/plugins/host-api.ts"],
"tests": ["apps/backend/internal/plugins/service_test.go", "apps/backend/internal/plugins/manifest/manifest_test.go", "apps/web/lib/plugins/host-api.test.ts"]
},
{
"id": "plugin-marketplace",
"audiences": ["operator", "contributor"],
"stability": "experimental",
"docs": ["plugins-marketplace"],
"sources": ["apps/backend/internal/plugins/marketplace/catalog.go", "apps/backend/internal/plugins/marketplace/sourcestore.go", "apps/web/lib/api/domains/marketplace-api.ts"],
"tests": ["apps/backend/internal/plugins/marketplace/catalog_test.go", "apps/backend/internal/plugins/marketplace/sourcestore_test.go", "apps/web/hooks/domains/plugins/use-marketplace.test.ts"]
},
{
"id": "websocket-protocol",
"audiences": ["contributor", "integrator"],
+1
View File
@@ -43,6 +43,7 @@
"release-process",
"---Plugins---",
"plugins",
"plugins-marketplace",
"plugins-authoring",
"plugins-manifest",
"---Office---",
+12
View File
@@ -480,6 +480,18 @@ Install the resulting tarball via **Settings > Plugins** (upload) or:
curl -F "package=@my-plugin-1.0.0.tar.gz" http://localhost:38429/api/plugins/install
```
To show a custom card icon in the marketplace, ship an image in the package
(e.g. `assets/icon.svg`) and point the manifest's [`icon`
field](plugins-manifest.md#field-reference) at its package-relative path.
## Publishing to the marketplace
To make your plugin discoverable and one-click installable from inside kandev,
publish the `<id>-<version>.tar.gz` + `checksums.txt` as a GitHub **Release**
asset and either open a PR listing your repo in the official catalog or host
your own source. See [Plugin marketplace →
Publishing](plugins-marketplace.md#publishing-a-plugin).
## Iterate loop
- **UI-only or backend-only change:** edit the source, repackage
+1
View File
@@ -71,6 +71,7 @@ ui: # optional native frontend plugin
| `description` | no | string | Shown in Settings > Plugins. |
| `author` | no | string | Free-form. |
| `categories` | no | string[] | Each entry must be one of `connector`, `automation`, `tools`, `analytics`. Unknown values are rejected. |
| `icon` | no | string | Package-relative path (e.g. `icon.svg`) to an image the package ships, rendered on the [marketplace](plugins-marketplace.md) card and in plugin lists. The registry index-build resolves it to an absolute `icon_url`; for an installed plugin it is served from the extracted package. Omit it and the card falls back to a letter tile. |
| `runtime.type` | conditionally | string | `"binary"` is the only supported value. Setting it (vs. leaving it empty) makes the manifest **runtime-managed** — see "Managed vs. legacy" below. |
| `runtime.executables` | required when `runtime.type: binary` | map\<string,string\> | Key is `<goos>-<goarch>` (e.g. `linux-amd64`, `darwin-arm64`, `windows-amd64`); value is a clean, package-relative path under `server/` (no leading `/`, no `..` segments). At least one entry required; the running host's key must be present at install time. Windows values end in `.exe`. |
| `min_kandev_version` | no | string | Optional advisory; not currently enforced by the installer. |
+180
View File
@@ -0,0 +1,180 @@
---
title: "Plugin Marketplace"
description: "Discover and install kandev plugins from the in-app catalog, keep them updated, add a team or corporate source, and publish your own plugin to the official catalog."
status: experimental
---
# Plugin Marketplace
The marketplace is a discoverable, curated catalog of kandev plugins you can
browse and install from inside the app — no tarball URL required. It is
assembled from one or more **sources**: kandev ships with the official source
enabled by default, and you can add team or corporate sources alongside it.
This page covers using the marketplace (browse, install, update, add sources)
and publishing a plugin into it. For what plugins are and how the install
pipeline, enable/disable, and security posture work, see
[Plugins](plugins.md). For building one, see [Authoring a
plugin](plugins-authoring.md).
Like the rest of plugins, the marketplace is gated behind the `plugins` feature
flag (**Settings > System > Feature Toggles**) — off by default in production,
on by default in dev/e2e builds. Enabling it requires a backend restart and
surfaces **Settings > Plugins** in the sidebar.
> **Sideloading still works.** The marketplace only adds *discovery*. Installing
> a plugin by URL or by uploading a `.tar.gz` is unchanged and always available,
> even with every source disabled or offline — see
> [Plugins → Installing a plugin](plugins.md#installing-a-plugin).
## Using the marketplace
**Settings > Plugins** has two tabs:
- **Installed** — the plugins on this instance, with Enable / Disable /
Uninstall and an **Update** button when a newer version is available.
- **Browse** — the merged catalog across all enabled sources.
### Browse and install
Open **Settings > Plugins > Browse**. Each plugin shows as a card with its
name, description, author, categories, source repository link, latest version,
and GitHub star count. To narrow the list:
- **Search** — type in the search box to match plugin name or description.
- **Category** — filter to a single category with the category dropdown.
- **Sort** — **Most stars** (default), **Recently updated** (by latest release
/ repo activity), or **Name**.
Stars are a **sort hint, not a quality score**. kandev collects no download or
usage telemetry, so there is no "most installed" metric — ranking is GitHub
stars only, and "Recently updated" surfaces new or actively maintained plugins
that high-star incumbents would otherwise bury.
Click **Install** on a card to install it. This resolves the entry to its
latest release tarball and runs the same verified install pipeline as
install-by-URL (`POST /api/plugins/install`) — see [Plugins → Installing a
plugin](plugins.md#installing-a-plugin) for the exact steps and integrity
checks. A card for a plugin you already have at the latest version shows
**Installed** instead of an install button.
Plugin-provided icons render on the cards. A plugin that ships an icon (via the
manifest's `icon` field) shows it; otherwise the card falls back to a neutral
letter tile.
### Keep plugins updated
When the marketplace advertises a newer version than the one you have
installed, the **Installed** tab shows an **Update to v`<version>`** button on
that plugin's row. Clicking it reinstalls the newer tarball through the normal
pipeline; Enable, Disable, and Uninstall are unchanged.
Updates are never automatic — kandev surfaces the newer version and waits for
an explicit click. There are no update channels and no background auto-update.
### Add a team or corporate source
The **Sources** button on the Browse tab opens the **Marketplace sources**
dialog. The official kandev source is present by default, badged **Official**,
and cannot be removed. To add another:
1. Click **Sources**.
2. Enter a **name** (e.g. `Acme Internal`) and the **URL** of an `index.json`
document (see [Host your own source](#host-your-own-source) below).
3. Click **Add**.
Its plugins are then merged into the Browse tab alongside the official ones.
You can enable/disable a source without deleting it, and remove any non-official
source. Adding a source is an explicit act of trust in its maintainer, much
like `brew tap`-ing a third-party tap.
Notes:
- When the same plugin `id` appears in more than one source, the **first
configured source wins** (the official source is always first); later
duplicates are hidden.
- A source that is unreachable or serves malformed JSON is reported as
**degraded** — its entries are omitted, but the healthy sources still load.
- Configured sources persist across restarts; the fetched catalog itself is a
short-lived cache and is re-fetched on demand.
## Publishing a plugin
Getting a plugin into the catalog follows a **one-repo-per-plugin** model,
mirroring Obsidian's community-plugin registry: each plugin lives in its own
public GitHub repository and publishes its package as a GitHub **Release**
asset; the official catalog is a curated pointer list that names *which repos*
are included. The descriptive metadata (name, description, version, tarball
URL, stars) is always read from your latest release, so a listing can never
drift from what actually ships.
### 1. Publish the plugin package as a release
Package your plugin as usual (see [Authoring a plugin →
Packaging](plugins-authoring.md#packaging)) and cut a GitHub **Release** whose
assets include both:
- `<id>-<version>.tar.gz` — the plugin package, and
- `checksums.txt` — the integrity manifest the install pipeline verifies.
The release must pass the standard package integrity gate. The
`kdlbs/kandev-plugin-template` starter repo is the recommended way to bootstrap
a repo with the right layout and a release workflow.
### 2. Add an icon (optional)
Add an `icon:` field to your `manifest.yaml` — a **package-relative path** to an
image your package ships (for example `icon.svg`). The catalog resolves it to
your icon and renders it on the plugin card; without it, the card shows a letter
tile. See the [Plugin manifest reference](plugins-manifest.md#field-reference).
### 3. Submit to the official catalog
The official source is curated: a plugin appears only after a maintainer merges
a PR that lists it.
1. Fork `kdlbs/kandev` and add one entry to
[`plugin-registry/plugins.yaml`](https://github.com/kdlbs/kandev/blob/main/plugin-registry/plugins.yaml)
pointing at your public repo:
```yaml
plugins:
- id: my-plugin # MUST equal the `id` in your plugin manifest
repo: your-org/your-plugin-repo # owner/name
categories: [productivity] # optional
```
`id` must match your manifest `id` and be unique in the file. `featured` is a
maintainer-only pin — leave it out of submissions.
2. Open a pull request. CI validates `plugins.yaml` against
[`plugin-registry/schema.json`](https://github.com/kdlbs/kandev/blob/main/plugin-registry/schema.json)
and checks that your `id` matches your repo's latest-release manifest `id`.
3. A maintainer reviews and merges. The index-build workflow picks up your entry
and your plugin appears in the in-app catalog on the next build.
Ranking in the catalog is **GitHub stars only** — there is no download or usage
telemetry to game. Full submission details are in
[`plugin-registry/README.md`](https://github.com/kdlbs/kandev/blob/main/plugin-registry/README.md).
## Host your own source
You do not have to PR into the official registry to share plugins internally.
Any URL that serves an `index.json` document of the catalog shape can be added
as a marketplace source (see [Add a team or corporate
source](#add-a-team-or-corporate-source)), and its plugins merge into the Browse
tab alongside the official ones. This is the recommended path for a team or
corporate registry — no PR to the main repo.
The `index.json` document is the fetch contract between a source and kandev. The
simplest way to produce one is to copy the official registry's
`plugin-registry/` directory into your own repo — its `plugins.yaml` +
[`build-index.mjs`](https://github.com/kdlbs/kandev/blob/main/plugin-registry/build-index.mjs)
build script (zero-dependency Node) + GitHub Action resolve each listed repo's
latest release into a full catalog record and publish the generated
`index.json` to GitHub Pages. Point kandev at that Pages URL. The document
shape, the build pipeline, and the source data model are specified in the
[plugin marketplace spec](https://github.com/kdlbs/kandev/blob/main/docs/specs/plugins/marketplace.md).
Related: [Plugins](plugins.md), [Authoring a
plugin](plugins-authoring.md), [Plugin manifest
reference](plugins-manifest.md).
+18 -10
View File
@@ -10,9 +10,10 @@ Plugins extend kandev without forking core: a plugin ships a **Go backend**
that kandev spawns and supervises as a subprocess over a strict typed gRPC
protocol, and can optionally ship a **native frontend bundle** that kandev
loads into the SPA. This page covers what plugins are, how to install and
manage them, and the current security posture. For building a plugin, see
[Authoring a plugin](plugins-authoring.md). For the manifest schema, see
[Plugin manifest reference](plugins-manifest.md).
manage them, and the current security posture. To discover and install plugins
from the in-app catalog, see the [Plugin marketplace](plugins-marketplace.md).
For building a plugin, see [Authoring a plugin](plugins-authoring.md). For the
manifest schema, see [Plugin manifest reference](plugins-manifest.md).
Plugins are an operator-level, instance-wide capability — there is no
per-user plugin access. They are gated behind the `plugins` feature flag
@@ -41,10 +42,14 @@ its own action right where you message an agent.
## Installing a plugin
Open **Settings > Plugins** and click **Install plugin**. You can install
from a URL (kandev downloads the tarball) or by uploading a `.tar.gz` file
directly. No credentials are ever shown or copied — installing a plugin has
nothing to reveal, unlike a webhook-secret/API-key registration flow.
The easiest way to install is from the in-app catalog — **Settings > Plugins >
Browse**, then **Install** on a card (see the [Plugin
marketplace](plugins-marketplace.md)). To install a plugin that is not in a
configured catalog, open **Settings > Plugins** and click **Install plugin**.
You can install from a URL (kandev downloads the tarball) or by uploading a
`.tar.gz` file directly. No credentials are ever shown or copied — installing a
plugin has nothing to reveal, unlike a webhook-secret/API-key registration
flow.
![The Install plugin dialog with From URL and Upload file tabs and a drag-and-drop area for a .tar.gz package.](../screenshots/plugin-install-dialog.png)
@@ -188,9 +193,12 @@ identically to an unsigned one; signing is not required in v1.
realm boundary) is explicit future work — see below.
- **Package integrity is always checked; signing is optional.** See
"Signed vs. unsigned packages" above.
- **No plugin marketplace.** Install-by-URL/upload is a manual, single-plugin
action; there is no central catalog, one-click install, or automatic
discovery.
- **Curated marketplace, no auto-install.** The [Plugin
marketplace](plugins-marketplace.md) adds one-click install from a catalog,
but the official source is PR-curated (a plugin appears only after a
maintainer approves it), install is always an explicit operator action, and
updates require an explicit click — there is no automatic discovery or
background install. kandev collects no download or usage telemetry.
Related: [Authoring a plugin](plugins-authoring.md), [Plugin manifest
reference](plugins-manifest.md), and [Extending Kandev](extending-kandev.md).