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:

1. a harness enabled by the host;
2. a provider supported by that harness;
3. an opaque provider-owned model identifier;
4. 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.

Harness adapters lists available adapters and 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 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 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. Local adapters can reuse native authentication as described in Harness adapters. Lanes requiring a connection and contained targets receive 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
foundry	foundry	AZURE_FOUNDRY_API_KEY, AZURE_FOUNDRY_RESOURCE
github	github	COPILOT_GITHUB_TOKEN

Pi, Copilot, OpenCode and Hermes gateway runs additionally require 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.

Source delivery selects its own credentials independently of agent model providers. GitHub uses GH_TOKEN; GitLab uses GITLAB_TOKEN. Local delivery can reuse the selected host's native gh or glab login. See forge delivery setup for explicit instances, Git transport credentials, and target connection examples.

Gateways

To use a gateway, set provider: "gateway" and use 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, Copilot, OpenCode and Hermes gateway lanes let the caller name the wire protocol in GATEWAY_API and use the selected native transport 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.

Microsoft Foundry

The codex and claude harnesses reach models deployed in a Microsoft Foundry resource with provider: "foundry". The model is the Foundry deployment name:

{ "harness": "claude", "provider": "foundry", "model": "FOUNDRY_DEPLOYMENT_NAME" }

Store the API key with the resource name:

zeroshot connection set foundry --field AZURE_FOUNDRY_API_KEY --field AZURE_FOUNDRY_RESOURCE

For a custom domain, declare AZURE_FOUNDRY_BASE_URL instead of AZURE_FOUNDRY_RESOURCE, set to the resource root without an API path. Exactly one of the two must be present. Claude Code runs in its native Foundry mode against https://RESOURCE.services.ai.azure.com/anthropic, or the root URL followed by /anthropic. Codex uses the Azure OpenAI v1 Responses API at https://RESOURCE.openai.azure.com/openai/v1, or the root URL followed by /openai/v1, and sends the key in the api-key header. One connection therefore serves a run that mixes Codex and Claude nodes on the same resource. Foundry lanes accept API keys only; Microsoft Entra ID authentication is not supported.

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.