Quickstart

Build the binaries

git clone https://github.com/moon-ventures-se/orchestrator-zero.git
cd orchestrator-zero
make build runtime-bundle

export PATH="$PWD/bin:$PATH"
export OZ0_RUNTIME_BUNDLE="$(ls -d "$PWD"/dist/runtime/* | tail -1)"

make build puts orchestrator-zero (the server and CLI) and orchestrator-zero-node (the node) in bin/. make runtime-bundle builds the Python runtime that nodes run. Run make doctor if something is missing.

Scaffold an agent plugin

cd ..
orchestrator-zero plugin new hello-agent --template python-agent --description "Greets people"
cd hello-agent
uv lock
orchestrator-zero plugin lint

You now have a plugin with one MCP tool (hello_agent, with a hello function), one skill and one agent, also called hello-agent. The agent uses anthropic/claude-sonnet-5-5 and may call the tool.

Start a dev server with your plugin

orchestrator-zero dev

This starts a server, joins a node, installs your plugin from its working tree and waits until the node has started its tools. It prints something like:

Dev server ready. In another terminal:
  export OZ0_CONTEXT=/tmp/.../operator/context.json
Node started (log: /tmp/.../node.log)
hello-agent dev-3f2a91c... ready in 14.0s: hello_agent.hello
Watching for changes; Ctrl+C stops.

Leave it running. It reinstalls the plugin every time you save a file.

Give the gateway your API key

In a second terminal, point the CLI at the dev server and store your key as a tenant secret:

export OZ0_CONTEXT=/tmp/oz0-dev-.../operator/context.json   # the line dev printed
printf %s "$ANTHROPIC_API_KEY" | orchestrator-zero secret set ANTHROPIC_API_KEY

The key is sealed with the cluster's master key and only ever unsealed in the edge. Nodes never see it.

Run the agent

orchestrator-zero run hello-agent "Say hello to Ada"

The CLI starts a job and streams what the agent does to stderr while it works: its tool calls (→), their results (←) and its text. Then it prints the answer, and what the job cost, one row per job in the tree (numbers here are illustrative):

JOB                  AGENT        NODES              MODELS                       CALLS  INPUT  CACHED  OUTPUT  COST
job-bb270cf1-...     hello-agent  node-91378eb09343  anthropic/claude-sonnet-5-5  2      465    0       45      $0.0014

The agent called your hello tool on the node, and the model calls went through the gateway, which metered them.

Change the tool and run again

Edit src/hello_agent/server.py, for example to change the greeting, and save. The dev terminal shows the plugin being reinstalled within seconds. Run the agent again and you get the new behaviour.