Harness adapters¶
Official local builds include every adapter below. Install each native CLI separately for local use.
| Harness ID | Providers | Distribution |
|---|---|---|
codex |
openai, openrouter, gateway, bedrock |
Core |
claude |
anthropic, openrouter, gateway, bedrock |
Core |
copilot |
github, openai, anthropic, openrouter, gateway, bedrock |
Core |
pi |
anthropic, openai, openrouter, gateway, bedrock, github |
Core |
opencode |
openai, anthropic, openrouter, bedrock, gateway, github |
Contributed |
hermes |
openai, anthropic, openrouter, gateway, github, bedrock |
Contributed |
Local builds enable contributed-harnesses by default. Platform and the default target image disable
default features and independently admit only the core registry. Targets advertise enabled pairs
through openengine.runtime-harnesses/v1; installing a CLI doesn't enable its adapter. Contributed
lanes require positive advertisement, while older targets without the extension retain legacy core
submissions.
Core adapters receive product maintenance. Contributors maintain their adapters; Zeroshot doesn't guarantee contributed-harness compatibility with native releases. Both groups must implement the same full execution, session and Active Memory contracts. Each runtime names its harness, provider and model explicitly. Model identifiers remain provider-owned strings.
Gateway connections carry GATEWAY_BASE_URL and GATEWAY_API_KEY. Pi, Copilot, OpenCode and Hermes
also require GATEWAY_API: openai-responses, openai-completions or anthropic-messages.
Codex always uses Responses; Claude always uses Messages. Copilot's Bedrock lane uses AWS's
OpenAI-compatible Responses endpoint with AWS_BEARER_TOKEN_BEDROCK and AWS_REGION; an optional
AWS_BEDROCK_BASE_URL preserves a custom endpoint. Models must support the chosen native API.
Local native login works for Codex/OpenAI, Claude/Anthropic, Copilot/GitHub and its OpenAI,
Anthropic and OpenRouter BYOK lanes, and Pi/Anthropic, OpenAI and GitHub. OpenCode and Hermes retain
native authentication for every supported provider except gateway, including the native AWS
credential chain for Bedrock. Other lanes require declared connections. GitHub connections use
COPILOT_GITHUB_TOKEN; each harness owns its native exchange and refresh behavior. Declared
credentials use private runtime state and preserve saved logins.
Local OpenCode and Hermes runs preserve native configuration discovery with declared credentials.
Their declared authentication takes precedence over ambient authentication for the selected lane,
while native settings and plugins continue to apply. OpenCode keeps its original HOME/XDG paths and native
permission policy. Its declared authentication uses a private plugin, so OPENCODE_PURE=true
conflicts with that setup. Native plugins and custom transport code run with the native CLI's authority.
Local OpenCode adds no --auto flag and skips configuration inspection
because that inspection can start background dependency work.
Hermes uses the interpreter from its installed canonical executable and native configuration factories without attaching to its shared gateway. Local profiles, plugins, MCP and permissions remain native. Declared connections override native dotenv values. Remote backends retain native containment limits. Missing native acknowledgement makes cleanup unconfirmed and fails execution; unreported child usage makes totals incomplete.
Contribute an adapter¶
Add an implementation under zeroshot/src/harnesses/adapters/contributed/ and register it in that
directory's register function. Core implementations live beside it under adapters/core/;
existing public native_v2_codex, native_v2_claude, native_v2_copilot and native_v2_pi module
paths remain available to embedders.
A registration supplies a descriptor, provider-access declarations, local path normalization and a
factory. Keep descriptors pure: no credential reads, filesystem inspection, process launches or
provider requests. The registry validates bounded harness/provider IDs and compatible pairs.
Factories receive HarnessBuildContext and return HarnessAdapter with NodeDriver and
SessionFactory implementations.
Adapters own native protocols, authentication translation and permission handling, including their environment allowlists and home/path expansion. Use shared process and session helpers for private execution files, bounded streaming, cancellation and cleanup. Support workers and verifiers with authoritative response validation, bounded corrections, reusable sessions, live output and usage that reports uncertainty when totals are incomplete.
Install the native Active Memory hook, plugin or bridge in the adapter. Shared memory owns recall budgets, receipts and maintenance; missing acknowledgement means unknown delivery evidence.
Run focused fixtures and shared registry/session tests. The ignored contract in
harnesses/live_tests.rs requires a disposable test repository and explicit ZEROSHOT_LIVE_HARNESS,
ZEROSHOT_LIVE_PROVIDER, ZEROSHOT_LIVE_MODEL and ZEROSHOT_LIVE_WORKSPACE values. Set
ZEROSHOT_LIVE_CLI_BINARY to a separately built CLI's absolute path for memory callbacks. Optional
ZEROSHOT_LIVE_CONNECTION_FIELDS lists additional declared field names, separated by commas.
Test native bridges too, and check the core-only library: