Files
pipelines/docs/harnesses.md
T
alan 3e100f78f3 Document the current install, harnesses and notifications
Rewrite the README around the server, web/Android app and CLI, and
replace docs/install.md with the current native install (all-or-nothing
Docker web build, flags from setup-native.py, lifecycle commands, data
locations, password, upgrading). Add docs/harnesses.md and
docs/notifications.md; point ntfy.md at the new overview and fix its
topic name.
2026-11-02 15:54:25 +00:00

221 lines
9.1 KiB
Markdown

# 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 <run 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 <id>`. 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 <session-id> [--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 `<prefix>/bin`). Rerun `./install` from a shell
where the harness is on `PATH`, or set an absolute `executable` with
`pipelines harness setup <name> --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.