Start

Quickstart

Run one code change locally or in Cloud. The built-in workflow gives the task to a worker, then separate agents review the result before pull-request delivery.

1. Install the CLI

Install Node.js 22 or newer, then run these commands. The npm package installs the right Zeroshot CLI binary for your operating system.

Terminal

Zeroshot

npm install --global @the-open-engine-company/zeroshot
zeroshot --version

2. Define the run

Create input.json first. Its task field tells the worker what to change, what behavior you expect, and which tests should pass.

input.json

Zeroshot

{
  "task": "Add a health-check endpoint that returns HTTP 200. Add focused tests and keep the change scoped."
}

Next, save runtime.json. A RuntimePlan chooses the model and connection fields for every node that runs code. The built-in software-change workflow has five agent nodes, so this file binds all five by name.

runtime.json

Zeroshot

{
  "harness": "codex",
  "provider": "openai",
  "size": "medium",
  "nodes": {
    "worker": {
      "kind": "agent",
      "model": "gpt-5.6-sol",
      "sessionScope": "node_instance",
      "connections": {"openai": ["OPENAI_API_KEY"]}
    },
    "acceptance": {
      "kind": "agent",
      "model": "gpt-5.6-sol",
      "sessionScope": "node_instance",
      "connections": {"openai": ["OPENAI_API_KEY"]}
    },
    "code": {
      "kind": "agent",
      "model": "gpt-5.6-sol",
      "sessionScope": "node_instance",
      "connections": {"openai": ["OPENAI_API_KEY"]}
    },
    "review_repair": {
      "kind": "agent",
      "model": "gpt-5.6-sol",
      "sessionScope": "node_instance",
      "connections": {"openai": ["OPENAI_API_KEY"]}
    },
    "delivery_repair": {
      "kind": "agent",
      "model": "gpt-5.6-sol",
      "sessionScope": "node_instance",
      "connections": {"openai": ["OPENAI_API_KEY"]}
    }
  }
}

Leave the delivery node out of runtime.json. The --ship flag adds Zeroshot's trusted deliver binding and declares that it needs the GH_TOKEN field from the github connection.

3. Choose where to run

Use Local when the workers should edit your current checkout. Choose Cloud for a fresh, isolated workspace on Zeroshot's hosted target; both options use the same CLI and files.

Where should the workers run?

LocalEdit this checkoutCloudCreate an isolated workspace

Current machine

Run in the current checkout

Start from a clean checkout with a GitHub origin, and check out the branch Zeroshot should merge into. Workers edit these files in place. Because --ship may commit every workspace change, remove unrelated edits before you run it.

Local runs require macOS or Linux. Put codex, git, and an authenticated gh command on PATH; for this example, running gh auth token must return a token.

Local run

Zeroshot

export OPENAI_API_KEY="..."
export GH_TOKEN="$(gh auth token)"

zeroshot run \
  --title "Health-check endpoint" \
  --template software-change \
  --ship \
  --input ./input.json \
  --runtime-config ./runtime.json

Leave out --target to run on this machine.

Connected target

Run in Zeroshot Cloud

Replace the example repository and branch below, then run the setup commands once. Every Cloud run copies that checkout into a new isolated workspace.

Use the repository and branch where the completed change should merge.

Cloud setup

Zeroshot

zeroshot target add cloud \
  --url https://api.cloud.zeroshot.sh

zeroshot target login cloud

zeroshot target setup cloud \
  --repository your-org/your-repo \
  --branch main

Before you submit, open Connections in the organization console. Save your OpenAI API key there and connect your GitHub account. For an organization repository, a Zeroshot owner or admin must also install the GitHub App and include that repository. The run command below exports no credentials, so Cloud reads them from the saved connections.

Cloud run

Zeroshot

zeroshot run \
  --target cloud \
  --title "Health-check endpoint" \
  --template software-change \
  --ship \
  --input ./input.json \
  --runtime-config ./runtime.json

The name after --target sends this run to the saved Cloud target.

To run workers on your own infrastructure, install the self-hosted Docker target on a trusted private VM.

This example sends its workflow and RuntimePlan with each submission. If you plan to reuse them, save the credentials and run configuration as connections and profiles.

What happens

The overview draws repair as a direct return to the worker so the control loop is easy to see. The built-in template keeps that work in a separate review_repair agent, then sends the result through both reviews again.

Zeroshot loads the built-in software-change workflow.
worker changes the code. Then acceptance checks the requested behavior while code reviews the implementation in a separate agent session.
If either review rejects the change, review_repair addresses the feedback and both reviews run again. Zeroshot stops after the workflow's repair limit.
With --ship, Zeroshot opens or reuses a pull request and waits for its checks. It confirms the merge; a CI or merge failure sends the run to delivery_repair.
The CLI keeps showing run updates until the workflow finishes. Add -d when you want the command to return as soon as submission succeeds.