oz0 run
For: Operators and developers looking up a command.
Start a job for an agent and wait for its answer. AGENT is the agent's or flow's name, or its address, <plugin>/<agent> (the server checks that the plugin defines it). INPUT is text, or JSON for agents with an input schema; "-" reads it from stdin. What the job and each agent it delegated to cost goes to stderr.
While the job runs, what its agents write and the tools they call stream to stderr (--quiet stops that). Jobs are durable: if you stop waiting, the job keeps running; follow it with job watch or job get.
With --continue JOB or --conversation ID the job is a conversation's next turn: the agent gets the earlier turns with your message. Then AGENT may be left out, and the agent of the latest turn answers: run --continue job-1 "and in Paris?". chat AGENT does the same in a loop. Continuing a turn that is not its conversation's latest forks it: the job starts a new conversation that goes on from that turn.
FILE is a path that exists, written as a path, which tells it from an agent's name: an agent in one file (./triage.md, as agent new writes it) or a plugin's folder written as ./triage or triage/ (a bare word is an agent's name even where a folder of that name exists).
It runs once on a dev server and a node of its own, which run starts and stops: the plugin is installed as dev installs it, granted what it uses in the dev tenant (--with installs those plugins from their folders first), with the environment's model keys as the dev tenant's, and its agent (or its only agent or flow) answers INPUT. To run it in your cluster, install it (plugin install ./triage.md) and run it by name.
Usage
oz0 run AGENT|FILE [INPUT] [flags]
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--budget | float | the agent's limits.max_cost_usd | most the job and the jobs it delegates to may spend on LLM calls, in US dollars |
--cache-dir | string | dev's | with a file or a folder: where the dev node keeps uv, Python and Node.js between runs |
--candidate | string | run it on this private candidate (the ID dev --server prints) instead of the installed version | |
--constraint | stringArray | a restriction the job and every job it delegates to must follow, such as --constraint "no personal data leaves the EU"; copied word for word to each child, never summarised; repeat for several (at most 20 of 500 characters) | |
--continue | job | continue the conversation of this job: the new job is its next turn and gets the earlier turns | |
--conversation | ID | continue the conversation of this ID, or start it under this ID when it has no turn yet | |
--data-subject | person | a person the job is about, such as an email address: its payloads are encrypted with a key wrapped by theirs, which subject erase destroys (repeatable, at most 8) | |
--detach | bool | print the job ID and return without waiting | |
--id | string | job ID (default: one the server derives from a key this run sends, so a retry is the same job); the same run again under the ID answers with its job, running or ended, and another input, agent or option under it is refused: an ended job never runs again | |
--json | bool | print JSON instead of a table | |
--node-binary | string | as dev finds it | with a file or a folder: orchestrator-zero-node to run |
--purpose | string | what the job is for, by the tenant's purpose ID: one of the purposes the agent's definition declares | |
--quiet (-q) | bool | do not stream what the agents do; print only the answer and the cost | |
--runtime-bundle | string | as dev finds it | with a file or a folder: the dev node's runtime bundle |
--tag | strings | tag the job, such as --tag incident-42; repeat for several; job search tag:<tag> finds them | |
--team | string | your team, the first by name when you have several | team the job is charged to, for quotas |
--tenant | string | default | tenant to run in |
--timeout | duration | longest the job may run, on top of the agent's own limits | |
--wait | duration | until the job ends | longest to wait for the answer |
--with | stringArray | with a file or a folder: a plugin it uses, from this folder, installed on the dev server first; 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.