Overview
How Zeroshot runs a coding task
Zeroshot follows a graph. A worker changes the repository; reviewers check the result before the graph either delivers the work or sends it around the loop again.
Five words used below
- Graph
- The route through a task. It tells Zeroshot what runs next and where rejected work returns; required checks sit on that route.
- Worker
- An agent node that may change files in the shared checkout.
- Reviewer
- A verifier node that checks a result independently and does not edit files.
- Runtime
- The settings used to start a node, including its harness, provider, model, session scope, and connection names.
- Connection
- A named set of private values, such as
OPENAI_API_KEY. The values stay outside GraphSpec and RuntimePlan.
The graph records what happens after review
Suppose the task is to add a health-check endpoint. A worker edits the repository while two reviewers inspect the result from different angles: one checks the requested behavior, and the other checks the code and its safety.
The graph names both outcomes. When the reviewers pass, delivery can start; when either one rejects the change, the comments go back to the worker and both checks run again on the revised files.
Conceptual graph
A failed review loops back to the worker
Reviewers do not edit the checkout. They return comments, and the graph decides which node runs next.
- TaskDescribe the resultAdd a health-check endpoint.
- WorkerEdit the repositoryImplement the requested change.
- ReviewerCheck requested behaviorDoes the endpoint do what the task asked?
- ReviewerCheck code and safetyIs the change correct and safe?
- DecisionDid both pass?Continue only when both reviewers accept.
- DeliveryOpen the pull requestPublish the checked change.
The diagram is conceptual. Zeroshot's built-in software-change graph uses dedicated review_repair and delivery_repair workers for those failure paths, rather than sending every failure to the first worker. Required checks run again after a repair. See the exact built-in flow.
The run can move without changing the task
GraphSpec, run input, and RuntimePlan can stay the same when you switch targets. What changes is where the nodes start and who keeps that machine running; each target also resolves declared connection values from a different source.
| Target | Where the run lives | If your laptop disconnects | Credential source |
|---|---|---|---|
| Local | This computer, in the current checkout | The local process must keep running. | Declared values can come from the process environment. |
| Self-hosted Docker | A private VM that you operate | The VM keeps the run when your laptop disconnects. | The CLI sends fields declared by RuntimePlan. |
| Zeroshot Cloud | Zeroshot-managed capacity | Cloud keeps the run; you can reconnect later. | Saved user or organization connections may fill missing values. |
RuntimePlan gives credentials to one node at a time
GraphSpec routes the work but does not name credentials. For each executable node, RuntimePlan declares a connection key and the environment fields that node needs; the private values remain separate until the target starts the node.
openai → OPENAI_API_KEYBefore the worker starts, the selected target resolves the openai connection and places that field in this process only.
The reviewers do not inherit this worker's key. Their RuntimePlan entries must make their own declarations, while pull-request delivery can use a separate github connection for GH_TOKEN. The connections page explains lookup order.
Next pages
Start with Quickstart if you want to run a task. The other pages cover setup and private values; the contract reference explains the graph's JSON.
- QuickstartRun the built-in software-change graph locally or in Zeroshot Cloud.
- Install and connectInstall the CLI, sign in to a target, and register a repository.
- Connections and profilesSave private values and reusable run settings without putting secrets in JSON.
- Technical contractsRead how Zeroshot validates graph and runtime JSON, then exposes a run through OECP.