151 lines
7.7 KiB
Markdown
151 lines
7.7 KiB
Markdown
# Self-hosted ntfy delivery
|
|
|
|
Every stage can have an optional `notify` property block. Notifications go to
|
|
your own ntfy instance and can attach Markdown and output files. It does not ask
|
|
an LLM to handle credentials or run curl. The full Markdown remains in the run
|
|
audit as well as the ntfy attachment. A separate HTML report viewer is not included.
|
|
|
|
## Per-stage notifications (recommended)
|
|
|
|
````markdown
|
|
# stage compose
|
|
|
|
```notify
|
|
on=success,failure
|
|
artifacts=markdown,files
|
|
```
|
|
|
|
...stage output, prompt, tools, edges, and configs...
|
|
````
|
|
|
|
- `on` is `success`, `failure`, or `success,failure`. A failure is an execution
|
|
error, the `error` outcome, or a route to `#failure`; any other completed stage
|
|
is a success. This reports the stage's result, not the final run's result.
|
|
- All notification hooks use one system-wide server-to-phone connection. Stages
|
|
do not choose topics or addresses. Configure `PIPELINES_NTFY_URL` (publishing
|
|
topic URL), `PIPELINES_NTFY_PUBLIC_URL` (phone-facing server base URL), and
|
|
`PIPELINES_NTFY_TOKEN` or `PIPELINES_NTFY_TOKEN_FILE` once on the server.
|
|
The topic is `pipelines` in the provided setup. No block means no notifications.
|
|
Legacy `destination` lines remain parseable for immutable-history compatibility
|
|
but no longer select a connection for notification hooks. Explicit native
|
|
`type=ntfy` stages retain their separate destination configuration.
|
|
- `artifacts=markdown` sends the string in `output.markdown` as `digest.md`.
|
|
- `artifacts=files` sends paths listed in `output.artifacts`, e.g.
|
|
`["reports/result.txt", "screenshots/chart.png"]`. Model stages with this policy
|
|
are instructed to list files they actually created/modified. No workspace scan
|
|
or file discovery occurs; an invalid model response may leave no artifact list.
|
|
- Both artifact kinds can be selected. Each file gets a separate notification
|
|
(ntfy supports one attachment per notification). If none were produced, an
|
|
event-only notification is still sent, including on failure.
|
|
- Files must be workspace-relative regular files, at most 1 MiB each and 10 files
|
|
per stage. Traversal, absolute paths, symlinks, hidden paths, known database/key
|
|
paths, `secrets/`, and `node_modules/` are rejected. These guards are not a
|
|
content scanner/DLP system: only list files you intend to share.
|
|
- Notifications have a 30-second total budget, with no automatic retries. Their
|
|
receipts/failures appear in the selected run stage's **Metadata**, separately
|
|
from output. They do not change routing or convert a successful stage into a
|
|
failed run. A crash can leave a `sending` receipt with uncertain delivery;
|
|
notifications are not replayed during recovery. Tool access follows the stage's
|
|
declared tools; notification settings do not grant additional tools.
|
|
|
|
## Explicit delivery stage (optional)
|
|
|
|
The preceding stage must output three nonempty UTF-8 strings: `title`, `summary`,
|
|
and `markdown`. Title/summary must be single-line (256/2048 byte limits); Markdown
|
|
is limited to 1 MiB. Native delivery stages do not accept model prompts/tools or
|
|
inline credentials. They require `destination` and a `success` edge:
|
|
|
|
````markdown
|
|
# stage notify
|
|
|
|
```configs
|
|
type=ntfy
|
|
destination=anime
|
|
```
|
|
|
|
```edges
|
|
success -> #success
|
|
error -> #failure
|
|
```
|
|
````
|
|
|
|
Configure the **pipeline server process** outside the pipeline file:
|
|
|
|
```sh
|
|
export PIPELINES_NTFY_ANIME_URL='https://ntfy.your-domain.example/anime'
|
|
# Set PIPELINES_NTFY_ANIME_TOKEN securely to a publishing user's access token.
|
|
go run ./cmd/pipelines-server
|
|
```
|
|
|
|
The URL includes one topic, without credentials, query parameters, or a fragment.
|
|
Other destinations use the same pattern: `destination=reports` reads
|
|
`PIPELINES_NTFY_REPORTS_URL` and `PIPELINES_NTFY_REPORTS_TOKEN` (or `_TOKEN_FILE`
|
|
pointing to a secret file). Set only one token source. Destination names
|
|
use lowercase letters, digits, and underscores. A token is optional only when
|
|
the configured server permits anonymous publishing; private deployments need it.
|
|
Never put tokens in a prompt, committed file, or chat. Environment credentials
|
|
are inherited by subprocesses: do not grant untrusted stages shell/code-execution
|
|
access. Prefer a dedicated publishing user with write-only access to this topic.
|
|
|
|
## Local server
|
|
|
|
The root `compose.yaml` runs **both the pipeline server and ntfy** with persistent
|
|
volumes, internal service networking, and a private topic. See the
|
|
[Docker + Android setup](docker.md) for bootstrap, credentials, and timezone
|
|
detection. The previous ntfy-only Compose file has been replaced. Docker's daemon
|
|
was unavailable; deployment is **not tested**. HTTP integration tests use an
|
|
ntfy-compatible test server, not a running ntfy instance.
|
|
|
|
Use a TLS reverse proxy or a private VPN (e.g. Tailscale). A phone cannot reach
|
|
your computer's `127.0.0.1`; that address is only for local publishing/proxying.
|
|
To bind the container to a particular LAN/VPN interface, explicitly set
|
|
`NTFY_BIND_ADDRESS` to that interface IP. Do not expose an unauthenticated server,
|
|
or send access tokens over public plain HTTP. Set `NTFY_BASE_URL` to the same
|
|
address your phone uses so attachment URLs resolve correctly. If the pipeline
|
|
server is another container, localhost is that container, not the ntfy host.
|
|
|
|
## Phone
|
|
|
|
Install the ntfy app, add your own server, authenticate with the reader account,
|
|
and subscribe to `anime`. Ensure notifications and required background operation
|
|
are allowed. Outside your home network, both topic subscriptions and attachment
|
|
downloads need access to your server through VPN or public HTTPS.
|
|
|
|
For **iOS instant notifications**, ntfy's current documentation requires
|
|
`NTFY_UPSTREAM_BASE_URL=https://ntfy.sh` (or an APNS-connected upstream with a
|
|
custom app). The upstream sends wake-up requests; message content is fetched
|
|
from your instance. This is not completely independent of third-party push
|
|
infrastructure. Without upstream forwarding, delivery can be substantially
|
|
delayed. Phone delivery/background behavior has **not been tested** here.
|
|
|
|
## Execution and failure behavior
|
|
|
|
- Publishing is bounded to 20 seconds and does not follow redirects.
|
|
- No automatic publish retry: timeouts or malformed acknowledgments may mean the
|
|
notification was delivered but its acknowledgment was lost. Inspect ntfy
|
|
before retrying an ambiguous failure.
|
|
- For the optional native `type=ntfy` stage, a confirmed response adds `delivery` metadata (destination name, message ID,
|
|
attachment URL, filename) to the existing output. Failures take the error route
|
|
and are recorded in normal run/step audits, without remote response bodies or
|
|
credentials in diagnostics.
|
|
- Repeating the same run request key does not publish again. A new run or a graph
|
|
loop visiting delivery again can send another notification; content-level
|
|
"only new items" deduplication is not yet implemented. For the initial digest,
|
|
keep notification last with no feedback edge.
|
|
- Markdown reports remain available in pipeline run history even after ntfy expires its
|
|
attachment. Configure ntfy retention for your needs; its attachment directory
|
|
must be dedicated to ntfy, not shared with other files.
|
|
|
|
File-attachment bytes are stored by ntfy, not permanently archived in SQLite;
|
|
run metadata stores the delivered filename/URL, and workspace files may later
|
|
change. Download attachments before your ntfy retention expires.
|
|
|
|
`examples/anime-digest.md` provides discover → compose with per-stage notification hooks and daily 19:00
|
|
scheduling. It uses direct `webfetch` of Jikan's current-season API, avoiding the
|
|
unconfigured OpenCode search-provider selection. The example is a file only;
|
|
submitting it activates its schedule. Its anime/model/phone path is **not tested**.
|
|
|
|
References: [publishing](https://docs.ntfy.sh/publish/),
|
|
[server configuration](https://docs.ntfy.sh/config/),
|
|
[iOS self-hosting](https://docs.ntfy.sh/config/#ios-instant-notifications).
|