# The plugin index

> What a hub serves, how the app and hive read it, and what happens to an entry they cannot read.

Source: https://hivemind.griiken.com/guide/hub-index/

A hub lists its plugins in one file, `index.json`. <Tooltip tip="The catalogue Hivemind installs agents and plugins from." cta="Glossary" href="https://hivemind.griiken.com/guide/glossary/#hivehub">HiveHub</Tooltip> serves its own at `/api/v1/index.json` on its site. **Settings → Plugins** and `hive agents install`, `hive views install`, `hive widgets install` and `hive tools install` read it.

## What the index holds [#what-the-index-holds]

The index is `{ "version": 1, "plugins": [...] }`. Each entry names one plugin:

| Field | What it says |
|---|---|
| `id`, `type` | the plugin's id and its kind: `agent`, `view`, `widget`, `tool` or `package` |
| `name`, `description`, `author`, `version` | what the list shows |
| `path`, `source` | the folder of its files, and the https address they are under |
| `files` | every file, each with its SHA-256 |
| `minAppVersion` | the oldest Hivemind it runs on: an agent's or tool's own, or for a view, widget or package the release that first reads a field it uses ([since.ts](https://github.com/dip497/hivemind/blob/main/packages/hive-hub/src/since.ts)) |
| `bin`, `icon` | an agent's program and its mark |
| `category` | where it is listed |
| `members` | a package's plugins: each one's kind, id, name and permissions |

How each file is checked before it installs: [What you install from HiveHub](https://hivemind.griiken.com/guide/security-and-privacy/#what-you-install-from-hivehub).

## An entry the app cannot read [#an-entry-the-app-cannot-read]

The app reads each entry on its own. An entry it cannot read is skipped, and the rest are still listed. That happens when its id does not fit its kind, a field is missing or malformed, or its kind is one this Hivemind does not know.

- `hive views install @owner/name` and the other install commands say why, when the plugin you asked for is the one skipped.
- The app writes each skipped entry and its reason to its log.

A file that is not a version 1 index at all is refused as a whole.

## Limits [#limits]

An index lists at most 2,000 plugins and is at most 4 MB. Past 2,000, the rest are skipped and the app says how many were listed.

## The hub kit [#the-hub-kit]

The index format and its reader are one package in the Hivemind repository, the hub kit (`@hivemind/hub`). The app and `hive` read every index with it.

The kit also holds the checks a plugin folder must pass. A hub built on the kit runs them before it lists a plugin. The app runs the same checks on the files it downloaded, before it installs them:

- at most 200 files, 2 MB per file and 8 MB in all, each a plain relative path;
- one manifest Hivemind accepts: `hivemind-package.json`, `agent.yaml`, `hivemind-view.json`, `widget.json` or `hivemind-tool.json`;
- in a package, every member checked as that kind is checked alone, and owned by the package's owner;
- an id that fits its kind, and a category Hivemind knows;
- a view's entry file, a widget's code or drawing, and a version on widgets and tools.

A folder that fails, or that says it is another plugin than the one listed, is not installed, and the install says why.

A hub that cannot read a whole folder in one go, such as one on a Cloudflare Worker, reads it a few files at a time. `firstReads` names the manifests and README at the folder's top, from its paths and sizes. With their texts, `planRead` names everything else to read, which for a package is only what installs, and the few files whose text the checks read. `listedFile` keeps each file's size, SHA-256 and, for those few, its text. `checkPluginListing` then gives the answer `checkPluginFolder` gives for the same files. Give it only the files `planRead` names: it holds every file it is given to the limits, so a package's sources beside its members would count.

Each Hivemind release carries the kit as `hivemind-hub-<version>.tgz`. Its one dependency, `zod`, comes from npm. It runs in Node, Bun and a Cloudflare Worker. A hub depends on it by its address on the release, for example:

```bash
npm install https://github.com/dip497/hivemind/releases/download/v<version>/hivemind-hub-<version>.tgz
```

A hub's checks are then those of one Hivemind release.

<LastValidated />