Run

Run jobs

Start an agent, follow it, cancel it and list what ran.

For: people running and reviewing agents.

Use run to start one run of an agent. The command waits for its answer:

Terminal
oz0 run acme-reviewer "Review PR 42 in acme/api"    # text input
oz0 run acme-reviewer '{"repo": "acme/api", "pr": 42}' # JSON, for agents with an input schema
echo "Review PR 42" | oz0 run acme-reviewer -       # input from stdin

The answer goes to stdout. Everything else goes to stderr, so you can pipe the answer on: while the job runs, what its agents write and the tools they call, child jobs on other nodes included, and at the end what the job cost, one row per job in its tree.

lead → oz.delegate {"agent":"helper","task":"Please greet Ada"}
lead ⇢ helper (job job-1746aef4-.../helper-8c872bc6)
helper → team.hello {"name":"Ada"}
helper ← team.hello Hello, Ada!
helper: Done: Hello, Ada!
lead ← oz.delegate Done: Hello, Ada!
lead: Done. Ada has been greeted.

→ is a tool call, ← its result, ⇢ a child job and name: what an agent writes. --quiet turns the live output off.

run also runs flows, by name: their tool steps, agent steps and approvals show up the same way.

Don't wait

Terminal
oz0 run acme-reviewer --detach "Review PR 42 in acme/api" # prints the job ID and returns
oz0 job watch <job-id>                                 # follow it live until it ends
oz0 job get <job-id>                                   # status, answer and cost per branch

Jobs are durable. If you stop waiting, with Ctrl+C or --wait 30s, the job keeps running; follow it again with job watch, or check it with job get.

Choose the ID

Terminal
oz0 run acme-reviewer --id pr-42-review "Review PR 42 in acme/api"

Starting a job under an ID you chose is safe to retry: the same request under the same ID answers with the job it started, showing what GetJob shows you now, so a label the job took since closes what it would close there.

Any other start under an ID a job holds is refused with already_exists, a job with no start recorded to compare with included.

IDs may not contain /, which separates a job from its children, nor \ or ": Temporal's visibility, which finds a job's children, matches no ID that has one.

Control characters (NUL, line breaks, tabs and the like) are refused for the same reason, since retention and erasure find a job's runs by asking Temporal for its ID; a start through the Temporal proxy, and a schedule's action, are held to these two rules as well.

The prefixes the platform names its own jobs with are refused too, so nobody starts a job ahead of the platform under the ID it will use: rt. (routines' fires), evs., kp., jdg., cmp., rpl., shadow-, ev., event-, ch., channel-, gate- (quality gates' eval cases) and hook- (flow webhooks' deliveries).

Limit it

Terminal
oz0 run acme-reviewer --timeout 15m "..."
oz0 run acme-reviewer --budget 0.50 "..."

--timeout limits the whole job on top of the agent's own limits. --budget caps what the job and the jobs it delegates to may spend on model calls, in US dollars; see budgets.

List and cancel

Terminal
oz0 job list                  # recent top-level jobs, newest first
oz0 job list --limit 50 --tenant acme
oz0 job cancel <job-id> --reason "wrong PR"

Cancelling a job cancels the jobs it delegated to as well. The reason goes into the job's history.

A cancel stops a tool call where it runs: a running call reports to Temporal every second, so the cancel reaches it within seconds (a node that stops reporting for 15 seconds loses the call), and the node then cancels it at its tool server, which hears MCP's notifications/cancelled, and stops the job's own sandboxed server.

Until the call has stopped, job get says cancelling (a call is being stopped at its tool) and the console shows cancelling; the job is CANCELED only after.

A tool server that ignores the cancel cannot be stopped this way on a shared server: see cancels and the idempotency key. A call that runs past its tool's timeout is cancelled at the tool the same way.

A job's states

StatusMeaning
RUNNINGA node is working on it, or it waits for one
COMPLETEDIt has an answer
FAILEDIt ended with an error, such as InvalidInput or a limit reached
CANCELEDSomeone cancelled it
TIMED_OUTIt ran out of time
TERMINATEDIt was stopped without cleanup

Follow-up questions

oz0 run --continue JOB "..." asks a follow-up: the new job is the next turn of a conversation and gets the earlier turns, and oz0 chat AGENT does it in a loop. See conversations.

From apps

Apps start and follow jobs through the runtime API on the edge, the same API the CLI uses.

Jobs also start without anyone running a command: routines fire an agent or a flow on a schedule, a webhook or an event, a flow's webhook starts it with the request's body, and MCP and A2A clients start jobs as tasks.

Copyright © 2026