Architecture
Orchestrator Zero has three planes. Nodes do the work, the edge is the only door in, and management keeps track of everything. Temporal sits behind the edge and keeps every run durable.
The planes
| Plane | Contents | Talks to |
|---|---|---|
| Management | Admin API, tenants and operators, the node registry, the certificate authority, plugins and artifacts, secrets (sealed), usage, the audit log | PostgreSQL, the edge |
| Edge | The Temporal proxy, the runtime API, the LLM gateway, artifact downloads, the control stream to every node | Nodes, apps, Temporal, model providers, management |
| Temporal | Durable state for every job | The edge |
| Nodes | The supervisor, the agent runtime, plugin processes | Only the edge |
By default one orchestrator-zero process runs management, the edge and an embedded Temporal. A cluster is several such servers sharing one PostgreSQL server. Running the roles on separate machines comes later.
Design rules
- Nodes only dial out. A node opens two connections to the edge, on port 7233 (Temporal, mTLS) and 7443 (join, renewals, the control stream, artifacts and the LLM gateway). It listens on nothing, so it works behind NAT and firewalls.
- Every node call is authorized. The edge checks each call against the node registry, which every server reloads every two seconds. A blocked node is refused within two seconds on every port.
- Keys stay central. Provider API keys and other secrets are sealed in management and unsealed only in the edge. Nodes get a local proxy instead of keys.
- Management never needs Temporal. Running jobs, schedules and the LLM gateway keep going when management is down.
- The core is neutral. No models, tools or services are built in; they come from plugins.
A job, end to end
A client starts a job
orchestrator-zero run reviewer "..." or an app calls StartJob on the edge's runtime API. The edge starts an AgentWorkflow on the task queue agent.reviewer in the tenant's Temporal namespace.
A node picks it up and becomes the agent
Every node that has the agent's plugin, and the labels it requires, polls agent.reviewer. The first one free takes the job and becomes its home node.
Model calls go through the gateway
The agent's model calls leave the node through its local LLM proxy, reach the edge's gateway, get the tenant's key added and go to the provider. The gateway records tokens and cost under the job.
Tools run on the home node
Tool calls are Temporal activities on node.<home>, so they run where the job runs. The agent's own steps can run on any node that has the agent.
Children run anywhere
When the agent delegates with oz.delegate, the child is a job of its own on any node that has the child agent. Its cost counts toward the parent's tree.
The answer comes back
The workflow completes, the CLI or app gets the answer, and job get shows the cost of every branch.
When something is down
| Down | What happens |
|---|---|
| Management | Running and scheduled jobs continue, and apps can still start jobs through the edge. Joins, installs and secret changes wait. |
| An edge | Its nodes move to another server's edge within seconds. Run at least two servers. |
| All edges | Nodes cannot reach Temporal or models. Work pauses without losing state and resumes when an edge is back. |
| Temporal | Everything pauses and resumes where it was. |
| PostgreSQL | Management stops. The edge keeps authorizing nodes from its cached registry. In embedded mode Temporal stops too. |
| A node | Nothing is lost. Jobs it was running continue from the last finished step on another node with the same agent, but a tool call that must run on its home node waits for that node to come back. Moving a job's home to another node is planned. |