Import from registries

For: plugin authors.

Add an overlay or install from a marketplace or the MCP Registry.

An overlay for what the format cannot say

An oz0-plugin.yaml with an import: key next to the plugin's files adds what its format has no place for: contracts, limits, labels and delegation of its agents, the approvals of its tools, its name and version when it has no manifest, and parts to leave out. Its requires: takes oz0, platforms and secrets only; any other key of a manifest's requires: (optional_secrets, settings, inject, secrets_from, models) is an error in an overlay, since the plugin's own code would not follow it.

apiVersion: oz0/v1
import: {}                      # or {format: agent-plugin} when detection would guess wrong
name: sql-helpers               # needed when the plugin has no .claude-plugin/plugin.json
version: 0.4.1
requires:
  secrets: [WAREHOUSE_DSN]
skip: [mcp:jira, hook:Notification]
tools:
  github:
    requires_approval: [github.merge_pull_request]
agents:
  query-writer:
    input_schema: schemas/question.json
    model: {use: smart, needs: [tools]}
    limits: {max_steps: 6, timeout: 10m, max_cost_usd: 0.5}
    requires:
      labels: {net: internal}
    delegation: {max_depth: 1}
hooks:
  timeout: 5s
  on_timeout: escalate

Each MCP server becomes a tool whose ID is the server's name (github above), and a tool ID belongs to one plugin per tenant. When another plugin of the tenant has a tool of that ID, such as an OZ0 plugin's github, the install is refused and names that plugin; skip: [mcp:github] leaves the server out, or remove the other plugin first. Servers whose names make the same ID get -2, -3 and so on, and a plugin has at most 256 MCP servers.

From a marketplace

A Claude Code marketplace (a repository with .claude-plugin/marketplace.json) is a list of plugins. Install one of them by its name:

oz0 plugin install https://github.com/acme/marketplace --plugin review-kit

A plugin without .claude-plugin/plugin.json is named after its marketplace entry, as Claude Code names it, with a warning; plugin update keeps the name. An entry whose source is a folder of the marketplace installs from that folder at the commit the list was read at; github, url and git-subdir entries install from their repository at the entry's sha, else its ref. command entries are refused: they would run a program on the edge.

npm and archive entries install as bundles the edge fetches once and locks by their digest:

npm

The edge reads the package's metadata from the entry's registry (https; the public registry when it has none), takes the version the entry names (an exact version, the newest one a range such as ^2.0.0 takes, or a dist-tag), counting only releases at least seven days old, as npm's before does (a latest tag younger than that gives way to the newest older release; any other version or tag that young is refused until its week has passed; an offline folder's packages count as they are), downloads that version's tarball and checks it against the registry's sha512 integrity.

Install scripts never run. The plugin's source is npm:<package>@<version> and its ref the version.

• archive: the edge downloads the zip over https and checks it against the entry's sha256; an entry without one is locked to the bytes it downloaded now, with a warning. The plugin's root may be at the top of the zip or one folder down. The entry's headers are not sent, and a headersHelper is refused: it would run a command on the edge.

Neither moves by itself: plugin update says so, and a new version is a new install from the marketplace.

From the MCP Registry

The MCP Registry lists MCP servers with the npm, PyPI or OCI package each runs from. Install one as a plugin whose one tool is that server:

oz0 plugin mcp weather                         # browse, through the edge
oz0 plugin install mcp:io.github.example/weather
oz0 plugin install mcp:io.github.example/[email protected] --accept-inventory sha256:…

The edge reads the registry; your browser and your laptop never do. The plugin is pinned to the package version the registry lists, its fixed arguments and environment come with it, and the variables the registry marks secret become declared secrets. Its name is the server's name with dashes (io-github-example-weather). plugin update keeps the version; install another version to move.

The edge runs an npm package, else a PyPI package, else an OCI image pinned by its digest, else a remote server over Streamable HTTP. An image runs on nodes with Docker or Podman, and the edge mirrors it at install (container images); an image named only by a tag does not carry over. It refuses remote servers that need a sign-in or a value from a person, and entries the registry marks deleted; a deprecated entry installs with a warning.

A remote server's secret or required header (a token) comes from a tenant secret named like the header, such as AUTHORIZATION or X_API_KEY, which the plugin declares; set it before nodes start the tool.

A Claude Code server whose command is docker run … <image>@sha256:<digest> … (or podman run) carries over as a tool from that image, with its -e variables; a server whose command line mounts folders, publishes ports, adds capabilities or names an image by tag only does not.

Mounts are refused in every form docker run takes them (-v, --volume, --mount, joined short flags such as -iv, --volumes-from, --tmpfs, --device, --env-file), and so is any other way to the node's container runtime: a wrapper such as sudo docker …, sh -c "docker run …" or env docker …, another container CLI (nerdctl, kubectl, …), a command line that names docker.sock, or an environment with DOCKER_HOST or CONTAINER_HOST.

Such a server is left out with a note in oz0 plugin lint; this keeps out the config-driven mounts that reached docker.sock in other MCP gateways (Docker MCP Gateway GHSA-mqq5-qh4g-2g8g, gh-aw GHSA-846c-fpfg-rj9m). The check reads a shell's script as the shell would, quotes and backslashes dropped and commands after ;, &&, | or inside $(...) included. It is a lint of the forms people write, not a boundary: a stdio server runs code of its own, so a script that builds the command's name or a file it runs (bash ./start.sh) goes past it.

The boundary is the sandbox, whose tier 1 binds no container runtime's socket into a tool server.

In the console, Plugins, MCP Registry lists the registry's servers with whether each can run here. Review builds the plugin on the edge and shows its inventory; Accept the inventory and install installs it.

The registry is the official one, https://registry.modelcontextprotocol.io. To read a company's mirror or another registry, set OZ0_MCP_REGISTRY_URL in the environment of the servers that run the edge role.

Versions of the formats

The loader follows formats Orchestrator Zero does not control, so it says which version it read each plugin as (import.format_version in the bundle, and the inventory's first line). This release reads the Claude Code plugins reference as of Claude Code 2.1.288, Agent Plugins 1.0.0, and the MCP Registry's server.json schema 2025-12-11 and API v0.1..