--- title: "Install a plugin" description: "Install a checked plugin version and verify its state." canonical_url: "https://docs.oz0.ai/build/plugins/install" --- # Install a plugin > Install a checked plugin version and verify its state. 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 ```bash [Terminal] 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`: ```bash [Terminal] 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](https://docs.oz0.ai/build/plugins/sources). A plugin made in the studio installs from the tenant's [workspace](https://docs.oz0.ai/build/plugins/workspace) the same way: `oz0 plugin install workspace:@`. A Claude Code plugin, an Agent Plugin, a Claude Code marketplace's entry (`--plugin `) and a server of the MCP Registry (`mcp:`) install the same way too, once you accept the inventory of every command they run: see [Bring your Claude Code plugins and Agent Plugins](https://docs.oz0.ai/build/plugins/claude-code-and-agent-plugins). A plugin listed in a trusted [plugin index](https://docs.oz0.ai/build/plugins/indexes) installs by name, pinned to the commit and content the listing names: `oz0 plugin install hub:com.example/team@0.1.0`. 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](https://docs.oz0.ai/govern/reviewed-changes). ## A quality gate for plugins with evals A version of a plugin that has [evals](https://docs.oz0.ai/improve/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: ```text 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](https://docs.oz0.ai/improve/evals/quality-gates#quality-gates) for how the verdict works. ## See how it is going ```bash [Terminal] 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](https://docs.oz0.ai/govern/reviewed-changes/changesets#where-a-change-came-from), 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: ```bash [Terminal] 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 plugin-improver@0.1.0 # 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](https://docs.oz0.ai/build/plugins/install/review): Review requirements, permissions and policy changes before installing. - [Install from a source](https://docs.oz0.ai/build/plugins/install/sources): Choose a folder, standalone agent or private repository and meet the source-fetch rules. - [Update a plugin](https://docs.oz0.ai/build/plugins/install/update): Update the installed version and review changes of ownership or dependencies. - [Roll out a plugin](https://docs.oz0.ai/build/plugins/install/rollouts): Release a new version through canaries and handle failed or interrupted rollouts. - [Grant access between plugins](https://docs.oz0.ai/build/plugins/install/grants): Review, grant and revoke access to parts owned by another plugin. - [Retire or remove a plugin](https://docs.oz0.ai/build/plugins/install/retire-and-remove): Wind down plugin use, inspect dependents and remove old versions. - Section : [a plugin in a folder](https://docs.oz0.ai/build/plugins/install/sources#a-plugin-in-a-folder) - Section : [a plugin that moved](https://docs.oz0.ai/build/plugins/install/update#a-plugin-that-moved) - Section : [a private repository](https://docs.oz0.ai/build/plugins/install/sources#a-private-repository) - Section : [a set](https://docs.oz0.ai/build/plugins/install/grants#a-set) - Section : [an agent in one file](https://docs.oz0.ai/build/plugins/install/sources#an-agent-in-one-file) - Section : [new versions roll out to canaries first](https://docs.oz0.ai/build/plugins/install/rollouts#new-versions-roll-out-to-canaries-first) - Section : [old versions](https://docs.oz0.ai/build/plugins/install/retire-and-remove#old-versions) - Section : [plugins that use other plugins](https://docs.oz0.ai/build/plugins/install/grants#plugins-that-use-other-plugins) - Section : [quality signals](https://docs.oz0.ai/build/plugins/install/rollouts#quality-signals) - Section : [remove](https://docs.oz0.ai/build/plugins/install/retire-and-remove#remove) - Section : [retire](https://docs.oz0.ai/build/plugins/install/retire-and-remove#retire) - Section : [shadow runs for a quiet tenant](https://docs.oz0.ai/build/plugins/install/rollouts#shadow-runs-for-a-quiet-tenant) - Section : [update](https://docs.oz0.ai/build/plugins/install/update#update) - Section : [updates and the plugins that use them](https://docs.oz0.ai/build/plugins/install/update#updates-and-the-plugins-that-use-them) - Section : [updates from new hands](https://docs.oz0.ai/build/plugins/install/update#updates-from-new-hands) - Section : [what its agents combine](https://docs.oz0.ai/build/plugins/install/review#what-its-agents-combine) - Section : [what the install shows first](https://docs.oz0.ai/build/plugins/install/review#what-the-install-shows-first) - Section : [where the edge fetches from](https://docs.oz0.ai/build/plugins/install/sources#where-the-edge-fetches-from) ## Sitemap See the full [sitemap](https://docs.oz0.ai/sitemap.md) for all pages.