ZeroshotPlatform

Start

Quickstart

Run one code change locally or on Platform. 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 18 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. With --ship, the built-in software-change workflow has five agent nodes, so this file binds all five by name. Without a delivery flag, leave out delivery_repair.

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 Platform 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.

The commands are written for bash or zsh; on Windows, set the same variables in PowerShell. 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 on Zeroshot Platform

Sign in once. Each Platform 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 Platform
Zeroshot
zeroshot target login platform

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 Platform reads them from the saved connections.

Platform run
Zeroshot
zeroshot run \
  --target platform \
  --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 Platform target.

To run workers on your own infrastructure, install the self-hosted Docker target on a trusted private VM. Keep port 8080 on the VM's loopback, reach it with ssh -N -L 8080:127.0.0.1:8080 user@your-vm, and register http://127.0.0.1:8080 with --direct.

If you started a target from an earlier version of these docs with -v zeroshot-data:/var/lib/zeroshot/native-v2, keep that mount when you recreate the container, or move the volume's contents into a native-v2/ directory first. Otherwise the target starts with empty storage.

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.