Skip to main content

Quick Start

Set up Reverse Proxy for ntfy from scratch and send your first push notification through Cloudflare Workers.

Prerequisites

Before you begin, make sure you have the following ready:

  • Node.js — v22 or v24 (LTS recommended for stability)
  • npm — v10 or later, which ships with supported Node.js versions
  • Cloudflare account — A free or paid account with a registered domain (Workers and Email Routing are both available on the free plan)
  • ntfy server — At least one self-hosted ntfy instance with token authentication enabled

info

Your ntfy server needs base-url set to its public URL and behind-proxy set to true. If you plan to receive binary attachments (images, files), also configure attachment-cache-dir. See the ntfy self-hosting documentation for details.

Install

Install the package globally to use the nrp command anywhere:

bash
npm install -g ntfy-reverse-proxy

Or run it directly without installing:

bash
npx ntfy-reverse-proxy

Both ntfy-reverse-proxy and nrp are registered as CLI aliases — they do the same thing.

The first command that needs configuration copies the starter template included with the npm package to your platform config directory. Global and npx installs don't require a repository clone or a separately downloaded config.sample.json.

First-Time Setup

The interactive config menu starts from the packaged template and guides you through everything you need for a working deployment.

  1. Run nrp to launch the interactive config menu.
  2. Add at least one ntfy server. Each server needs a name, a URL starting with https://, and a token starting with tk_.
  3. Add at least one context. Choose a name, interpreter, topic, delivery mode, and assign one or more servers.
  4. Update settings. Set the worker_name and base_domain to match your Cloudflare domain.
  5. Run nrp validate from the CLI to check config integrity. Validation also runs automatically as part of the deploy step. This catches missing fields and invalid references before deployment.
  6. Run deploy to generate wrangler.toml and deploy to Cloudflare Workers.

tip

The CLI validates config against its schema on every load. You can also run validation manually with nrp validate or through the interactive menu.

Sending Your First Notification

After deployment, each HTTP context gets a subdomain route in the format {context-id}.{base_domain}. Test it with a simple curl command.

Plain Text Notification

bash
curl -X POST https://{context-id}.ntfy.example.com \
  -H "Content-Type: text/plain" \
  -d "Hello from ntfy-reverse-proxy!"

Authenticated Notification

If the context has a token configured, include the Authorization header:

bash
curl -X POST https://{context-id}.ntfy.example.com \
  -H "Authorization: Bearer your-context-token" \
  -d "Authenticated notification"

Landing Page

GET requests to any context URL return a landing page showing "Reverse Proxy for ntfy" with an operational status badge. When show_response_output is enabled, the page also includes a collapsible section with the full configuration, with sensitive values masked.

If Something Goes Wrong

If deployment fails or notifications are not arriving, check Troubleshooting. Common first-time issues include:

  • Cloudflare's bot protection blocking webhooks (403 errors)
  • DNS propagation delays after deployment
  • ntfy server misconfiguration

What Is Next