Run a first task

This example runs the built-in software-change graph in a local folder, with Git delivery disabled. The template normally creates a PR; this example explicitly uses --delivery none. Git is optional. Add --cwd FOLDER to select another folder; input files stay relative to the invoking folder. Use a project that already has a status command for this example, or replace the task with a change that fits your project.

The worker edits the selected folder

Back up work you want to protect, or commit or stash it in a Git checkout.

1. Write the input

The template expects an object with a task string:

input.json

{
  "task": "Add JSON output to the status command and cover it with focused tests."
}

2. Choose the runtime

A uniform runtime applies one agent configuration to every agent node. Replace the model placeholder with an identifier accepted by the selected provider. Install and sign in to the selected native CLI first; check its version with codex --version, claude --version, copilot --version, or pi --version.

runtime.json

{
  "harness": "codex",
  "provider": "openai",
  "model": "YOUR_MODEL_ID",
  "effort": "high"
}

Zeroshot passes model identifiers to the provider unchanged and does not keep its own model catalog. For this local run, Zeroshot reuses the installed Codex CLI's login and provider configuration; no placeholder API key or openai connection is required. A Docker or Platform run instead derives the canonical OPENAI_API_KEY requirement and resolves it from the submission environment or the target's connection store because it cannot inherit host login state.

For another harness, use its file instead. A local run reuses that CLI's own login in the same way.

runtime.json for Claude Code

{
  "harness": "claude",
  "provider": "anthropic",
  "model": "YOUR_MODEL_ID",
  "effort": "high"
}

runtime.json for GitHub Copilot

{
  "harness": "copilot",
  "provider": "github",
  "model": "YOUR_MODEL_ID"
}

runtime.json for Pi

{
  "harness": "pi",
  "provider": "anthropic",
  "model": "YOUR_MODEL_ID",
  "effort": "high"
}

See Harness adapters for available harness/provider pairs and contributed adapters. Runtimes and connections explains native login and credential requirements.

3. Check the request without starting it

--validate-only materializes the template and uniform runtime, then admits the request with its initial input. It does not contact a target, launch a harness, or start a run. The commands below use one line so they can be pasted into Bash, PowerShell, or Command Prompt.

zeroshot run --title "Add JSON status output" --template software-change --delivery none --input input.json --uniform-runtime-config runtime.json --validate-only

Successful validation writes {"valid":true}. A rejected request names the input, graph, or runtime problem; the selected target checks connection availability later, when it receives the submission.

4. Start the run

Remove --validate-only:

zeroshot run --title "Add JSON status output" --template software-change --delivery none --input input.json --uniform-runtime-config runtime.json

The foreground command streams newline-delimited JSON while the run advances. Ctrl-C closes that stream without stopping the controller; another terminal can read the durable state:

zeroshot list
zeroshot status RUN_ID
zeroshot logs RUN_ID

For a graph view with node transcripts, open zeroshot ui and select the run in Runs.

Normal completion happens when the graph reaches a terminal node. An explicit zeroshot force-stop RUN_ID also closes the run, while engine or target failures can produce a terminal failure result. zeroshot logs RUN_ID keeps the error records that explain a failure, such as a failed node's error or the runtime cause. A failed foreground run exits with status 1 and its error lists the latest of those records, followed by the zeroshot logs command for the rest.

Try the smaller template

single-worker has one agent node and no independent review loop:

zeroshot template show single-worker

zeroshot template show software-change --delivery none shows the graph behind the first example as a tree in a terminal. Names marked * need RuntimePlan bindings; template delivery bindings are supplied automatically. Add --json or redirect stdout to export the complete GraphSpec accepted by --graph and the Python SDK.

zeroshot template show auto-research prints the research graph with its default of ten iterations. Supply a positive options.iterations integer in the run input to set the admitted loop bound. It keeps adopted, record-only, and aborted results under .zeroshot/research; add --push to a run when every finalized iteration should be published.