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.
9.1 KiB
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:
```configs
provider=PROVIDER
model=MODEL
harness=opencode
reasoning_effort=high
```
harness defaults to opencode. reasoning_effort is optional; see
harnesses and control. Use the exact IDs your
harness lists (opencode models, pi --list-models).
Per run, without changing the definition:
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.
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
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:
# 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:
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
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.htmlat 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
PATHrecorded when you ran./install(prefixed with<prefix>/bin). Rerun./installfrom a shell where the harness is onPATH, or set an absoluteexecutablewithpipelines harness setup <name> --host --executable /path/to/bin. - Claude Code not listed under Chat. Check
clauderesolves in one of the locations above andclaude auth statusreports 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 customCODEX_HOMEfor the service, so the default~/.codexis used. - "Pi is not configured on this execution server". Run
pipelines harness setup pi --hoston the server machine. - "invalid provider/model identifier". Use the exact IDs from the harness's
model list; placeholders such as
default/defaultare refused.