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.
This commit is contained in:
2026-11-02 15:54:25 +00:00
parent 1c8680393e
commit 3e100f78f3
6 changed files with 636 additions and 607 deletions
+118 -95
View File
@@ -1,120 +1,143 @@
# Pipelines
Small, reusable AI workflows for coding, research, and everyday project work.
Run them in your browser or terminal using your existing configured harnesses.
Inspect each stage's output, file changes, artifacts, and recorded session.
Small, reusable AI workflows for coding, research and everyday project work,
plus chats with the coding agents you already use.
**Alpha:** single-user, supervised work. Models can make mistakes and editing
workflows can change files and run commands. Start in a disposable project;
review results before trusting them. Provider charges may apply.
Pipelines is one per-user server with three clients:
## Install on macOS or Linux
- **Web app** (Flutter, served behind a sign-in) and the same app as an
**Android APK**.
- **CLI and TUI** (`pipelines`) for scripting, inspection and authoring.
Use a Git checkout and an already configured OpenCode installation. You also
need Go 1.27+, Python 3.9+, Git, curl, a C compiler, and Node.js 18+.
The installer checks prerequisites; it does not replace your harness or provider
credentials. Pi can also be used when configured.
A **pipeline** is a versioned Markdown definition of stages (model, human
decision, notification). A **run** executes it in a project directory on the
server machine. A **chat** is a conversation with an agent harness (OpenCode,
Claude Code or Codex) that the server keeps going while you are away.
**Alpha:** single-user, supervised work. Models make mistakes and editing
stages change files and run commands. Start in a disposable project, review
results, and expect provider charges.
![Workflow](docs/images/workflow.png)
## Install
```sh
git clone https://git.a-wan.net/alan/pipelines.git
cd pipelines
./install
./install # server + CLI + web app, login autostart
./install --apk # optional: Android app, offered to phones for update
```
Native installation is the default: Pipelines runs on your host and reuses your
existing harness setup. Follow the installer's connection details to open the
web app (default `http://localhost:8082/`). Setup creates or reuses its private
web sign-in credentials and enables startup at login. Run as your normal user
in a working macOS launchd or Linux systemd user session.
If no usable model default is configured, setup asks you to select one inside
`./install`; no separate configuration command or test generation is required.
Needs Go (version in `go.mod`), Node.js 18+, Python 3.9+, git, curl, a C
compiler, a **running Docker** (the web app is built in Docker; the install
refuses without it) and an existing OpenCode on `PATH`. The installer never
installs these for you. See [Installation](docs/install.md).
For optional terminal commands, select the installation and add its binaries
to PATH (use your custom prefix if you changed it):
Then open the URL the installer prints (default `http://localhost:8082/`) and
sign in with the password you chose.
## What you can do
**Runs**
- Runs list with filters, multi-select and delete, and sorting by newest,
oldest, **largest on disk**, duration, pipeline or status.
- Run detail tabs: Summary, Timeline, and Artifacts and Changes when the run
has any.
- Artifacts viewer for files a stage produced, including the recorded session
export (`session.html`).
- Changes: the file diffs each stage made in the workspace.
- Human decision stages: a run waits for you; decide in the app or with
`pipelines decide`.
- Retry from the failed stage, cancel, rename, per-run model overrides.
**Pipelines**
- Starter templates, draft-first authoring with a harness, versioned
publishing, import/export as ZIP.
- [Schedules](docs/schedules.md): recurring runs of an existing pipeline.
- Search across pipelines, versions, runs, steps, fields and artifacts.
**Chat**
- Chat with **OpenCode**, **Claude Code** or **Codex** in any folder on the
server, picked with the folder picker.
- Send messages while the agent is working: Claude Code and Codex receive them
mid-turn; otherwise the server queues them durably and delivers them in order
when the turn ends, even with no client attached.
- Approvals, questions, uploads, model choice and interrupt in the app.
- Adopt an existing harness session with `pipelines chat-adopt`.
**Notifications**
- The Android app keeps its own connection and shows notifications in the
background (no ntfy app needed).
- Settings: any run ended, chat needs you, chat reply finished, and
**Also send to ntfy** for devices that still use ntfy.
Pi runs pipeline stages (`harness=pi`) but is not offered as a chat harness.
See [Harnesses](docs/harnesses.md).
## Architecture
```
browser / Android app ──HTTPS (tailscale serve) or HTTP──┐
▼
web proxy (node, 0.0.0.0:8082) ── sign-in, web app, /updates/
│ same-origin /connect, /artifacts/
▼
pipelines CLI/TUI ──ws://127.0.0.1:8080/connect──► pipelines-server (SQLite)
│
┌────────────────────┬───────────────┼───────────────┐
▼ ▼ ▼ ▼
opencode serve pi (RPC) claude (stdio) Codex App Server
stages + chat stages chat chat (socket)
│
▼
ntfy (8090, optional fallback)
```
- **One server process** (`pipelines-server`) owns the database, runs, chats
and notifications. Its API has no authentication and binds to
`127.0.0.1:8080` by default.
- **One web app.** The authenticated Node proxy (`web/serve.mjs`) serves the
installed web build and proxies to the server. Every address (localhost,
LAN, tailnet) reaches this same proxy.
- **Tailnet HTTPS.** When `PIPELINES_WEB_PUBLIC_URL` is an `https://*.ts.net`
address, `./install` runs `tailscale serve` to point it at the proxy.
- **ntfy** is built from source and runs alongside, for optional fallback
delivery and stage notification hooks.
- A login service (launchd on macOS, `systemd --user` on Linux) supervises the
server, web proxy and ntfy together.
## Terminal quick start
```sh
export PATH="$HOME/.local/share/pipelines/bin:$PATH"
pipelines service enable
pipelines service status
cd /path/to/your/project
pipelines # TUI
pipelines run "pipeline name" "Describe a small task"
pipelines runs
pipelines inspect 1
pipelines doctor
```
See [installation](docs/install.md) for autostart controls, custom ports, data
locations, and troubleshooting. No sudo is needed. Keep the raw
Pipelines and harness APIs private. Use the authenticated web proxy for browser
access; do not expose the control APIs to the Internet.
Runs use the directory you start them from, on the server machine. A browser
on another computer does not upload its files.
### Prefer Docker?
## Documentation
```sh
./install --docker
```
Docker remains optional, not the default. It uses its own persistent harness
credentials and needs Docker Compose and Python 3. Do not start a second native
server alongside it. [Docker setup and migration](docs/install.md).
## Try a starter
In the web app, open **Settings → Templates**, select a starter, and create a
pipeline. In the terminal, run `pipelines` and use `:templates`.
Choose a small code change, a read-only review, research, or a document utility.
Starters use your task and selected project—not this repository's paths, stack,
or accounts. They inherit configured model defaults. Templates are available
immediately but are never published or run without your choice.
1. Select the project directory **on the server machine**.
2. Give the pipeline a specific task and run it.
3. Inspect the report, stage visits, and any changed files.
For terminal use, launch from your project directory:
```sh
cd /path/to/your/project
pipelines
# After creating a pipeline:
pipelines run "your pipeline name" "Describe a small task"
pipelines runs
pipelines inspect 1
```
A browser on another machine does not upload that machine's project files.
Recurring work uses separate [saved run schedules](docs/schedules.md), not workflow
definitions. Reuse one pipeline with different prompts and timers; filter both
Pipelines and Runs by scheduling state.
For editing work, use version control and keep a backup. Cancellation and retries
are **not rollback**; a new execution can repeat side effects.
## Sessions and notifications
Pipelines records and exports stage sessions itself. A model stage cannot hand
its result to the next stage until its session is settled and its export is
verified. If export fails, the computed output is retained while export-only
recovery waits; this is not a request to rerun the agent or make a human decision.
See [session capture](docs/notes/session-export-handoff-gate.md).
Notifications have separate channels:
- **Web alerts:** require the page to be open and browser permission where
supported. Closed-app browser push is not implemented.
- **ntfy:** optional phone notifications, independent of the Pipelines app.
Removing the app does not unsubscribe an ntfy client.
See [notification setup](docs/ntfy.md). The installer checks publishing, not
actual delivery to your phone.
## More
- [Alpha walkthrough and known limits](docs/first-version-testing.md)
- [Installation and autostart](docs/install.md)
- [Configured harnesses and models](docs/harnesses-and-control.md)
- [CLI commands](docs/cli.md)
- [Installation and lifecycle](docs/install.md)
- [Harnesses: OpenCode, Claude Code, Codex, Pi](docs/harnesses.md)
- [Notifications](docs/notifications.md) · [ntfy reference](docs/ntfy.md)
- [CLI and authoring](docs/cli.md)
- [Schedules](docs/schedules.md)
- [Pipeline format](internal/author/skill/references/format.md)
- [App (web and Android)](app/README.md) · [Web proxy](web/README.md)
- [Reasoning effort and stage limits](docs/harnesses-and-control.md)
- [Chat backend details](docs/chat-backends.md)
- [Artifacts](docs/stage-artifacts.md) · [File diffs](docs/stage-file-diffs.md)
- [Transfer pipeline definitions](docs/pipeline-transfer.md)
- [Docker installation](docs/docker.md)
- [Web proxy](web/README.md)
- [Alpha walkthrough and known limits](docs/first-version-testing.md)
When reporting a problem, include your OS, install mode, reproduction steps,
`pipelines version --json`, and `pipelines ping --json`. Redact credentials and
private task/file content; do not post your database or native session storage.
`pipelines version --json` and `pipelines ping --json`. Redact credentials and
private content; do not post your database or harness session storage.