3e100f78f3
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.
221 lines
9.1 KiB
Markdown
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.
|