Self-hosted ntfy on macOS: forward Notification Center alerts with Bearer token or Basic auth

Why run a self-hosted ntfy server for macOS notifications?

The public ntfy.sh service is the fastest way to test Mac-to-iPhone forwarding, because it requires no account or server setup. However, many Mac developers switch to a self-hosted ntfy instance (running in Docker, on a home server, or on a small VPS) for three practical reasons:

1. Create a scoped ntfy Bearer token or Basic auth user

On your self-hosted ntfy server, enable access control in /etc/ntfy/server.yml and create a dedicated user and tk_... access token for your Mac so you can revoke it independently of your phone:

# On your self-hosted ntfy server (Docker or ntfy serve)
# 1. Restrict default access in /etc/ntfy/server.yml:
#    base-url: "https://ntfy.example.com"
#    auth-file: "/var/lib/ntfy/user.db"
#    auth-default-access: "deny-all"

# 2. Create a user and grant write/read access to your Mac topic:
ntfy user add mac-forwarder
ntfy access mac-forwarder mac-alerts rw

# 3. Mint a dedicated Bearer access token (tk_...) for your Mac:
ntfy token add --label="MacBook Pro NotiFerry" mac-forwarder

For reliable background wakeups on iOS when the iPhone screen is locked, also set upstream-base-url: "https://ntfy.sh" in your server.yml, as documented in the ntfy iOS instant notifications guide. That setting sends a lightweight poll-request hash through Apple Push Notification service (APNs) so the iPhone ntfy app wakes up and fetches the actual message payload directly from your private server.

You can verify your server URL and token from macOS Terminal before configuring any app:

# Test publishing from macOS Terminal with your Bearer token
curl -H "Authorization: Bearer tk_your_secret_token" \
  -H "Title: Xcode" \
  -d "Archive succeeded" \
  https://ntfy.example.com/mac-alerts

2. Connect NotiFerry to your self-hosted HTTPS server

NotiFerry supports custom self-hosted ntfy servers out of the box in Settings → Connection:

1. Server URL: Enter your full HTTPS base URL (for example, https://ntfy.example.com or your Tailscale https://machine.tailnet.ts.net URL). NotiFerry enforces HTTPS and rejects credentials embedded inside the URL string.
2. Authentication: Select Access token (sends Authorization: Bearer tk_...) or Username & password (sends HTTP Basic Authorization). NotiFerry stores the secret in macOS Keychain—never in plain-text preference files or diagnostic exports.
3. Secret topic: Keep the generated random topic or enter the topic name you authorized with ntfy access, then click Save connection.
4. Confirm the phone test: Click Send test and confirm I saw it on my iPhone once the alert arrives in the iOS ntfy app.

Once connected, NotiFerry reads new entries from the macOS Notification Center SQLite database using a single read-only folder bookmark (no Full Disk Access), applies your chosen privacy mode (Full notification, Title only, or Generic alert) and per-app block list locally on the Mac, and publishes matching alerts to your self-hosted server.