Concepts
Temporal
Why Orchestrator Zero is built on Temporal, and the backends it can use.
Agent runs are long, expensive and fail halfway. Temporal is the open-source engine made for that kind of work, so Orchestrator Zero builds on it instead of reinventing it.
| Temporal feature | What it gives your agents |
|---|---|
| Durable execution | A crash, a deploy or a lost node never throws a run away; it continues after the last finished step |
| Activities | Model calls are retried by Temporal alone, after the wait the provider asks for, with timeouts and heartbeats; tool calls run once and report their result |
| Task queues | Each job lands on a node with the right agent and labels |
| Child workflows | Agents delegate to agents on other machines |
| Timers and signals | Runs can wait for a long time without holding a machine |
| History | Every step of every job is recorded and can be inspected |
You never use Temporal directly: the edge talks to it for the nodes, and nodes cannot tell which backend is behind it.
Backends
| Backend | What it is | Status |
|---|---|---|
| Embedded | Temporal's services inside the orchestrator-zero binary, on the same PostgreSQL (SQLite in dev mode) | Works today; the default |
| Your own cluster | A Temporal cluster your organization already runs | Planned |
| Temporal Cloud | Temporal's hosted service, with a namespace per tenant | Planned (M7) |
Nodes go through the edge with every backend. Temporal Cloud does not check certificate revocation, so the edge holds the Cloud credentials and blocks nodes itself, on their next call.
Things to know about embedded Temporal
- History shards are fixed at creation.
server init --history-shardssets them once; 1024 suits a cluster that may grow large, 64 or 128 suit small ones. - Ports must be 32767 or lower, because Temporal's PostgreSQL schema stores them in a small integer column. The defaults are fine.
- A tenant has at most 150 agents and flows, all its plugins together;
plugin installrefuses one that would go past it. Each is a task queue in the tenant's Worker Deployment, and Temporal registers a new runtime version's queues one at a time: in our load test, 150 agents took 30 seconds after the install, and 300 took 9 minutes, while their jobs waited. Tenants are the way to more agents for now. - Upgrades go one Temporal minor version at a time.
server startapplies Temporal's schema migrations, and ours, under a PostgreSQL lock.