Execution Harnesses
When a worker is dispatched, the platform needs to decide two things: which model to call, and which CLI or runtime to run the agent in. The first decision comes from the worker's model preferences. The second — which execution harness to use — is derived from the first. This page explains how these concepts relate and how the platform resolves them.
Core concepts
Five concepts work together to connect a worker's model preference to a running agent:
| Concept | What it represents |
|---|---|
| Model | A provider-independent model definition — for example, "Claude Opus 4" or "GPT-4o" |
| Provider | An inference vendor or gateway — for example, Anthropic, OpenAI, or Amazon Bedrock |
| Model availability | The relationship that makes a model available through a specific provider, supplying the provider-specific model identifier, region, endpoint, and pricing |
| Execution harness | The agent CLI or runtime that runs the agent — for example, Claude Code, Codex, or Aider |
| Sandbox provider | The execution environment where the harness runs (a container, a hosted workspace) — distinct from the harness itself |
Models are provider-independent
A model is a canonical definition that exists independently of any provider. Claude Opus 4 is one model; it may be available through Anthropic's direct API, through Amazon Bedrock, or through both. GPT-4o is one model; it may be available through OpenAI's API or through Azure OpenAI.
A model does not belong to a single provider. Instead, model availabilities connect models to the providers that serve them:
Each availability record carries the provider-specific model identifier (the string sent in API calls), the endpoint, the region, and the pricing. See Providers, Models, and Credentials for details on managing availabilities and credentials.
Execution harnesses are separate from providers
An execution harness is the tool that runs an agent session — it receives the task, manages the conversation with the model, handles tool calls, and produces the result. Examples include Claude Code, Codex, and Aider.
The harness is not the same as the model or the provider:
- Claude Code is a harness. It can run models from Anthropic (direct API) or Amazon Bedrock.
- Codex is a harness. It runs models from OpenAI.
- Aider is a harness. It can run models from multiple providers.
The harness is also not the same as the sandbox provider. A sandbox provider describes where the agent runs (the container or workspace). The harness describes how the agent runs (the CLI or runtime inside that environment).
Model–harness support
Not every harness can run every model. Claude Code does not support OpenAI models; Codex does not support Anthropic models. The platform maintains explicit model–harness support mappings that define which harnesses are compatible with each model availability.
These mappings are managed as part of the model catalog. When model availabilities are added or updated, corresponding harness support entries are maintained alongside them. You do not need to configure these mappings yourself — they are kept current as part of catalog administration.
How the platform uses support mappings
When a worker is dispatched, the platform:
- Reads the worker's model preferences (an ordered list of model availabilities)
- For each availability, looks up which execution harnesses support it
- Filters to harnesses that are both compatible and active on the deployment
This produces a list of executable candidates — each candidate is a model availability paired with a compatible harness. The platform dispatches using the highest-priority candidate that can actually run.
Derived harness selection
The key design principle: you select a model preference; the platform derives the harness. You do not need to set the execution harness on a worker definition. Selecting a model availability is enough — the platform resolves a compatible harness automatically.
How selection works
- The platform reads the worker's model preferences in priority order.
- For each preference, it looks up the configured harness support mappings.
- If a compatible harness exists and is active on the current deployment, the platform dispatches using that combination.
- If the compatible harness is not active locally (for example, Claude Code is not installed on this runner), the preference is skipped.
- The process continues down the priority list until an executable candidate is found.
- If no preference yields an executable candidate, the dispatch fails with an actionable error.
Deterministic selection
When more than one harness supports a given model availability, the platform selects deterministically based on the configured priority of the harness support mappings. The selection is stable — the same configuration always produces the same result, making behaviour predictable and auditable.
Configured compatibility vs. runtime availability
There is an important distinction between these two concepts:
- Configured compatibility means the model catalog says a harness can run a given model availability. This is a data relationship managed in the catalog.
- Runtime availability means the harness is actually installed and active on the deployment where the agent will run. A harness might be configured as compatible but not present on a particular runner.
The platform checks both. A candidate must be both configured as compatible and available at runtime to be selected.
No-match errors
If no model preference yields an executable candidate, the dispatch fails clearly. The error identifies:
- Which model preferences were evaluated
- Why each was skipped (no harness support mapping, or harness not active locally)
- What action to take (add a harness support mapping, activate a harness, or add a model preference with a supported harness)
This makes misconfiguration visible immediately rather than producing silent failures.
Cross-harness failover
Failover in WRM moves between complete candidates — each candidate is a model availability paired with its compatible harness. This means failover can change the harness, not just the provider or model.
Example
Consider a worker with these model preferences:
| Priority | Model availability | Compatible harness |
|---|---|---|
| 1 | Claude Opus 4 via Anthropic | Claude Code |
| 2 | Claude Opus 4 via Bedrock | Claude Code |
| 3 | GPT-4o via OpenAI | Codex |
If Anthropic's API is down and the circuit breaker has tripped:
- Priority 1 is skipped (circuit breaker open for Anthropic)
- Priority 2 is tried — Claude Opus 4 via Bedrock, using Claude Code
- If Bedrock also fails, Priority 3 is tried — GPT-4o via OpenAI, using Codex (a different harness)
The failover crossed from Claude Code to Codex because the next viable model availability required a different harness. This happens automatically — the platform resolves the harness for each candidate independently.
Without model–harness support mappings, this cross-harness failover would not be possible. The old approach of setting a single harness on the worker definition would force all fallback models to use the same harness, making candidates like GPT-4o on Claude Code invalid and unreachable.
Run provenance
Each agent run records which model, provider, and execution harness were actually used. When failover occurs, the run records both the attempts and the final successful combination.
Per-attempt provenance
Each attempt during failover is recorded as part of the run's step trace. The record includes:
| Field | What it records |
|---|---|
| Model | The canonical model that was attempted |
| Provider | The provider through which the attempt was made |
| Model identifier | The provider-specific model identifier used in the API call |
| Execution harness | The harness that was used (or would have been used) for this attempt |
| Outcome | Whether the attempt succeeded or failed, and why |
Final run provenance
The agent run record itself captures the provenance of the successful (or final) attempt:
| Field | What it records |
|---|---|
| Model | The canonical model used for the completed run |
| Provider | The provider used for the completed run |
| Execution harness | The harness used for the completed run |
| Model identifier | The provider-specific identifier sent in API calls |
This provenance makes it possible to answer questions like "which harness did this run actually use?" and "did this run fail over from one harness to another?" — important for debugging, cost attribution, and capacity planning.
For more detail on run tracking, see Agent Runs.
Terminology note
The term backend appears in parts of the API and database to refer to what this documentation calls an execution harness. "Backend" is legacy internal terminology — in user-facing configuration and documentation, prefer "execution harness."
Where backend appears as a field name in API responses or database records, it refers to the execution harness. You should not need to set this field on worker definitions — harness selection is derived from model preferences as described above.
Related pages
- Providers, Models, and Credentials — managing providers, model availabilities, and credentials
- Worker Definitions and Workers — how model preferences are configured on worker definitions
- Agent Runs — run tracking, step traces, and provenance
- Cost Management — budget hierarchy, circuit breakers, and provider failover
- Orchestration — sandbox providers and where agent work runs