How to Get ntfy Notifications on Mac

Short answer

Pick the method that matches how you use your Mac.

For a native Mac inbox, install NTBX, subscribe to an HTTPS ntfy topic, allow macOS notifications, and keep the app running. Publish to that topic from your CI runner, cron job, or monitoring tool. The official mobile app, PWA, and CLI offer other ways to subscribe; the comparison below explains their setup and delivery tradeoffs.

Jump to the NTBX setup and curl test →

At a glance

Four ways to receive ntfy messages.

Method 1

Run the official ntfy app on Apple Silicon.

The official ntfy iPhone and iPad app can run on Apple Silicon Macs. Install it from the App Store, add an ntfy.sh or self-hosted server, and subscribe to your topics. This is the shortest path if you want the official client and your Mac supports iPhone and iPad apps.

The important caveat is presentation and integration: Apple labels the listing Designed for iPad. Not verified for macOS. It works as an iPad-style app on Mac rather than as a desktop interface designed around the menu bar.

View the official ntfy App Store listing ↗

Method 2

Install the official ntfy web app.

The ntfy PWA turns the web interface into a standalone app. Safari can add a site to the Dock on macOS 14 Sonoma or later, while Chromium browsers can install the PWA from their address bar or menu. You keep the full web interface, including subscriptions and message history managed by that ntfy server.

Background behavior is not identical across browsers. The official compatibility table says Chrome, Firefox, Edge, and Opera do not receive desktop Web Push after the browser exits; Safari is the exception. Web Push can also pause when the web app has not been opened for an extended period.

For a self-hosted server, background notifications require its Web Push settings to be configured. Without that setup, keep the web app open for live delivery.

Read the official ntfy desktop PWA guide ↗

Method 3

Subscribe with the ntfy CLI.

The ntfy command-line client can subscribe to one or more topics and run a command for every message. On macOS, the client configuration lives at ~/Library/Application Support/ntfy/client.yml. You then supply or maintain the command that turns each incoming message into a local notification.

This route is flexible enough for filters, scripts, and custom actions, but it is not a ready-made Mac inbox. Reliable delivery also means arranging for the subscriber to keep running and maintaining any notification command it calls.

Read the official ntfy CLI subscription guide ↗

Method 4

Use a purpose-built native Mac client.

Native clients turn ntfy streams into Mac notifications without a web runtime. Compare them by setup, authentication, message history, automation, and how closely they follow standard macOS interaction patterns.

Native Mac quick start

Connect NTBX to an HTTPS ntfy topic.

1. Install NTBX and allow notifications. The Mac App Store app requires macOS 14 or later. Launch it and grant notification permission; optionally enable launch at login.
2. Add the server and topic. Use an ntfy.sh topic or a self-hosted URL such as https://ntfy.example.com/builds. You can enter a full topic URL or the server and topic separately.
3. Set authentication if needed. Enter a Bearer token with read access to the topic. NTBX keeps it in Keychain. The sender must separately have publish permission.
4. Publish a test. Set NTFY_TOPIC_URL to the same HTTPS topic URL. For the protected-topic example below, set NTFY_PUBLISH_TOKEN to a token allowed to publish there.

curl --fail --show-error \
  -H "Authorization: Bearer ${NTFY_PUBLISH_TOKEN:?Set a publish token}" \
  -H 'Title: Backup finished' \
  -H 'Priority: 3' \
  --data-binary 'db-01: nightly backup completed' \
  "${NTFY_TOPIC_URL:?Set your HTTPS topic URL}"

For anonymous publishing, omit the Authorization header. On a public ntfy server, anyone who knows an unprotected topic name may be able to read or publish to it. Use your server’s access controls for private alerts.

Confirm the message appears in the NTBX inbox, then check Notification Center. If only the system alert is missing, check macOS notification permission and Focus. If the inbox is empty too, check server reachability, the topic URL, and token permissions.

ntfy publishing and authentication reference →

Connect your existing automation

Send CI and cron results to your Mac.

NTBX is the subscriber. Your automation sends the message to ntfy, so you do not need a separate NTBX API or plugin. For GitHub Actions, add this step after the work you want to report and create the two named repository secrets for your protected topic.

- name: Notify ntfy
  if: ${{ always() }}
  env:
    NTFY_TOPIC_URL: ${{ secrets.NTFY_TOPIC_URL }}
    NTFY_PUBLISH_TOKEN: ${{ secrets.NTFY_PUBLISH_TOKEN }}
    JOB_STATUS: ${{ job.status }}
    RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
  run: |
    curl --fail --show-error --max-time 15 \
      -H "Authorization: Bearer ${NTFY_PUBLISH_TOKEN:?Set a publish token}" \
      -H "Title: CI result" \
      -H "Click: $RUN_URL" \
      --data-binary "Workflow result: $JOB_STATUS" \
      "${NTFY_TOPIC_URL:?Set your HTTPS topic URL}"

The Click header attaches the workflow URL to the ntfy message. NTBX exposes HTTP(S) click links so you can open the related run. Keep secrets in your CI secret store, and choose whether a failed notification request should fail the job for your workflow.

For cron jobs or backup scripts, use the same publishing request after the task completes, with a message describing success or failure. For Uptime Kuma, choose its ntfy provider and configure the same server and topic you subscribe to in NTBX. These are ntfy publishing workflows, not separate native integrations built into NTBX.

Official ntfy examples for GitHub Actions, cron, and Uptime Kuma →

Self-hosted ntfy

Check transport, authentication, and Web Push.

All four approaches can work with a self-hosted ntfy server, but their requirements differ:

• Use HTTPS. NTBX deliberately accepts HTTPS servers only. Other clients may have their own transport rules.
• Plan authentication. Confirm that your chosen client supports the token or credentials required by the topic. NTBX supports anonymous topics and Bearer tokens stored in Keychain.
• Configure Web Push for the PWA. Direct streaming clients do not depend on the PWA's Web Push configuration, while background web delivery does.
• Keep the receiver available. A CLI process, browser, or native app can only deliver messages while its required background component is active.

Recommendation

Choose for the workflow, not the feature count.

Fastest official setup

Use the official App Store app on an Apple Silicon Mac.

Full web interface

Install the PWA and verify the background-delivery behavior for your browser and server.

Maximum scripting control

Use the CLI and own the local notification command and process lifecycle.

Native Mac workflow

Choose a native client based on whether you value simple setup, automation, or richer message features.