Read index version records
For: tenant administrators and plugin authors.
Interpret version states, SBOMs and install conflicts.
Version states
Every installed plugin version, and every listed one, has three states, each a fact the platform checked, and none implies another:
| State | It means | Set by |
|---|---|---|
| Saved | The platform holds the version's bytes | A Git commit installed, a workspace revision, an uploaded or pushed bundle |
| Validated | Its evals passed | The install's quality gate passing for that version, or a plugin test report of exactly the listed files that the index carries |
| Published | An index the cluster reads lists it, active or deprecated | The index |
plugin list shows the furthest in its STATE column and the rest beside it ("published in acme, not validated"); the Plugins page, an agent's capability card and the hub do the same. A published version without evals is published and not validated, and every screen says so. "Validated" says only that the evals passed, with which engine and on which day; it says nothing about the plugin being safe or fit for a purpose.
SBOMs
Each plugin version has a software bill of materials: a CycloneDX 1.6 JSON file of the packages it installs, for your vulnerability scanner.
| Where | What it lists |
|---|---|
plugin pack writes sbom.cdx.json into the folder and the bundle | The packages of the plugin's uv.lock and package-lock.json, each with its version, package URL and hashes |
A hub listing (generated.sbom) | The same SBOM's SHA-256, how many packages it lists and their package URLs; whether the bundle carries the same file, or one that is out of date |
An installed version: oz0 plugin sbom <name> -o team.cdx.json, the Plugins page | Those packages, plus every package the edge pinned by hash when it installed the version, with the hashes of each file a node may install, and its tools' container images by digest |
| An evidence bundle | The installed SBOM of each plugin version the period used, next to its factsheet |
The file is the same for the same version, wherever it is made: components sorted, no scan time, a serial number made from the content. Its metadata.component is the plugin version, bound to the SHA-256 of its other files, so an SBOM cannot be passed off as another version's. Commit sbom.cdx.json with the lockfiles it comes from; plugin inspect says when the bundled one no longer matches them. An SBOM lists what the lockfiles pin; the vulnerability scan compares an installed version's with known advisories.
Plugins that cannot be installed together
A tool ID belongs to one plugin of a tenant (see the catalog), and so do an agent or flow name and a plugin's own name. An index lists, for each version, the other plugins it lists that share one of them: CLASHES in index plugins, clashes in --json, and "Cannot be installed together with" on the hub's plugin pages. A hub install warns with them before it fetches anything, and says which of them the tenant has:
warning: hub:com.example/team: index acme lists com.example/team 0.1.0 as not installable in one tenant with
io.github.bob/team-tools 1.0.0, 1.1.0 (tool team): a tool ID, an agent or flow name and a plugin name each belong to
one plugin of a tenant; tenant default has io.github.bob/team-tools 1.1.0 installed, so the install is refused unless
that clash is one the installed version of team already had: remove plugin team-tools first (oz0 plugin remove team-tools)
The warning is the index's view of the listed versions. The install still checks the bytes it installs against what the tenant has, and refuses a taken tool ID, agent or flow name whatever the index says. Two listings of the same plugin name by different publishers clash too. A hub install never replaces a plugin the tenant installed from another listing: it is refused before anything is fetched (plugin preview shows the refusal as a warning), and you remove the installed plugin first if you mean to swap them.
A plugin you installed from a Git URL, a path or an upload is replaced by a hub listing of the same name, with the warning.