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:
@@ -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.
|
||||
|
||||

|
||||
|
||||
## 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.
|
||||
|
||||
Reference in New Issue
Block a user