Files
pipelines/docs/notifications.md
T
alan 3e100f78f3 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.
2026-11-02 15:54:25 +00:00

91 lines
3.5 KiB
Markdown

# Notifications
The server records every notification once and delivers it two ways:
1. **In the Pipelines app** (Android, and the web page while it is open), over
the app's own connection. No ntfy app is needed.
2. **ntfy** (optional fallback), for devices that still use the ntfy app.
The same settings decide what is sent on both paths.
## What notifies
| Event | When |
| --- | --- |
| Run needs your decision | a run reaches a human decision stage (runs not set to Silent) |
| Run failed / succeeded | runs started with **Notify me** (`--notify on`), or every run when **Notify when any run ends** is on |
| Stage hook | a stage's own `notify` block fires ([ntfy reference](ntfy.md)) |
| Chat needs you | a chat asks a question or requests approval |
| Chat replied | an assistant turn ends (off by default) |
Each event notifies once. Opening or dismissing it on one device clears it on
the others.
Chat events are seen while some client has the chat open or the server still
holds queued messages for it. A turn that finishes with no client attached and
nothing queued does not produce a "replied" notification.
## Settings
In the app, **Settings**:
**Notifications** asks for the platform's notification permission.
**Notifications in Pipelines** (Android only):
- **Receive notifications in Pipelines**: starts a background service that
keeps its own connection to the server and posts notifications. Android shows
a quiet "Pipelines is connected" notification while it runs. It restarts
after a reboot or an app update.
- **Status**: the service's connection state.
- **Allow notifications**: shown when Android is blocking Pipelines
notifications.
- **Allow background delivery**: asks Android to exempt Pipelines from battery
optimisation so delivery stays instant while the phone is idle. Grant it.
**Phone notifications** (stored on the server, shared by every device):
| Setting | Default |
| --- | --- |
| Notify when any run ends (otherwise only runs started with **Notify me**) | off |
| Chat needs your answer or approval | on |
| Chat reply finished | off |
| Also send to ntfy (for devices that still use the ntfy app) | on |
Turning **Also send to ntfy** off stops publishing to ntfy; the app still
receives everything.
Per run, choose **Notify me**, the default (auto), or **Silent** when starting
it. From the CLI: `pipelines run … --notify on|auto|off`.
## The web app
The web page shows notifications only while it is open and the browser allows
them. Closed-browser web push is not implemented.
## ntfy (optional)
`./install` builds and runs ntfy on port 8090 with a private `pipelines` topic.
The installer prints the subscription details at the end, and
`pipelines doctor` repeats them (`Phone server … · topic: pipelines ·
username: phone-reader`).
To subscribe from the ntfy app:
1. Add a server: the ntfy address (default `http://<LAN IP>:8090`, or the
`--ntfy-url` you installed with). Off your home network, use a VPN such as
Tailscale.
2. Sign in as `phone-reader`. A freshly created account uses the web sign-in
password; an account kept from an earlier install keeps its old password.
3. Subscribe to the topic `pipelines`.
A tap opens `pipelines://run/<id>` or `pipelines://chat/<id>` in the Android
app; the **Open in browser** action opens the same page on
`PIPELINES_WEB_PUBLIC_URL`.
Notifications already shown by the ntfy app cannot be retracted by the server;
swipe them away there.
See [ntfy reference](ntfy.md) for stage `notify` hooks, explicit ntfy stages,
the app notification protocol and network troubleshooting.