Get started

Quickstart

Build oz0, watch an agent answer with no API key at all, give it a model, and make an agent of your own.

For: Developers running their first local job.

Run a local job with recorded answers and no API key. After it succeeds, connect a model, create an agent and inspect its jobs. Each stage builds on the running environment from the previous one.

The picture first

An agent defines the instructions, model and tools for the work. A node is the machine that executes it. Each execution is a job you can inspect.

The oz0 server coordinates the work; oz0-node runs it. This tutorial starts both locally. Management, edge and embedded Temporal are parts of the server process, so you do not install them separately.

You only need those terms to start. Concepts explains the rest when you need them.

Before you start

  • Linux or macOS.
  • Go 1.27 and uv 0.12. uv installs Python for you.
  • Git, and access to the Orchestrator Zero repository.
  • No API key to start with. For the agents to think on their own later: an Anthropic API key, or a model server on your machine such as Ollama.
This tutorial requires access to the private source repository. Public source downloads, install scripts and release images are coming soon. The docs are available to read before the product release; see public availability.

Build the binaries

Terminal 1
git clone https://github.com/orchestrator-zero/orchestrator-zero.git
Terminal 1
cd orchestrator-zero
make build runtime-bundle

export PATH="$PWD/bin:$PATH"
export OZ0_RUNTIME_BUNDLE="$(ls -td "$PWD"/dist/runtime/* | head -1)"   # the newest

make build puts oz0 (the server and CLI) and oz0-node (the node) in bin/. They are the short names of orchestrator-zero and orchestrator-zero-node, which work everywhere too. make runtime-bundle builds the Python runtime that nodes run. Run make doctor if something is missing. oz0 --help lists the commands by task: the ones that get you started first, then the rest under the same seven words the web UI's sidebar and these docs use (Run, Build, Improve, Govern, Fleet, Spend and Admin).

A first run, without a key

In a folder without a plugin, oz0 dev starts with the hello agent:

Terminal 1
cd ..
Terminal 1
oz0 dev

It starts a server, joins a node, installs the hello agent and runs it once on answers recorded with oz0, so no model is called and nothing is spent. The first start takes a minute or two, while the node installs uv, Python and the runtime; later starts reuse them. It prints something like:

Dev server ready. In another terminal:
  export OZ0_CONTEXT=/tmp/oz0-dev-1234567/server/operator/context.json
Web UI: https://127.0.0.1:40121 (user admin, password in /tmp/oz0-dev-1234567/server/admin-password)
Temporal UI: http://127.0.0.1:41523
Node started (log: /tmp/oz0-dev-1234567/node.log)
hello dev-98a3de5f1d5d ready in 10.3s: hello.hello
First run: oz0 run hello "Say hello to Ada"
hello → hello.hello {"name":"Ada"}
hello ← hello.hello Hello, Ada!
hello: Done: Hello, Ada!
hello answered from answers recorded with oz0 (no model was called, nothing was spent):
  Done: Hello, Ada!

In another terminal, point the CLI at this dev server:
  export OZ0_CONTEXT=/tmp/oz0-dev-1234567/server/operator/context.json
Then give hello a model. No model key is set: store one as the tenant's secret, sealed and used only by the edge,
  printf %s "$ANTHROPIC_API_KEY" | oz0 secret set ANTHROPIC_API_KEY
  oz0 run hello "Say hello to Ada"
Or run a model on this machine, with an agent of your own: oz0 agent new my-agent,
  give it model: {primary: local/<model>}, list the model's server (Ollama, vLLM, llama.cpp) in
  ~/.cache/orchestrator-zero/dev/node/models.yaml, and run oz0 dev my-agent.md (see Local models in the docs).
Make an agent of your own, in one file: oz0 agent new my-agent, then oz0 dev my-agent.md.
The dev server keeps running; Ctrl+C stops.

The agent called its hello tool on the node, and its model calls went through the server's gateway, which answered them from the recording. Your first job is complete. Leave the dev server running for the next step.

Give hello a model

Open a second terminal in the folder you cloned into. Put the binaries on its PATH, point the CLI at the dev server and store your key as a tenant secret:

Terminal 2
cd orchestrator-zero && export PATH="$PWD/bin:$PATH"
export OZ0_CONTEXT=/tmp/oz0-dev-.../server/operator/context.json   # the line dev printed
printf %s "$ANTHROPIC_API_KEY" | oz0 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. With ANTHROPIC_API_KEY set in the environment before oz0 dev, dev stores it for you.

Terminal 2
oz0 run hello "Say hello to Ada"

This time the model answers. No key? A model on your own machine works too, for an agent of your own (hello's folder is made afresh at every first run): see Make an agent of your own and Local models. And oz0 doctor checks the setup from where you are, the model key included (Doctor).

Make an agent of your own

Stop the first dev server with Ctrl+C in terminal 1. Then write an agent in one file:

Terminal 1
mkdir my-agent && cd my-agent
oz0 agent new my-agent --description "Greets people"

my-agent.md holds the agent's fields in its front matter and its instructions below them:

my-agent.md
---
# A one-file agent: these fields, then its instructions below. `oz0 plugin eject` turns it into a full plugin
# when it needs code of its own, evals or more parts.
apiVersion: oz0/v1
description: Greets people
# A model alias, which each tenant maps to a model of its own providers: default, fast or smart.
model:
  use: default
# What it takes and gives: text. A JSON Schema contract is a file beside the agent: eject the plugin first.
input: text
output: text
# Other plugins' functions, by address, such as tools: [github/oz0_github.get_issue].
limits:
  max_steps: 20
  timeout: 10m
---
You are my-agent. Greets people.

Answer in a short paragraph, and say so when you do not know.

The file is a plugin of its own: there is no manifest to write, since Orchestrator Zero makes one, a capability named after the file. The agent asks for the tenant's default model alias (use: default), which a tenant gets once it has a model provider, here Anthropic's claude-sonnet-5-5 from your key (the standard aliases), and it declares what v1.0 asks of an agent: its input and its output.

Write what it should do below the front matter, then start a dev server with it:

Terminal 1
oz0 dev my-agent.md

dev installs the file, alone, and reinstalls it every time you save it:

Dev server ready. In another terminal:
  export OZ0_CONTEXT=/tmp/oz0-dev-7654321/server/operator/context.json
Web UI: https://127.0.0.1:40122 (user admin, password in /tmp/oz0-dev-7654321/server/admin-password)
Temporal UI: http://127.0.0.1:41524
Node started (log: /tmp/oz0-dev-7654321/node.log)
my-agent dev-3f2a91c... ready in 4.0s:
Watching for changes; Ctrl+C stops.

Run your agent

This is a new dev server: point terminal 2 at it, and store the key again (dev starts empty every time, unless the key is in its environment):

Terminal 2
export OZ0_CONTEXT=/tmp/oz0-dev-.../server/operator/context.json   # the line the new dev printed
printf %s "$ANTHROPIC_API_KEY" | oz0 secret set ANTHROPIC_API_KEY
Terminal 2
oz0 run my-agent "Say hello to Ada"

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

job job-bb270cf1-b194-4bf1-a0e3-267e061e416a started (agent my-agent)
my-agent: Hello, Ada! Nice to meet you.
Hello, Ada! Nice to meet you.

JOB                                       AGENT     NODES              MODELS                       CALLS  INPUT  CACHED  OUTPUT  COST
job-bb270cf1-b194-4bf1-a0e3-267e061e416a  my-agent  node-91378eb09343  anthropic/claude-sonnet-5-5  1      310    0       12      $0.0011
job job-bb270cf1-b194-4bf1-a0e3-267e061e416a completed: 1 calls, 310 input and 12 output tokens, $0.0011

The model calls went through the gateway, which metered them. To try a file once without keeping a dev server, oz0 run ./my-agent.md "Say hello to Ada" starts one, runs the agent and stops it again.

Change it and run again

Edit the instructions in my-agent.md, for example to answer in one line, and save. Or from the second terminal:

Terminal 2
cd ../my-agent
perl -pi -e 's/^Answer in a short paragraph/Answer in one line/' my-agent.md

The dev terminal shows the agent being reinstalled within seconds (my-agent dev-... reloaded in ...). Run it again and you get the new behaviour:

Terminal 2
oz0 run my-agent "Say hello to Ada"

On a cluster, with a connector

On a cluster that has a connector installed, such as GitHub, a first agent that uses it is one file and three commands, with an edit between the first two:

Terminal
oz0 agent new triage --uses github        # its functions by address: the Read ones on, the others commented out
# edit triage.md: what it does, and the functions it needs
oz0 plugin install ./triage.md            # shows what it needs, may do and reaches, and asks once
oz0 run triage "Triage issue 12 of acme/api"

The install asks its one question on a terminal, and yes there also grants the agent what it uses of the connector; a script without a terminal takes the defaults, which grant nothing, so its install is refused with the --accept-uses line to add. When the agent needs code of its own, evals or more parts, oz0 plugin eject ./triage.md writes the full plugin folder, keeping its name and version: see Agents and Your first plugin, which builds a tool of its own.

Look around

Terminal 2
oz0 job list          # recent jobs
oz0 job get <job-id>  # status, answer and cost per branch
oz0 usage             # tokens and cost by job, agent and model
oz0 catalog           # agents, tools and skills, and the nodes ready to run them
oz0 node list         # the dev node

dev also prints the address of the Temporal UI, where you can open the job's workflow and see every model and tool call in its history. Something not working? oz0 doctor checks ports, certificates, the clock, the database, Temporal and the model key, and says how to fix what fails (Doctor, Troubleshooting).

Open the web UI

dev prints the web UI's address too, with the file that holds the admin password. Open the address, accept the browser's warning about the certificate (it comes from the dev cluster's own CA) and sign in. Overview has a checklist of the next steps of a new setup that your role can take (as the dev cluster's admin: join a node, add a model key, install a verified plugin, run a job, set a budget), each with its command and ticked once done; Hide puts it away and Show setup steps at the top of the Overview brings it back.

Beside it is Try a first job: cards for the verified starters net-diag, host-health and the PR reviewer, each with what it does and what it needs (a node, a model key, a GitHub connection). When the starter is installed and its needs are met, Start runs it and opens the job; when it is not installed, an admin's Install and start opens the Plugins page's install with its verified listing filled in, and starts it once you confirm the install.

When the install comes with warnings (host-health always warns that its tool runs on the host, outside the sandbox), the dialog stays open with them, and the job starts only when you click Start there. Nothing starts without your click, and the cards go away with the checklist. Jobs has the runs you just made, with each step, its cost and the live view; Agents runs my-agent from a form; Nodes shows the dev node.

See Web UI for every page.

make build alone builds the server without the web UI: it says so when it finishes, dev says so under the address, and the page says so. Build the UI into the server once, with Node.js 24:

Terminal 1
make web build    # in the orchestrator-zero folder; then start dev again

Connect Slack, Discord or GitHub

Agents can answer in Slack or Discord and work on GitHub as an app. Each of them sends its events to one URL per app, and yours go to your own edge, so you create your own app, about two minutes each: install the plugin, then Connect it in the web UI under Credentials, Connections, or with oz0 connection start.

GitHub's app comes from a manifest you only confirm; Slack's create link opens Slack with your app's manifest filled in, and you paste back three fields; Discord's steps guide you through its developer portal. Each step is checked before the next, and what you paste reaches only the edge.

Terminal 2
oz0 plugin install hub:ai.oz0/slack
oz0 connection start slack --open --wait 15m

The edge must be reachable from Slack, Discord or GitHub and your browser at a public address with a trusted certificate (server start --public-edge-url), so this is for a cluster rather than a laptop's dev server. When a step does not pass, its page says why; see troubleshooting for each provider.

Use it from your coding assistant

One command sets up Claude Code, Codex or Gemini CLI in a project: the operators' MCP server (oz0 mcp, with your CLI context and no token in any file) and the skills or instructions it reads. A second run changes nothing, and --remove takes it out again; see Run Orchestrator Zero from an MCP client.

Terminal 2
oz0 setup claude-code --dry-run   # what it would write
oz0 setup claude-code

Next steps

Concepts

The ten words you need: node, edge, tenant, plugin, agent, job and the rest.

Your first plugin

Write a real tool, give it to an agent and publish it with a Git tag.

Run a cluster

Move from dev mode to servers on PostgreSQL and join real machines.

Join nodes

Add another machine to the dev server or a cluster, with a token or by approval.

Delegation

Let one agent hand work to another agent on another machine.
Copyright © 2026