Runtimes and connections¶

A graph defines the work and its control flow; the runtime plan supplies execution details for each executable node. Since the two documents are separate, local, self-hosted, and managed targets can run the same graph.

The RuntimePlan reference lists every field, limit, and admission rule.

Four explicit choices¶

Each agent node uses:

a harness, codex, claude, copilot, or pi;
a provider supported by that harness;
an opaque provider-owned model identifier;
zero or more named connections, each declaring exact environment field names.

The harness and provider form the node's effective lane. A plan's run-level harness and provider are the default lane for every agent node, and a binding can override them with its own lane, for example to have Codex implement and Claude Code review. Zeroshot starts one harness adapter per distinct effective lane, and each node runs on its own lane's CLI. Model and connections are always chosen per node.

The RuntimePlan reference lists the accepted harness/provider pairs, which apply to the default lane and to every node's lane. Admission rejects known-incompatible pairs, such as codex with anthropic, claude with openai, and pi with github. Zeroshot does not check current provider availability, and model names remain provider-owned.

Uniform and exact plans¶

--uniform-runtime-config expands one agent binding across all executable nodes, which keeps a built-in template configuration short:

{
  "harness": "claude",
  "provider": "anthropic",
  "model": "PROVIDER_MODEL_ID",
  "size": "medium",
  "effort": "high",
  "sessionScope": "execution"
}

--runtime-config accepts a full plan with one same-named binding per executable graph node. Use it when reviewers and workers need different lanes, models, effort, sessions, or connections. Inspect node names first with zeroshot template show TEMPLATE.

Session scope decides whether a node that runs again, such as in a loop, continues its provider session; see session scope.

Runtime configuration contains names, not secret values¶

A connection maps a stable key to required environment field names:

{
  "connections": {
    "openrouter": ["OPENROUTER_API_KEY"]
  }
}

The submission environment or a target-owned connection store supplies the values. Zeroshot keeps them out of the graph, runtime JSON, run ledger, and observation records.

When connections is omitted, Zeroshot materializes provider access for each node from its effective lane and the selected execution placement. On a local run, nodes on the codex/openai, claude/anthropic, copilot/github, pi/anthropic, and pi/openai lanes reuse the harness's native login and configuration without inventing a connection. On a contained target, or on any non-native provider lane, a node receives these canonical requirements:

Provider	Connection key	Fields
`openai`	`openai`	`OPENAI_API_KEY`
`openrouter`	`openrouter`	`OPENROUTER_API_KEY`
`anthropic`	`anthropic`	`ANTHROPIC_API_KEY`
`gateway`	`gateway`	`GATEWAY_BASE_URL`, `GATEWAY_API_KEY`
`bedrock`	`bedrock`	`AWS_BEARER_TOKEN_BEDROCK`, `AWS_REGION`
`github`	`github`	`COPILOT_GITHUB_TOKEN`

A pi gateway run additionally requires GATEWAY_API, which names the wire protocol (openai-responses, openai-completions, or anthropic-messages). The Codex and Claude gateway lanes do not use it.

A run's connection requirements are the union over its nodes. A contained run with a Codex/OpenAI worker and Claude/Anthropic reviewers can therefore require both OPENAI_API_KEY and ANTHROPIC_API_KEY.

Compatible authored connections take precedence, including CODEX_API_KEY for contained OpenAI access and Claude's supported auth-token variables for contained Anthropic access. Local profiles keep the authored runtime unchanged; applying one to a target derives the contained requirements at submission time. Profiles stored on a target derive those requirements when they are stored.

Local Claude workers and reviewers preserve the invoking shell's USER for macOS Keychain login and reuse native CLAUDE.md, plugins, and MCP configuration. Claude's --safe-mode applies only to the permission-settings probe before a model turn. Hosted runs use private homes and do not inherit the caller's USER or user configuration. Declare additional environment fields needed by MCP servers through runtime connections.

Store a local static connection by prompting for its fields:

zeroshot connection set openrouter --field OPENROUTER_API_KEY
zeroshot connection list

connection set replaces the whole value for that key, so repeat every required --field when updating a multi-field connection. connection list reports names and kind but never values.

Hosted targets can also own user- or organization-scoped connections. Setup and dynamic connection kinds depend on the target; Zeroshot consumes only the resolved fields declared by the runtime.

Gateways¶

Use provider: "gateway" with codex, claude, or pi and the gateway's model identifier:

{ "harness": "codex", "provider": "gateway", "model": "PROVIDER_MODEL_ID" }

Store the endpoint and key together through the existing connection command:

zeroshot connection set gateway --field GATEWAY_BASE_URL --field GATEWAY_API_KEY

Codex requires the OpenAI Responses API, including streaming and tool calls; Chat Completions alone is insufficient. It sends the key as a bearer token. Claude requires the Anthropic Messages API and sends the key in x-api-key. The pi gateway lane lets the caller name the wire protocol in GATEWAY_API and reaches any endpoint Pi implements without probing it; an unrecognized value fails before launch. The selected gateway/model must support the harness's requests, including structured output. Zeroshot does not probe capabilities or translate protocols.

Supply the base URL expected by the selected harness, including any gateway path prefix. Zeroshot preserves that path. For OpenRouter, use https://openrouter.ai/api/v1 with Codex or https://openrouter.ai/api with Claude. Base URLs must use HTTP(S) and cannot contain embedded credentials, query parameters, or fragments. Both fields remain connection values, outside runtime JSON and run history. Exact plans declare these fields under any chosen connection key.

Docker runtimes can prepare shared tools, project dependencies, and services with setup and startup hooks. See Prepare a runtime environment for the installation conventions, resume behavior, and direct-target ownership boundary.

Renewable local GitHub delivery credentials¶

A trusted local host can set ZEROSHOT_GITHUB_TOKEN_FILE to a private token file outside the checkout. Use a delivery binding with "connections": {}: the controller receives the credential without adding it to agent bindings. The file contains one token, optionally followed by a newline. It must be a regular file owned by the controller user with no access for other users.

The host obtains short-lived tokens and renews them by atomically replacing the file. Mount its parent directory if the host writes outside a container. Zeroshot reopens the path on each delivery visit and after authentication rejection; an unchanged rejected token waits for host renewal. Explicit GH_TOKEN takes precedence, including failing on an empty or malformed value.

The file setting and credential stay out of provider environments, profiles, run history, and recovery metadata. Resume selects the caller's current setting again and retains the delivery branch identity. This keeps credentials out of agent environments; it does not isolate a trusted controller from other processes running as the same OS user. Named targets continue to use their existing credential resolver.

Trusted local delivery validation¶

Set ZEROSHOT_DELIVERY_CHECK_COMMAND to one absolute executable path outside the checkout to validate publication and merge candidates. It must be private to the controller user and executable; this setting accepts no command arguments or shell expression. The controller owns its process and passes candidate facts through the delivery validation protocol. The caller selects this capability outside graph and runtime input. The setting stays out of provider context and run/recovery history, and resume selects the caller's current executable again.