Concepts

The fleet

Node : A machine running orchestrator-zero-node: a laptop, a GPU box, a VM, a Raspberry Pi. It dials out to the edge, reports what it can do and runs the agents and tools of the plugins installed on it. A node is not an agent; it becomes one when it picks up a job.

Server : A process running orchestrator-zero server start. It runs three roles: management, edge and an embedded Temporal. A cluster is one or more servers sharing a PostgreSQL database.

Edge : The role nodes and apps talk to, and the only door into the cluster. It proxies Temporal, serves the runtime API and the LLM gateway, hands out plugin artifacts and keeps a control stream open to every node.

Management : The role that holds the registry of nodes, the certificate authority, tenants, operators, secrets, plugins and usage. Operators reach it with the CLI.

Labels : Key-value pairs on a node, such as gpu=a100 or zone=eu-north. They decide which plugins a node gets and which agents may run on it.

Tenant : An isolated team or customer, with its own nodes, plugins, secrets and Temporal namespace. Every cluster starts with the tenant default.

Operator : A person or a script with an operator certificate, allowed to manage the cluster through the CLI and the admin API.

The work

Plugin : A Git repository with an oz0-plugin.yaml at its root. It can hold tools, agents and skills, and later hooks, flows and evals. You install it on a tenant's nodes; it is locked to a commit.

Tool : An MCP server: your own code, an existing package from PyPI or npm, or a remote server. Each of its functions is callable as <tool>.<function>, for example github.get_pr.

Agent : A definition in a plugin: instructions, a model, the tools it may use, limits and who it may delegate to. Each agent is reachable on the task queue agent.<name>.

Skill : A folder with a SKILL.md, in the Agent Skills format, that teaches an agent how and when to use something.

Job : One run of an agent with some input. A job is a Temporal workflow, so it survives crashes and restarts, and its ID is the workflow ID.

Home node : The node that picked a job up. The job's tools run there, so a job can use files and devices on that machine.

Delegation : An agent handing a task to another agent with oz.delegate. The child is a job of its own, on any node that has that agent, and its cost counts toward the parent.

The plumbing

Task queue : A Temporal queue that nodes poll. agent.<name> for an agent's jobs, node.<id> for work that must run on one node, and oz0.default for everything else.

LLM gateway : The part of the edge that every model call goes through. It adds the tenant's API key, passes the call to the provider unchanged and records tokens and cost.

Join token : A one-time or reusable secret that lets a node join a tenant without an operator approving it. It also carries the hash of the cluster's CA, so the node can check the server before it sends anything.

Master key : The file that seals the cluster's certificate authorities and secrets. Every server needs a copy; lose it and the cluster is lost.