# Harnesses A harness is the agent program Pipelines drives. Pipelines never installs, upgrades or signs in a harness for you; it uses the copy and login you already have on the server machine. | Harness | Pipeline stages | Chat | Mid-turn messages | Authoring/debug sessions | | --- | --- | --- | --- | --- | | OpenCode | yes (default) | yes (default) | queued until the turn ends | yes | | Pi | yes (`harness=pi`) | no | n/a | yes | | Claude Code | no | yes | yes, delivered into the running turn | no | | Codex | no | yes | yes, via `turn/steer` | no | Stage configs accept only `harness=opencode` or `harness=pi`. ## Choosing models **Pipeline stages.** Each model stage pins its own model in its `configs` block: ````markdown ```configs provider=PROVIDER model=MODEL harness=opencode reasoning_effort=high ``` ```` `harness` defaults to `opencode`. `reasoning_effort` is optional; see [harnesses and control](harnesses-and-control.md). Use the exact IDs your harness lists (`opencode models`, `pi --list-models`). **Per run**, without changing the definition: ```sh pipelines run "my pipeline" "task" --model PROVIDER/MODEL pipelines run "my pipeline" "task" --stage-model review=PROVIDER/MODEL ``` Precedence: `--stage-model` > `--model` > the model pinned in the stage. Unknown stage keys and malformed models are refused before the run starts. **Defaults for new pipelines and interactive sessions** come from harness profiles in `~/.config/pipelines/harnesses.json` (override with `PIPELINES_HARNESS_CONFIG`). Each profile has an `executable`, a `model` (interactive authoring/debug sessions) and a `pipeline_model` (stages in new drafts and starters). Published versions are never rewritten. ```sh pipelines harness list # profiles, default, launch mode pipelines harness setup opencode --host # fuzzy-pick both models pipelines harness setup pi --host --login # sign in to Pi, then pick models pipelines harness setup opencode --host --model P/M --pipeline-model P/M pipelines harness default pi # default harness for new/edit/debug ``` `--host` writes a native profile and clears any Docker link. `./install` writes the OpenCode host profile itself (from `--model`, the saved profile, or OpenCode's own default) and keeps an existing valid Pi profile; it never adds a Pi profile on its own. `./install --opencode` and `./install --pi` (which run `scripts/setup-harness.py`) apply only to a Docker installation. **Chat** models are chosen in the chat's model picker; each harness supplies its own catalog. ## Verifying ```sh pipelines doctor # health + OpenCode API discovery, no inference pipelines provider-check --model P/M # one tiny tool-free generation (may cost) pipelines provider-check --harness pi --model P/M python3 scripts/check-pi-rpc.py # Pi RPC and policy, no inference ``` `pipelines restart` and `pipelines doctor` print the server's startup report. Its **Chat** row lists the chat harnesses the server found (for example `claude, codex, opencode`), and the **Harnesses** rows list the profiles. Then start a chat with each harness in the app. ## OpenCode **Used for:** default stage harness, default chat harness, and `pipelines new`, `edit` and `debug` sessions. **Found by:** `PIPELINES_OPENCODE`, then `PATH`, then `/opt/homebrew/bin`, `/usr/local/bin`, `/usr/bin`, `~/.local/bin`. `./install` requires `opencode` on `PATH` and records its absolute path. **Launched as:** the server starts its own loopback `opencode serve` for chat and for stage sessions, using your normal OpenCode configuration and login. A server started with `-opencode-endpoint URL` (or `PIPELINES_OPENCODE_ENDPOINT`) attaches chat to that service instead; the native installer does not set this. **Install and sign in:** install OpenCode yourself, then sign in to your providers with OpenCode (`opencode auth login`). Pipelines reads the default model with `opencode api get /api/model/default`. **Mid-turn messages:** not supported by the harness. A message sent while a turn runs is stored in the server's durable queue (up to 8 per chat) and sent in order when the turn ends, also after a server restart. ## Pi **Used for:** pipeline stages with `harness=pi`, and `new`/`edit`/`debug` with `--harness pi`. Not a chat harness. **Found by:** the `executable` in the `pi` profile. A run with a Pi stage is refused unless that profile exists on the server. **Launched as:** `pi --mode rpc --provider P --model M --session-dir --no-approve --no-extensions --no-skills --no-context-files --no-prompt-templates --no-themes --extension policy.js`. The policy extension enforces the stage's tool and edit permissions. `reasoning_effort` maps to Pi's thinking level and is verified before the task is sent. **Install and sign in:** ```sh # install Pi yourself so `pi` is on PATH, then: pipelines harness setup pi --host --login ``` `--login` opens a bare Pi session; run `/login` there, finish the provider sign-in, and exit with Ctrl+C or Ctrl+D to return to model selection. ## Claude Code **Used for:** chat only. **Found by:** `PIPELINES_CLAUDE`, then `PATH`, then `~/.local/bin/claude`, `/opt/homebrew/bin/claude`, `/usr/local/bin/claude`. The server checks again every 10 seconds, so installing it later needs no restart. **Launched as:** one `claude -p` process per active chat with stream-json input and output and `--permission-prompt-tool=stdio` (at most 8 live at once). Idle chats are resumed with `--resume `. Approvals and `AskUserQuestion` appear as cards in the app. **Sign in:** use your existing Claude Code login. A background service can see a stale keychain entry; when the default login check fails, the server retries with the login file in `~/.claude`. For a login that does not depend on either, create a long-lived token and store it privately: ```sh claude setup-token # save the printed token: install -m 600 /dev/null ~/.config/pipelines/claude-token $EDITOR ~/.config/pipelines/claude-token ``` `PIPELINES_CLAUDE_TOKEN_FILE` names another file. The file must be a regular, owner-only file. The startup report shows `Claude service token present` when it is read. An `ANTHROPIC_API_KEY`, `CLAUDE_CODE_OAUTH_TOKEN` or `CLAUDE_CONFIG_DIR` in the server's environment takes precedence. **Models:** the catalog comes from the CLI; switching applies live and is kept for the next turn. **Mid-turn messages:** yes. The message is written to the running CLI's stdin and read at its next step. Model changes apply from the next turn. ## Codex **Used for:** chat only. **Found by:** the Codex App Server control socket at `$CODEX_HOME/app-server-control/app-server-control.sock` (default `~/.codex/...`). The Codex app provides it while it runs. The server checks for it every 10 seconds and attaches when it appears. Pipelines never starts a Codex daemon or changes Codex settings. **Sign in:** your existing Codex login. Threads created from Pipelines are ordinary Codex threads and also show in the Codex app. **Behavior:** new threads use the `workspace-write` sandbox and Codex's own approval policy; command, file-change and permission requests appear as approval cards. **Mid-turn messages:** yes, with `turn/steer` pinned to the running turn. If the turn already ended, the message is queued for the next turn instead. ## Adopting existing sessions ```sh pipelines chat-adopt [--harness opencode|claude|codex] [--title TEXT] ``` Without `--harness`, each available harness is asked. Stop using the session elsewhere once you continue it in Pipelines. ## Limits - Stage session exports: the native session read is capped at 8 MiB and the rendered `session.html` at 8 MiB. A session over the read cap cannot be exported by retrying; the stage reports it. - Claude Code chat history: a transcript over 64 MiB is reported as exceeding the history limit instead of being truncated. - Codex tool detail in history is truncated at 64 KiB and marked as such. - Losing the Codex App Server connection drops pending approvals; they are reported as an error, not shown as still actionable. - Queued chat messages: at most 8 per chat while a turn runs. ## Troubleshooting - **Harness works in a terminal but not from the service.** The login service does not read your shell profile. It uses the `PATH` recorded when you ran `./install` (prefixed with `/bin`). Rerun `./install` from a shell where the harness is on `PATH`, or set an absolute `executable` with `pipelines harness setup --host --executable /path/to/bin`. - **Claude Code not listed under Chat.** Check `claude` resolves in one of the locations above and `claude auth status` reports logged in. - **Codex not listed under Chat.** Open the Codex app and confirm the socket exists under `~/.codex/app-server-control/`. The installer does not record a custom `CODEX_HOME` for the service, so the default `~/.codex` is used. - **"Pi is not configured on this execution server".** Run `pipelines harness setup pi --host` on the server machine. - **"invalid provider/model identifier".** Use the exact IDs from the harness's model list; placeholders such as `default/default` are refused.