Files
pipelines/docs/install.md
T
alan 108c29f9eb One harness setup path: pipelines harness setup <claude|codex|opencode|pi>
Checks the CLI on the server's PATH (install command when missing), signs in
with the harness's own login only when needed (--login forces it), keeps the
OpenCode/Pi model pickers, and verifies with the server's check. Works on
native and Docker installs (Docker delegates to the container setup); --host
is a hidden compatibility alias. harness list shows all four harnesses'
installed/signed-in/configured/default status. ./install --opencode|--pi now
point to the command; ./install ends with the next-step hint.
2026-11-02 16:11:04 +00:00

273 lines
12 KiB
Markdown

# Installation
`./install` installs Pipelines natively for your user on macOS or Linux. It
builds the server, the CLI and the web app together, installs them under
`~/.local/share/pipelines`, and starts them under a login service. No sudo.
```sh
git clone https://git.a-wan.net/alan/pipelines.git
cd pipelines
./install
```
## Prerequisites
The installer only detects tools. It never installs, upgrades or downloads
them, and it stops naming whatever is missing.
| Tool | Why |
| --- | --- |
| Go (version in `go.mod`, currently 1.27) | builds `pipelines-server`, `pipelines` and ntfy |
| Node.js 18+ | runs the authenticated web proxy (`web/serve.mjs`) |
| Python 3.9+ | installer and the lifecycle manager (`manage.py`) |
| git, curl | source checkout, updates, release lookup |
| C compiler (`cc`, `clang` or `gcc`) | ntfy's SQLite driver is cgo (Xcode Command Line Tools on macOS) |
| **Docker, running** | builds the Flutter web app and the APK |
| OpenCode on `PATH` | required; default stage and chat harness (`curl -fsSL https://opencode.ai/install \| bash`) |
| Pi, Claude Code, Codex | optional; set up after install with `pipelines harness setup <name>` |
| tailscale | optional; tailnet HTTPS access |
The install is **all or nothing**: the web app and the server are built before
either is installed. If Docker is not running, `./install` stops with
"Docker is not running, so the web app cannot be built" and leaves any existing
installation running unchanged.
Run as your normal logged-in user. macOS needs `launchctl` in a GUI login;
Linux needs `systemctl --user`. Other platforms are refused.
## What `./install` does
1. Checks tools, port settings, the login service manager and the OpenCode
executable.
2. Builds the Flutter web app in Docker (pinned to `app/.flutter-version`).
Builds are cached in `~/.cache/pipelines/app-builds` by a digest of the app
sources, so an unchanged app is reused.
3. Builds `pipelines-server` and `pipelines` with `go build -trimpath`.
4. Installs into the prefix: binaries in `bin/`, web app in `lib/app-web`, web
proxy in `lib/web`, `lib/manage.py`, and an empty `lib/app-updates` for APKs.
5. Runs `pipelines skill install` (the authoring skill for OpenCode and Claude
Code skill roots).
6. Writes host harness profiles to `~/.config/pipelines/harnesses.json`. If no
usable OpenCode default model is found, it opens the model picker in the
terminal (or fails without a terminal; pass `--model`).
7. Builds ntfy from its pinned Go module, writes its config and creates the
`pipeline-publisher` and `phone-reader` accounts.
8. Migrates data from an earlier Docker installation, if its volumes exist.
9. Registers the login service, writes the manifest
`<prefix>/pipelines-install.json`, saves `ws://127.0.0.1:<port>/connect` as
the CLI default in `~/.config/pipelines/client.json`, and starts everything.
10. Retires the legacy standalone web agent `net.awan.pipelines.web` on macOS
(stopped, plist renamed to `.disabled`), so only one web app is served.
11. If `PIPELINES_WEB_PUBLIC_URL` is an `https://…ts.net` address, runs
`tailscale serve --bg --https=<port> http://127.0.0.1:<web-port>`.
12. Prints the browser URLs and the next step, setting up harnesses.
## Set up harnesses
One command per harness, the same on native and Docker installations:
```sh
pipelines harness setup opencode # stages + chat (required; ./install already configured it)
pipelines harness setup pi # stages
pipelines harness setup claude # chat
pipelines harness setup codex # chat
pipelines harness list # status of all four
```
Each run checks the CLI is installed where the server finds it (printing the
install command if not), signs in with the harness's own login when needed,
picks OpenCode/Pi default models, and verifies with the server's check. No
restart is needed. See [Harnesses](harnesses.md#set-up-harnesses).
It also warns when a different `pipelines` earlier on `PATH` shadows the new
one; it does not touch that binary.
### Addresses
| Service | Default | Flag |
| --- | --- | --- |
| Web proxy (sign-in, web app, `/updates/`) | `0.0.0.0:8082` | `--web-port`, `--web-host` |
| Server API (no auth) | `127.0.0.1:8080` | `--port`, `--bind-address` |
| ntfy | `:8090` | `--ntfy-port`, `--ntfy-url` |
Expose only the web proxy. A reinstall keeps the saved ports and bind
addresses unless you pass the flag again, so an installation set up with
`--web-port 8083` stays on 8083.
`PIPELINES_WEB_PUBLIC_URL` is the address phones and notification links use.
Set it once; reinstalls keep it:
```sh
PIPELINES_WEB_PUBLIC_URL=https://mymac.tailnet-name.ts.net ./install
```
Without it the installer records `http://<LAN IP>:<web-port>`. Use HTTPS or a
VPN for remote access; plain HTTP does not protect the password.
## Flags
From `arguments()` in `scripts/setup-native.py`:
| Flag | Effect |
| --- | --- |
| `--prefix PATH` | install location (default `~/.local/share/pipelines`, or `PIPELINES_PREFIX`) |
| `--port N` | server API port (default 8080) |
| `--bind-address IP` | server API bind (default `127.0.0.1`) |
| `--web-port N` | web proxy port (default 8082) |
| `--web-host IP` | web proxy bind (default `0.0.0.0`) |
| `--ntfy-port N` | ntfy port (default 8090) |
| `--ntfy-url URL` | ntfy address given to phones (default `http://<LAN IP>:<ntfy-port>`) |
| `--timezone TZ` | override the detected timezone (fallback UTC) |
| `--model PROVIDER/MODEL` | default model for new starters and missing OpenCode profile fields |
| `--allow-authoring` | allow creating and publishing pipelines (fresh installs default to this) |
| `--no-authoring` | execution-only server |
| `--fresh` | start empty even if earlier Docker volumes exist |
| `--replace-data` | let Docker migration overwrite existing native data |
Reinstalls keep the recorded authoring role unless you pass one of the two
role flags.
## Other install modes
```sh
./install --web # rebuild and install only the web app (Docker), then reload the page
./install --apk # build the Android APK (Docker, slower) and offer it to phones
./install --docker # server and ntfy in Docker Compose instead of native
```
`./install --apk` builds a release APK for this installation's web address,
copies it to `<prefix>/lib/app-updates/pipelines.apk` with a `version.json`,
and serves it at `<web>/updates/` behind the sign-in. On the phone:
**Settings → App updates → Check for updates**, then **Download and install**.
The first install can use `<web>/updates/pipelines.apk` directly. Every APK is
signed with the key in `~/.config/pipelines/android/` (seeded from
`~/.android/debug.keystore` if present), so each build installs over the last.
Options: `--server-url ws(s)://host:port/connect`, `--notes TEXT`, `--prefix`.
`./install --docker` is the optional Compose installation with its own
container harness credentials; see [Docker](docker.md). Do not run it
alongside a native install on the same ports. Its harnesses are set up with
the same `pipelines harness setup opencode|pi` (run from the checkout), which
configures them inside the container. The old `./install --opencode` and
`./install --pi` only print that command and exit.
## Lifecycle commands
Put the installed CLI on `PATH`:
```sh
export PATH="$HOME/.local/share/pipelines/bin:$PATH"
```
The installed `pipelines` finds its own manifest. `PIPELINES_PREFIX` selects
another installation.
| Command | Effect |
| --- | --- |
| `pipelines start` | start server, web proxy and ntfy; print the startup report |
| `pipelines stop` | stop all three (active runs are interrupted; edits are not rolled back) |
| `pipelines restart` | stop then start, keeping data |
| `pipelines doctor` | startup report, health of server and ntfy, OpenCode API check (no inference) |
| `pipelines status` | server, host and ntfy publishing health, from the running server |
| `pipelines logs` | follow `logs/server.log` |
| `pipelines update` | pull and reinstall the same way, then restart (see below) |
| `pipelines uninstall [--purge] [--yes]` | remove the service and binaries; `--purge` also deletes data |
| `pipelines service enable [--print]` | enable and start login autostart (`--print` previews the definition) |
| `pipelines service disable` | disable autostart and stop the supervisor |
| `pipelines service status` | autostart and supervisor state |
The login service is `~/Library/LaunchAgents/net.a-wan.pipelines.plist` on
macOS and `~/.config/systemd/user/net.a-wan.pipelines.service` on Linux. It
runs `manage.py supervise`, which owns all three processes. This is login
autostart, not boot-without-login.
## Where things live
| Path | Contents |
| --- | --- |
| `<prefix>/pipelines-install.json` | manifest (ports, paths, install args, environment) |
| `<prefix>/bin/` | `pipelines`, `pipelines-server`, `ntfy` |
| `<prefix>/data/pipelines.db` | SQLite database (definitions, runs, chats, settings) |
| `<prefix>/data/artifacts/` | run artifacts and session exports |
| `<prefix>/data/ntfy/` | ntfy config, cache and accounts |
| `<prefix>/secrets/publisher-token` | ntfy publishing token |
| `<prefix>/logs/` | `server.log`, `web.log`, `ntfy.log`, `supervisor.log` |
| `~/.config/pipelines/web-auth.json` | web password and cookie secret (`PIPELINES_WEB_AUTH_FILE`) |
| `~/.config/pipelines/harnesses.json` | harness profiles (`PIPELINES_HARNESS_CONFIG`) |
| `~/.config/pipelines/client.json` | default server URL for the CLI/TUI |
| `~/.config/pipelines/claude-token` | optional Claude Code service token |
| `~/.config/pipelines/android/` | APK signing key |
| `~/.cache/pipelines/app-builds/` | cached web and APK builds |
`<prefix>` is `~/.local/share/pipelines` unless changed. On Linux the
supervisor's output also reaches `journalctl --user -u net.a-wan.pipelines.service`.
## Web sign-in password
On a new computer `./install` asks for the password (8+ characters, typed
twice). Without a terminal, set `PIPELINES_WEB_PASSWORD`. It is stored in
`~/.config/pipelines/web-auth.json` (mode 0600) with a generated cookie secret,
and reused unchanged on every reinstall. An invalid or non-private file stops
the installer rather than being reset.
The same password is given to the ntfy `phone-reader` account when that account
is first created; existing ntfy accounts keep their passwords.
To change the web password, edit `password` in `web-auth.json` (keep it 0600)
and run `pipelines restart`.
## Upgrading
```sh
pipelines update
```
`update` refuses while runs are executing (finish or cancel them first). It
then runs `git pull --ff-only` in the checkout it was installed from (skipped
when the branch has no upstream), re-runs `./install` with the recorded
arguments, restarts, and prints the startup report. Data, passwords, ntfy
accounts and the signing key are kept. If the installer fails, the previous
version keeps running.
Running `./install` again from the checkout does the same without the pull.
Run `./install --apk` again to offer a new APK to phones.
## Uninstall
```sh
pipelines uninstall # keeps data and credentials in <prefix>
pipelines uninstall --purge # also deletes <prefix>, including the database
```
Neither touches OpenCode, Claude Code, Codex, Pi or files in
`~/.config/pipelines`.
## Developer server
For working on Pipelines itself, run a server in the foreground on spare
ports. This is not the supported installation and does not serve the web app:
```sh
go run ./cmd/pipelines-server -db /tmp/dev.db -addr 127.0.0.1:8081
go run ./cmd/pipelines --url ws://127.0.0.1:8081/connect tui
```
`go run ./cmd/pipelines-server -help` lists the server flags (`-addr`, `-db`,
`-allow-authoring`, `-opencode-endpoint`). Without `-db` it uses the standard
per-user data directory (`XDG_DATA_HOME`, or Application Support on macOS).
## Troubleshooting
- **"Docker is not running"**: start Docker Desktop (or the daemon) and rerun.
- **Ports busy**: a Docker installation or an old server may hold 8080, 8082 or
8090. Stop it, or choose other ports with the flags above.
- **"No usable configured harness model"**: rerun `./install` in a terminal to
pick models, or pass `--model PROVIDER/MODEL`.
- **CLI talks to the wrong server**: `PIPELINES_URL` overrides the saved
default; unset it. Check `pipelines connection`.
- **Web app missing**: the server refuses to start without it. Run
`./install --web`.
- **A harness works in the terminal but not in the service**: the service uses
the `PATH` recorded at install time; `pipelines harness setup <name>` says
so. Rerun `./install` from a shell where the harness is on `PATH`. See [Harnesses](harnesses.md#troubleshooting).