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 binding names:

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

The RuntimePlan reference lists the accepted harness/provider pairs. Admission rejects known-incompatible pairs, such as codex with anthropic and claude with openai. 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 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 the selected execution placement. Local codex/openai, claude/anthropic, and copilot/github runs reuse the harness's native login and configuration without inventing a connection. A contained target, or any non-native provider lane, 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`

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 or claude 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 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.