Kukuroo: self-hosted web push worker for iOS

A push endpoint you own, in one Cloudflare Worker.

• Notifications you have to act on should not be buried in a Telegram channel, a Discord server, or email.
• The other way onto a lock screen is shipping a native app whose only job is that one line.

No server to keep alive.

A Worker and a KV namespace. Nothing to host, renew, or restart at 3am.

No company in the middle.

Your keys stay in your Worker, and the payload is encrypted to the device. Nobody's dashboard sees your alerts.

No app to build.

iOS has rendered these natively since 18.4. No App Store, no $99 a year for four words on a lock screen.

Send a push notification in seconds

From the agent you left running, the moment it finishes or stops to ask. From cron, CI, a Raspberry Pi, your backend, a shell alias. Anything that can make an HTTP call can ring your phone.

bash

$ curl -X POST https://push.example.com/push/send \ -H "authorization: Bearer $KUKUROO_SEND_TOKEN" \ -d '{"notification":{"title":"Task W13 finished", "body":"W14 is unblocked and ready to start", "navigate":"https://push.example.com/"}}' {"delivered":1,"removed":0,"failures":[]}

One-Click Integration

Setup takes less than a minute. One command writes the Worker, generates every key, installs them, provisions storage, and deploys.

bash

$ npx kukuroo init my-push

That's it. You now have a push server of your own. Open the printed URL in Safari on your iPhone, Add to Home Screen, and open it from the icon. Apple's rule, once per device.

Already have a Worker running as your website?

Then Kukuroo mounts into the router you already have, rather than asking for a Worker of its own. Devices enroll on your hostname, which is where a notification tap should land.

The mounted setup, step by step →

Prerequisites

Kukuroo supports a short list, on purpose:

• Cloudflare Workers. The only place it runs. No Docker image, no binary, no other host.
• Safari. Declarative Web Push has shipped nowhere else yet. Other browsers are turned away at the enrollment page rather than left half working.
• iOS 18.4 or later, with the page on your Home Screen and opened from the icon. A Safari tab will not do, and that is Apple's rule rather than ours. macOS Safari 18.5 receives too, if you can think of a reason to want it.
• A Cloudflare account. Push and Workers suit each other unusually well, and the free plan carries a personal setup without noticing: 50 devices per send, 100,000 requests a day. If it ever grows past you, $5 a month takes that to 10,000 devices per send and 10 million requests.