Harnesses and models

You choose which coding agent does each agent step of a run. That agent is the step’s harness: Claude Code, Codex, OpenCode or Pi. Claude Code, Codex and OpenCode use your installed programs. Pi is bundled with Orbital. Configure credentials for the harnesses you use; each step runs on your own plan. Orbital starts the harness, gives it the step’s prompt and settings, and records what it does. A run can move from one harness to another.

Which harness a step uses

A step’s harness, model and effort come from its styles and its own keys, in the order styles cascade: the step’s own keys, then its styles, then the styles of its groups, then a model picked when the run started, then the workflow’s top-level style. Each is decided on its own, so a step that sets only its effort keeps the harness and model it would have had.

When nothing on the way names a harness, the step takes it from the run’s preset: the preset picked on the Start page or passed to start_run, which pins the run to it, or else the preset in use in Settings > Presets. A run that follows the preset in use moves with it at its next turn when you switch it. When the run’s preset names no harness either, the step uses Default harness in Settings > General. On a fresh install the shipped claude preset is in use.

A harness named when the run starts, with orbital run start --harness, start_run or the API, works like switching the run’s harness. It removes harness, model, effort, connection and provider from every layer, so every step runs on that harness. A model named with it applies to every step, except one whose own keys, styles or groups’ styles set a model for that harness in its sub-table, such as claude.model.

A model that belongs to another harness is refused before the turn starts. The step stops with a reason such as “Model gpt-6-astra runs on codex, not on claude, so the turn was not started.” Change the model in the step’s style or move the step to that harness, then retry.

After a restart, Orbital works out each step’s harness afresh. The run’s header and the composer footer name the harness and model of the same step: the step running now, or the latest one. A run that used more than one pairing says so, for example “Codex · gpt-6-astra, +1 other”.

Styles and personas and Use different models in one workflow explain styles. Workflow file gives the full order.

See a harness’s status

Open Settings > Harnesses. The status table shows, for each harness, whether it is installed, whether it is signed in, and when Orbital last checked. Choose Check again after you install or sign in. Orbital also checks every five minutes.

The status table comes first, then each harness's settings.

Status	Meaning
Installed, version	Orbital found the program and it answered.
Not installed	Orbital found the program neither at the path set in Settings nor on the PATH of your login shell. The message gives the command to install it.
Too old, version	The program is older than the oldest version Orbital works with. The message names that version and the command to update it.
Could not start	The program is there, but it failed to start.
Off	You turned the harness off.
Signed in, Signed out, Sign-in not reported	What the harness says about its login.

Pickers add the reason after a harness’s name, such as “(turned off)” or “(not installed)”.

Harness settings

Each harness has its own group in Settings > Harnesses: Turned on, Default model, Default effort and Environment variables. Claude Code, Codex and OpenCode also have a Program path. See Settings.

Use more than one Claude account

Claude Code keeps each login in a config folder, ~/.claude unless CLAUDE_CONFIG_DIR names another. Give each account its own folder and sign in to it once:

CLAUDE_CONFIG_DIR="$HOME/.claude-work" claude

Run /login in that session, then /status to check which account it uses. Spell the folder the same way every time, without a slash at its end: Claude Code keys its stored login by the folder, so another spelling asks you to sign in again.

Then add each account under Settings > Harnesses > Claude > Accounts, in order of priority. The first account is the primary one, and the rest are fallbacks, tried top to bottom. Use the arrows to change the order. Each account shows whether it is signed in and, when it has run out, until when it is out of quota.

A new session starts on the first account with quota left, and every later turn in that session stays on the same account. When that account reaches a usage, rate or weekly limit, the step carries on in a new session on the next account down, with the run’s context in its prompt as for any fresh step. Orbital never copies a session from one account’s folder to another. The step’s thread says which account ran out and which one took over, and the run page names the account beside the harness, as in “Claude (Work) · claude-opus-5-5”. Only when every account is out of quota does the step stop as out of quota, naming the soonest reset.

Differences between harnesses

Claude Code

Claude Code works in plain folders as well as Git repositories. Claude has usage, rate and weekly limits. When it reaches one, the step moves to your next Claude account, or stops as out of quota when there is none left.

Codex

Codex refuses to start in a folder that is not a Git repository. So a step on Codex needs its primary folder to be one. See plain folders and Git.

To keep a Codex step from writing to the repository, set codex.sandbox_mode = "read-only" in its style. See permissions.

OpenCode

OpenCode works in plain folders as well as Git repositories.

To use OpenRouter models through OpenCode, export OPENROUTER_API_KEY in the shell that starts Orbital, then restart it.

Pi

Orbital bundles the Pi SDK. Configure a provider in Pi, or set its API key in Settings > Harnesses > Pi > Environment variables. Orbital reports Pi’s sign-in status as unknown because credentials belong to individual providers.

Pi streams its responses, tool activity and usage into Orbital, and follows the step’s permission settings. Orbital connects Pi to its MCP tools for handoffs and run controls. Operator extensions are disabled for these turns. Pi still reads its settings, credentials, skills and project instructions. Use provider/model-id for an exact model selection. A style’s pi.model and pi.effort apply only when Pi runs the step.

Attachments reach Pi by their file paths, which its read tool can open.

A missing or switched-off harness

A step whose harness is turned off, not installed, or not set up does not fail. The run stops on that step with the reason on the step. It is Paused, and its badge reads “Waiting on you”. To carry on:

1. Fix the cause.

   Install the harness, sign in, or turn it back on under Turned on in Settings > Harnesses.

2. Check again.

   Choose Check again in Settings > Harnesses.

3. Resume the run.

   Open the run and choose Resume.

Or move the run to a harness that works.

A harness that is off takes no new turns anywhere. Runs that need it stop, and its chats take no new turns.

When a harness runs out of quota

Claude and other harnesses have usage, rate and weekly limits. When a harness reaches one, the step stops with an “out of quota” reason. The reason names the harness and, when it is known, when the quota resets. The run is Paused, with the badge “Waiting on you”.

You can then switch the run’s harness yourself. Or let the delivery lead do it with a quota fallback.

Switch a run’s harness

You can move a stopped run to another harness and retry its current step there. Finished steps, context and file changes stay. Switch a run’s harness gives the steps and what carries over.

A step that goes silent

A turn that writes nothing for the Stalled turn limit is stopped and started again in the same session. The limit is five minutes unless you change it in Settings > General. After two such restarts in one step, the run is Paused, with the badge “Waiting on you”.

Quick reference

	Claude Code	Codex	OpenCode
Install	npm install -g @anthropic-ai/claude-code@latest	npm install -g @openai/codex@latest	npm install -g opencode-ai@latest
Sign in	claude	codex login	opencode auth login
Oldest version Orbital works with	2.1.280	0.156.0	1.18.0
Plain folders	Yes	No, the primary folder must be a Git repository	Yes

Related

• Switch a run’s harness: retry a step on another harness, by hand or by quota fallback.
• Use different models in one workflow: give steps their own harness, model and effort.
• Install Orbital: install and sign in to a harness.
• Settings reference: every harness setting.