oz0 plugin install
For: Operators and developers looking up a command.
Install a plugin from a Git repository. The edge resolves the ref (default: the latest release tag, or the default branch) to a commit and locks it, checks the plugin like plugin lint, and packs it; nodes download it from the edge, never from Git.
A folder or an archive on this machine (a bundle from plugin pack, or a .tar.gz, .tgz, .tar or .zip, repacked as a bundle when it is not one) is packed here, uploaded and locked to its SHA-256 instead of a commit; an upgrade is a new upload.
A Markdown file that is a plugin of one part, such as an agent in one file (agent new), is packed alone, without what lies beside it; its manifest is generated, with the version 0.0.0-d<digest>. An OCI reference installs by digest only: the edge pulls it, with --secret naming a tenant secret with the registry's user:password, and a tag alone is refused with the digest it points to now.
Installing an installed plugin updates it: a version with evals runs them on a test node first, and a new version of a plugin that runs on two or more nodes rolls out to canaries first, step by step through health and quality gates (rollout show).
An update whose agents' contracts break the installed version's, as the generated OpenAPI documents of the two show (a narrower input, a wider or different output, an agent or flow that is gone), needs a new major version or --allow-breaking. workspace:<folder>@<revision> installs a revision of the tenant's workspace (without @<revision>, its head) the same way.
A source hub:<name>[@<version>], such as hub:io.github.alice/[email protected], resolves through the cluster's trusted plugin indexes (index list; --index picks one) to the source the listing pins, and installs it the same way, refusing a commit, content or repository other than the listed ones, and withdrawn or quarantined versions unless the index allows them. Without a version it installs the newest active one.
A Claude Code plugin (.claude-plugin/plugin.json or its default folders) or an Agent Plugin (plugin.json and mcp.json) installs from any of these sources too: the edge reads it as a file format and builds the manifest, with an optional oz0-plugin.yaml overlay (import: {}) for schemas, limits, labels and delegation. Its hooks and MCP commands run on every node, so the first install is refused with their inventory, and --accept-inventory <digest> installs it; an update whose inventory changed needs the new digest.
Its hooks see harness sessions' calls, and its agents' sessions run its MCP servers, only with --harness-extras; with --guarded-servers too, its servers that hold secrets also serve the sessions of jobs an outside event started, from outside them.
--plugin <name> installs that entry of a Claude Code marketplace (.claude-plugin/marketplace.json) at the source, through the source the entry names. mcp:<name>[@<version>], such as mcp:io.github.example/weather, installs a server from the MCP Registry as a plugin with that server as its tool, pinned to the package version the registry lists.
A plugin whose agents and flows use other plugins' tools or agents declares that under uses: in its manifest, and from v1.0 they reach only that, once a tenant admin grants it: an install whose request the plugin's grant does not cover is refused with the request, such as "pr-reviewer wants github.merge and delegation to github, from plugin github", and --accept-uses <digest> grants it.
A version that asks for more needs a new grant; one that asks for less does not. A used plugin the tenant does not have is installed first, in the same decision, from the source --dependency <plugin>=<source> names, else the plugin's uses.<plugin>.source, else a trusted hub index that lists it in the version range.
An install or update is checked against every installed plugin whose uses: names the plugin: the new version must be in the range each declares, and still have every function, agent and skill each one is granted. Otherwise it is refused with the list (oz0 plugin dependents <name> shows all of them); --force --reason <why> installs it anyway, and the audit log keeps the reason with the list (plugin.update.forced).
The version's gate and rollout check again, and stop for a plugin installed in the meantime that the force did not name.
Before it installs, when its input, output and errors are all a terminal and without --json, it shows what the plugin needs (secrets, settings, connections, model aliases and grants), what it may do (every function grouped by type, Read, Write, Sends out, Destructive or Unknown, with its default, Allow, Ask or Refuse, and why) and what it reaches (hosts, events that start jobs, secrets by name), and asks once; yes there grants what the plugin asks of other plugins too.
Anywhere else it behaves as --yes: it takes the defaults, grants only what --accept-uses, --accept-provides, --accept-reads and --accept-model say, and prints the same three blocks after the install. $OZ0_YES=1 does the same as --yes, for scripts run by hand from a terminal.
--policy <function>=<allow|ask|refuse> changes one function's default (repeatable; a group such as write or sends-out works too), and --config <file> takes an oz0.plugin-config/v1 file (oz0 plugin config export writes one): its settings and tools are set after the install, the rest is filed as the plugin's configuration change. A switch changes the tool policy, so it takes --reason (or $OZ0_REASON); a loosening waits for another admin where four eyes are on.
A set (a plugin of kind set) installs its members, each pinned to an exact version and source, with what they use of other plugins, as one decision: the SET block lists each member and what the install does with it (install, update to the pin, keep at the pin, or keep a newer version or one from another source, which differs from what the set's evals ran on), and each member's own needs, may do and reaches follow.
On a terminal, yes also takes the settings and model mappings the set suggests; --suggested takes them anywhere else. The set's digest is one --accept-uses.
Usage
oz0 plugin install <git-url | folder | file.md | bundle | oci://registry/repository@sha256:digest | hub:name[@version]> [flags]
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--accept-inventory | string | accept the inventory of a Claude Code plugin, an Agent Plugin or an MCP Registry entry by its digest, as a refused install printed it | |
--accept-model | bool | grant a plugin whose tools declare uses_model to call a model through the gateway in its calls, metered and budgeted to the calling job and under the tenant's data rules (the same as --accept-reads model) | |
--accept-provides | strings | grant what the plugin's manifest says it provides beyond its own calls, such as outside-spend (spend that belongs to no job); comma-separated or repeatable | |
--accept-reads | strings | grant what the plugin's manifest says its functions read beyond their own calls, such as inventory (the tenant's agents as the inventory records them); comma-separated or repeatable | |
--accept-uses | string | grant the plugin's uses of other plugins, and install the plugins it uses that the tenant lacks, by the digest a refused install printed | |
--all-at-once | bool | give a new version to every node at once, instead of rolling it out to canaries first | |
--allow-breaking | bool | install a version whose agents' contracts break the installed version's, without a new major version | |
--approve-egress | bool | when the plugin's egress widens what the tenant permits, approve the change request it makes at once, after printing its delta (you must be allowed to approve it yourself) | |
--batch | int32 | half of the rest | nodes in each later step of a rollout |
--canary | int32 | 1 | nodes in a rollout's first step |
--config | string | an oz0.plugin-config/v1 file to apply after the install: its settings and tools at once, the rest as the plugin's configuration change | |
--dependency | stringArray | <plugin>=<source>: where to install a plugin it uses that the tenant lacks (a Git URL, hub:<name>, oci://..., mcp:<name>); repeatable | |
--force | bool | install or update it although it breaks installed plugins that use it (takes --reason) | |
--forge | string | github.com, gitlab.com and codeberg.org are known; other hosts record the URL's owner only | for a Git URL, the forge to ask for the repository's ID and owner: github, gitlab, gitea (also Forgejo and Codeberg) or none |
--guarded-servers | bool | with --harness-extras: the plugin's MCP servers that hold secrets also serve its agents' sessions in jobs an outside event started, each from a sandboxed server of the job's own outside the session | |
--harness-extras | bool | keep an imported plugin's hooks on harness sessions' tool calls, and its MCP servers in its agents' Claude sessions | |
--index | string | the first trusted index that lists it | for a hub: source, the plugin index to resolve it in |
--json | bool | print JSON instead of a table | |
--map | stringArray | map a model alias the plugin's agents ask for and the tenant lacks, <alias>=<target>: the target another of the tenant's aliases or a <provider>/<model> that resolves for it, which becomes a tenant alias; repeatable | |
--no-gate | bool | install a version with evals at once, without running them on a test node first | |
--path | string | the plugin's folder in the repository, for repositories that hold several | |
--plugin | string | the source is a Claude Code marketplace: install its plugin of this name | |
--policy | stringArray | <function or group>=<allow|ask|refuse>: change one function's default, or a group's (read, write, sends-out, destructive, unknown); repeatable; takes --reason | |
--quality-cascade | points | how many points more of the candidate's jobs may go to a later model of their cascade before the step fails and the candidate rolls back (0 to 1, 0.1 is 10 points, or off; default the plugin's configuration, else 0.1; only stricter) | |
--quality-denials | points | how many points more of the candidate's approvals people may deny before the step fails and the candidate rolls back (0 to 1, 0.1 is 10 points, or off; default the plugin's configuration, else 0.1; only stricter) | |
--quality-min-jobs | int32 | the plugin's configuration, else 10; only lower | the fewest jobs each version needs in a quality signal for it to count, 1 to 1000 |
--quality-outcome | points | how many points more of the candidate's jobs than the installed version's may fail their outcome check's first round before the step fails and the candidate rolls back (0 to 1, 0.1 is 10 points, or off; default the plugin's configuration, else 0.1; only stricter) | |
--quality-reported | points | how many points more of the candidate's reported results may be failures before the step fails and the candidate rolls back (0 to 1, 0.1 is 10 points, or off; default the plugin's configuration, else 0.1; only stricter) | |
--quality-sampled | points | how many points more of the candidate's sampled jobs a sampled judge may fail before the step fails and the candidate rolls back (0 to 1, 0.1 is 10 points, or off; default the plugin's configuration, else 0.1; only stricter) | |
--reads-target | strings | with --accept-reads results: a plugin whose results (findings, eval cases, refused approvals, errors, cost, scorecards) the plugin's agents may read, answered with your permissions at every read; comma-separated or repeatable; none, and it reads nothing | |
--reason | string | why a forced install or update goes past the plugins that use it (at most 500 characters; default $OZ0_REASON) | |
--ref | string | latest release tag, else the default branch | branch, tag or full commit SHA |
--secret | string | tenant secret with a token for a private repository over HTTPS (the token, or user:token), or with an OCI registry's user:password; it goes only to the hosts it is bound to (oz0 secret set NAME --host HOST) | |
--select | stringArray | only nodes with this label, key=value; repeatable | |
--shadow-runs | int32 | 5 | recent real inputs the quality gate replays on the new version, side effects stubbed, when too few real jobs end there; 0 for none, at most 20 |
--soak | duration | 1m | how long each step of a rollout is watched before its gates |
--start-timeout | duration | 5m | how long a step's nodes may take to run the new version |
--suggested | bool | for a set: take the settings and model mappings it suggests for its members without being asked | |
--tenant | string | default | tenant to install into |
--yes (-y) | bool | take the defaults without asking (what happens anywhere but on a terminal; $OZ0_YES=1 does the same) |
Inherited flags
| Flag | Type | Default | Description |
|---|---|---|---|
--context | string | $OZ0_CONTEXT or <config dir>/orchestrator-zero/context.json | CLI context file written by server init |
--log-level | string | info | log level: debug, info, warn or error |
See all oz0 commands and the global flags.