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

# Harnesses and models

> A harness is the coding agent that does each agent step

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](https://pi.dev/). 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](/styles/#how-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](/harnesses/switch-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](/styles/) and [Use different models in one workflow](/harnesses/use-different-models/) explain styles. [Workflow file](/reference/workflow-file/#how-a-steps-settings-resolve) 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.

![Settings, Harnesses page shows a status table for Claude, Codex and OpenCode, then Claude's settings: turned on, program, default model, default effort and environment variables.](/screenshots/settings-harnesses.webp?v=6446e71ff0)

*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](/reference/settings/#harnesses).

## 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:

```sh
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](#when-a-harness-runs-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](#use-more-than-one-claude-account), or stops as [out of quota](#when-a-harness-runs-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](/projects/#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](/styles/#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](/runs/#standings), 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](/harnesses/switch-harness/).

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](/harnesses/switch-harness/) yourself. Or let the delivery lead do it with a [quota fallback](/harnesses/switch-harness/#quota-fallbacks).

## 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](/harnesses/switch-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](/harnesses/switch-harness/): retry a step on another harness, by hand or by quota fallback.
- [Use different models in one workflow](/harnesses/use-different-models/): give steps their own harness, model and effort.
- [Install Orbital](/get-started/install/): install and sign in to a harness.
- [Settings reference](/reference/settings/#harnesses): every harness setting.