Skip to content
Orbital
Menu
DocsExamplesReference
Get started
OverviewInstall OrbitalStart your first runBuild with AI
Concepts
How Orbital worksRunsWorkflowsDurability after restartsProjects and foldersHarnesses and modelsStyles and personas
Runs
Start a runWatch a runMessage a runPause, stop or resolve a runThe run queue
Workflows
Write your first workflowWrite promptsAdd branchesDecide with a modelAdd a loopRun steps in parallelReuse a workflowPass context between stepsAdd gates and waitsPush and open pull requestsRepeat a workflowOne-off workflows
Automate
TriggersMake a trigger ruleDelivery leadLead deliveryChats
Configure
Create a projectWorktrees and deliverySwitch a run's harnessUse different modelsGive steps a styleSettingsSet up decision modelsRun on your other computers
Connect agents
Connect a coding agentUse the shipped skillsCommand line
Troubleshooting
Troubleshooting
Changelog
Changelog

Switch a run's harness

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

Move a run to another harness 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

Section titled “Before you start”
  • Install and sign in to the harness you want to move to. Settings > Harnesses shows its status.

Switch the harness

Section titled “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.
    Pick the harness, then retry.

What changes and what stays

Section titled “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.

Switch from a coding agent

Section titled “Switch from a coding agent”

A coding agent can do the same with the 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 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

Section titled “Quota fallbacks”

A quota fallback lets the delivery lead move a run for you when its 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.

Section titled “Related”