> For the index of every page in Orbital's docs, read https://docs.runorbital.dev/llms.txt.

# Switch a run's harness

> Retry a run's current step on another harness, by hand or automatically

Move a run to another [harness](/harnesses/) part way through when its harness runs out of quota, is missing, or does a step badly. Open the run's **Run actions** menu (⋯) and choose **Retry with another harness…**. The current step starts again on the new harness, and the rest of the run stays as it is.

## Before you start

- Install and sign in to the harness you want to move to. **Settings > Harnesses** shows its status.

## Switch the harness

1. **Stop the step.**

   If the step is still working, choose **Pause** and wait until the step stops. A run that has already stopped needs no pause.

2. **Open the dialog.**

   Open the **Run actions** menu (⋯) and choose **Retry with another harness…**.

3. **Pick the harness and retry.**

   Pick the new harness under **Harness**, then choose **Change harness and retry**.

![The Retry with another harness dialog with a Harness picker and a Change harness and retry button.](/screenshots/change-harness-dialog.webp?v=ddbef0b3da)

*Pick the harness, then retry.*

## What changes and what stays

The current step starts again on the new harness, in a fresh session. The new harness then does every later step of the run too, even a step whose style names another harness.

The switch removes `harness`, `model`, `effort`, `connection` and `provider` from every layer a step's settings come from: the step's own keys, its styles, its groups' styles, the workflow's top-level `style` and the run's preset. Harness sub-tables, `persona` and `permissions` stay.

| Part of the run | After the switch |
| --- | --- |
| Each step's persona and permissions | Kept. |
| Settings made for the new harness in a sub-table, such as `codex.model` and `codex.effort` | Kept. |
| A harness, model, effort, connection or provider set on a step or in a style | Dropped. Unless a sub-table for the new harness sets them, it uses its own default model and effort, or the **Default model** and **Default effort** you set for it. |
| Finished steps, the run's context and history | Kept as they are. |
| Worktrees and file changes | Kept as they are. |
| The old harness's session | Does not carry over. |

:::caution[Retrying can repeat work]
Retrying the step can repeat what it already did outside Orbital, such as a comment it posted. Orbital does not undo it.
:::

## Switch from a coding agent

A coding agent can do the same with the [`control_run`](/reference/mcp-tools/#control_run) MCP tool and the `ChangeHarness` action. That action takes an optional `model`, but Orbital refuses the call when you give one. It changes a run's harness, not its model.

To move a run onto a [preset](/reference/settings/#presets) instead, use the `ChangePreset` action with a `preset`. It pins the run to that preset and retries the step. The retried step and every step after it run each role on the preset's harness, model and effort, as a run started with that preset would. `ChangePreset` is allowed whenever `ChangeHarness` is. A preset that does not exist is refused, and the run is left as it was.

## Quota fallbacks

A quota fallback lets [the delivery lead](/delivery-lead/) move a run for you when its harness [runs out of quota](/harnesses/#when-a-harness-runs-out-of-quota). A fallback names a preset. Set it under "When a harness runs out of quota" in **Settings > Harnesses**: **Move to preset** names the preset to move to.

The delivery lead settings show the same list as **Quota fallbacks**, with **Move a run to**. A change in one place changes the other.

The delivery lead applies a fallback with `ChangePreset`: it pins the run to the fallback's preset and retries the step, so each role runs on that preset's harness, model and effort. It moves a run only to a preset in that list whose harness can take it. It does so only when its **Switch a run's harness** permission allows it. That permission is **Do it** unless you change it. Without the delivery lead, Orbital never moves a run by itself.

Earlier versions saved fallbacks as harnesses. When Orbital starts, it converts each one to the first preset on that harness. A fallback no preset runs on is dropped. **Settings > Recent changes** records the conversion.

## Related

- [Harnesses and models](/harnesses/): which harness a step uses and what each status means
- [Pause, stop or resolve a run](/runs/control-a-run/): pause a step before you switch
- [Delivery lead](/delivery-lead/): the agent that applies quota fallbacks
- [MCP tools](/reference/mcp-tools/#control_run): the `ChangeHarness` and `ChangePreset` actions