oz0 dev
For: Operators and developers looking up a command.
Start a dev server and a node, install the plugin from its working tree (no commit needed) and reinstall it whenever a file changes. The node's tools (uv, Python, Node.js) are cached between runs; the server starts empty every time. ANTHROPIC_API_KEY and OPENAI_API_KEY from the environment become the dev tenant's keys.
In a folder without a plugin, dev makes a first run: it starts with the hello agent, runs it once on answers recorded with the server, so no model key is needed and nothing is spent, prints the answer, and says how to add a key or a local model; the dev server then stays up with hello installed (--no-first-run skips it).
The plugin may be one part with no oz0-plugin.yaml: a folder of one agent, flow or skill, or one file, such as the agent agent new writes (dev ./triage.md). A file is installed alone, without what lies beside it, and reinstalled whenever it changes; its manifest is generated, at version 0.0.0-dev.
The plugins the working copy uses (its uses) are installed in the dev tenant before it, and granted there: from a folder given with --with (repeatable), which reloads on change like the working copy, or from the source its uses entry names (source: hub:<name>).
With --server, nothing starts here: the working copy goes to a real cluster as a private candidate, on the tenant's online nodes that have the --select labels, which run it instead of the installed version of the plugin, with the tenant's plugins and the secrets its installed version gets.
It answers only on queues of its own: only jobs started against it (run --candidate <id>, StartJobRequest.candidate) reach it, and its nodes take no other work of the tenant while it runs there, so they must leave every installed plugin another node. It takes the operator role in the tenant; an operator's candidate goes only on nodes an admin opened with the label candidates=allow, and gets no secret the installed version does not.
Every step is in the audit log, and the Plugins page shows it with its owner. Every save reloads it; when dev stops it is removed, and the server removes it by itself when dev stops renewing it (its machine went away). Its ID is the same every time you start dev for the plugin, and a new dev takes it over from an old one.
--server is the cluster's management URL, which your CLI context (--context, OZ0_CONTEXT) must point at, or a CLI context file.
Usage
oz0 dev [plugin-dir | file.md] [flags]
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--cache-dir | string | where the dev node keeps uv, Python and Node.js between runs | |
--candidate-ttl | duration | 90s, at most 10m | with --server: how long the candidate outlives this command if it stops renewing it |
--llm-anthropic-url | string | $OZ0_LLM_ANTHROPIC_URL, else https://api.anthropic.com | Anthropic API address for the gateway, such as a proxy or a stand-in |
--llm-openai-url | string | $OZ0_LLM_OPENAI_URL, else https://api.openai.com | OpenAI-compatible API address for the gateway |
--no-first-run | bool | in a folder without a plugin, fail as before instead of starting with the hello agent | |
--node-binary | string | next to this binary, else on PATH | orchestrator-zero-node to run |
--plugin-sandbox | string | the node's, as an installed plugin meets it | the test node's --plugin-sandbox: auto for a plugin that reaches something on this machine, such as a stand-in for its API on localhost, which the node's default refuses |
--runtime-bundle | string | $OZ0_RUNTIME_BUNDLE, else the newest in ./dist/runtime | runtime bundle directory |
--select | stringArray | with --server: only nodes with this label, key=value; repeatable | |
--server | string | try the working copy on this cluster as a private candidate: its management URL, or a CLI context file | |
--tenant | string | default | with --server: the tenant whose nodes, secrets and plugins the candidate uses |
--with | stringArray | a plugin the working copy uses, from this folder: installed first and reloaded on change too; repeatable |
Inherited flags
| Flag | Type | Default | Description |
|---|---|---|---|
--context | string | $OZ0_CONTEXT or <config dir>/orchestrator-zero/context.json | CLI context file written by server init |
--log-level | string | info | log level: debug, info, warn or error |
See all oz0 commands and the global flags.