Files
pipelines/docs/ntfy.md
T

7.7 KiB

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.

# 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. Go checks/file edits still require manual approval; this setting does not grant extra tool access.

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:

# stage notify

```configs
type=ntfy
destination=anime
```

```edges
success -> #success
error -> #failure
```

Configure the pipeline server process outside the pipeline file:

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/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 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, server configuration, iOS self-hosting.