Install a plugin

For: tenant administrators and plugin authors.

Install a plugin from its source, inspect what it needs and may do, and choose the nodes that will run it. The edge locks the source to a commit or digest before distributing the checked version.

Use the companion pages for updates, rollout controls, grants and removal. Each task keeps the checks and approval rules that apply to it.

Install

oz0 plugin install https://github.com/acme/oz-github-tools

Without --ref, the edge takes the highest vX.Y.Z tag, compared as numbers, or the default branch when there is no release tag. Pin a branch, a tag or a full commit SHA with --ref:

oz0 plugin install https://github.com/acme/oz-github-tools --ref v1.4.0
oz0 plugin install https://github.com/acme/oz-github-tools --ref main --select team=platform

--select key=value installs it only on nodes with that label; repeat it to require several. --tenant picks the tenant (default default). Installing a plugin that is already installed updates it.

In dev mode the edge also accepts file:// URLs. A folder, a bundle file or an OCI reference installs too, in dev mode and in a cluster: see Folders, bundles and OCI.

A plugin made in the studio installs from the tenant's workspace the same way: oz0 plugin install workspace:<folder>@<revision>.

A Claude Code plugin, an Agent Plugin, a Claude Code marketplace's entry (--plugin <name>) and a server of the MCP Registry (mcp:<name>) install the same way too, once you accept the inventory of every command they run: see Bring your Claude Code plugins and Agent Plugins. A plugin listed in a trusted plugin index installs by name, pinned to the commit and content the listing names: oz0 plugin install hub:com.example/[email protected].

A plugin whose egress lets the tenant's sandboxes reach a host they could not reach before does not install at once. The install waits as a change request with its delta (each new entry and what kind of widening it is), the command prints it and exits 0, and nothing changes until a tenant admin approves it with oz0 change approve. --approve-egress on plugin install and plugin update approves it in the same command after printing the delta, when you may approve. A plugin whose hosts the tenant already permits installs as before. See Reviewed changes.

A quality gate for plugins with evals

A version of a plugin that has evals runs them on one test node before the fleet gets it, and is stopped when it does worse than its thresholds or the version it replaces. Until then the fleet keeps the installed version:

Testing team 0.2.0 (commit ff4d7eae2c6d…) in tenant default before the fleet gets it: its evals run on a test node.
Until it passes, the fleet keeps team 0.1.0.

--no-gate installs it at once. See Quality gates for how the verdict works.

See how it is going

oz0 plugin list

plugin list shows every plugin, its locked commit (and its folder, for one in a folder), and each node's state with it: whether the node has built and started it, the functions it found, or the error it hit. For a plugin with evals it also shows the gate of its latest version: waiting, testing, passed or stopped, and why.

Where a version came from

When a version's commit was made by an agent, through a reviewed changeset, its message carries the OZ trailers push_changes wrote: the job, the agent and its plugin version, the model and the evidence. The install reads them from the commit it fetched, or, for a pull request merged with a merge commit, from the commit it merged, but only when that commit is all the merge brought in (its parent is already in the branch merged into, up to 64 commits back).

A merge that brought in more, such as a release merge of a branch where people committed too, or a person's commit on top of the agent's, makes the version a person's. A hub install whose commit carries none takes what the index's listing says of the version, which is the job and the agent as text, the model alias and the evidence counted by kind. The record is kept with the version and shown where the version is:

oz0 plugin versions triage
# VERSION  COMMIT        ROLE       GATE    FIRST             MADE BY
# 1.5.0    4be1c0d93a77  installed  passed  2026-10-20 08:00  agent improver in job job-0192...
# 1.4.0    9f3e2a1b7c55  -          passed  2026-10-01 12:00  -
#
# 1.5.0:
#   Made by an agent:
#     Job:       job-0192... (https://oz.example/t/acme/jobs/job-0192...)
#     Agent:     improver of [email protected]
#     Model:     smart (anthropic/claude-sonnet-5-5)
#     Evidence:  comparison:cmp-3 (better)
#     Read from: the commit's OZ trailers
oz0 plugin show triage        # the installed version's record too

The plugin's page in the console says the same under Made by an agent, with the job, each evidence read and each comparison as a link (findings and eval runs by their IDs), and Show versions lists every version the tenant has had. The trailers are whatever the commit's author wrote, so a record that names a job this tenant does not have (a version made in someone else's tenant, or trailers a person typed) is shown as text, never as a link into it.

Related tasks

• Review an install: Review requirements, permissions and policy changes before installing.
• Install from a source: Choose a folder, standalone agent or private repository and meet the source-fetch rules.
• Update a plugin: Update the installed version and review changes of ownership or dependencies.
• Roll out a plugin: Release a new version through canaries and handle failed or interrupted rollouts.
• Grant access between plugins: Review, grant and revoke access to parts owned by another plugin.
• Retire or remove a plugin: Wind down plugin use, inspect dependents and remove old versions.