Reference
oz0-plugin.yaml
Every field of the plugin manifest, and the rules plugin lint checks.
The manifest is oz0-plugin.yaml at the root of the plugin's repository. It is read strictly: unknown fields are errors, so a typo does not pass silently. orchestrator-zero plugin lint runs the same checks as the edge.
oz0-plugin.yaml
apiVersion: oz0/v1
name: github-tools
version: 1.4.0
description: Tools and agents for working in GitHub
runtime: python
requires:
oz0: ">=0.4"
platforms: [linux/amd64, darwin/arm64]
secrets: [GITHUB_TOKEN]
tools:
- id: github
mcp: ["python", "-m", "github_tools.mcp"]
requires_approval: [github.merge]
- id: fetch
package: pypi:mcp-server-fetch==2026.8.18
affinity: any
agents: [agents/pr-reviewer.yaml]
skills: [skills/]
hooks:
- on: pre_tool_call
call: github.check_merge
match: { tools: ["github.merge"] }
timeout: 2s
on_timeout: escalate
flows: [flows/]
evals: [evals/]
Top level
apiVersion
string required
Must be
oz0/v1.name
string required
Lowercase letters, digits and dashes, at most 63 characters, starting and ending with a letter or digit.
version
string required
A semantic version such as
1.4.0, with an optional pre-release or build suffix.description
string
One line about what the plugin does. Missing it is a warning.
runtime
string required
The language of the plugin's own code:
python, node, go or binary. Nodes build python plugins with a pyproject.toml today.agents
string[]
Agent definition files, or folders of them, relative to the plugin's root.
skills
string[]
Skill folders (with a
SKILL.md), or folders of them.flows
string[]
Flow files, or folders of
*.yaml flows, each with name, description, input_schema, trigger.webhook.secret, steps and output. See Flows.evals
string[]
harnesses
list
Agent harnesses this plugin provides. See below.
Paths must be relative to the plugin's root, use forward slashes and stay inside the plugin (no ..). A plugin with no tools, agents, skills, hooks or flows gets a warning.
requires
oz0
string
The Orchestrator Zero versions the plugin works with: one or more constraints such as
>=0.4 or >=0.4, <0.6, using >=, <=, >, <, =, ^ or ~.platforms
string[]
os/arch pairs, with os in linux, darwin, windows and arch in amd64, arm64. Empty means every platform.secrets
string[]
Tenant secrets the plugin's processes get as environment variables of the same names, such as
GITHUB_TOKEN: its tools, hooks and harnesses, on every node that runs it, held in memory only. A node does not start the plugin while one of them is not set in the tenant. See Secrets.tools[]
Each tool is an MCP server. Set exactly one of mcp (your own code), package or url; package may also set mcp to name the command to run.
id
string required
Lowercase letters, digits, dashes and underscores, unique in the plugin. Agents call the tool's functions as
<id>.<function>.mcp
string[]
The command that starts the MCP server over stdio. Without
package, it runs in the plugin's own environment, and python means that environment's Python. With package, it runs in the package's environment.package
string
An existing MCP server:
pypi:<name>[==<version>], npm:<name>[@<version>], oci:<image> or binary:<url>. Unpinned packages are a warning; the edge pins them at install time. oci: and binary: are not run yet.url
string
A remote MCP server over Streamable HTTP.
http:// is a warning; use https://.affinity
string
node (default): runs on the job's home node. any: runs on any node that has the plugin.requires_approval
string[]
This tool's functions that pause a job for a person, as
<id>.<function>. Checked today; enforced from M5.env
map
Extra environment variables for the tool's process. Keys must be environment variable names.
harnesses[]
A harness runs one session of an agent harness per job. Agents use it with runtime: harness:<name>. See Harnesses.
name
string required
The harness's name, as agents refer to it.
command
string[] required
The command that starts one session, resolved like a tool's
mcp command. It speaks the harness protocol in JSON lines over stdin and stdout.permissions
boolean
The harness asks before each tool call, so the job's hooks and approvals decide it. See Write a harness for another tool.
hooks[]
See Hooks.
on
string required
pre_tool_call, post_tool_call, job_start or job_end. pre_llm_call is accepted and does not run yet.call
string required
The function that answers,
<tool>.<function>, of one of this plugin's tools.match.tools
string[]
For tool events: the
<tool>.<function> names the hook applies to; * matches any function. Empty means every call.match.agents
string[]
Only these agents' calls and jobs. Empty means every agent of the tenant.
timeout
duration
How long the hook may take, such as
2s. The default is 2 seconds, the most 30.on_timeout
string
What a hook that does not answer in time, fails, or gives no decision counts as:
allow, deny (the default) or escalate.