ZeroshotCloud

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 this command. The npm package installs the right Zeroshot CLI binary and its agent skill.

Terminal
Zeroshot
npm install --global @the-open-engine-company/zeroshot

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?

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

Sign in once. Each Cloud run resolves the repository and branch from the invoking worktree, then copies that remote revision into a new isolated workspace.

Run from the worktree whose upstream branch should receive the completed change.

Connect Cloud
Zeroshot
zeroshot target login cloud

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 built-in 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.

  1. Zeroshot loads the built-in software-change workflow.
  2. worker changes the code. Then acceptance checks the requested behavior while code reviews the implementation in a separate agent session.
  3. If either review rejects the change, review_repair addresses the feedback and both reviews run again. Zeroshot stops after the workflow's repair limit.
  4. 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.
  5. The CLI keeps showing run updates until the workflow finishes. Add -d when you want the command to return as soon as submission succeeds.