Skip to content
Back to search

kukuroo

MarketplaceWorks with Claude CodeGitHub

Self-hosted Web Push on a Cloudflare Worker: iOS and macOS notifications with no server to keep alive, no vendor, and no native app. Safari only, via Declarative Web Push.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/saiday--kukuroo/badge.svg)](/listings/saiday--kukuroo)

HTML

<a href="/listings/saiday--kukuroo"><img src="/api/listings/saiday--kukuroo/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

npx kukuroo init my-push

It asks a few questions, writes a Worker into `my-push`, generates and uploads every secret, and deploys. One answer is irreversible: where devices enroll, a `workers.dev` address or a domain you have on Cloudflare, fixed once a device has enrolled. Back up `my-push/kukuroo.credentials.json`, the only copy of your keys.

On the device: open that origin in Safari, **Add to Home Screen**, and open it **from the icon** to allow notifications. A Safari tab does not work on iOS; [the enrollment guide](docs/create-pwa-and-subscribe-to-push.md) has the rest. From then on, a notification is one request:

curl -X POST https://push.example.com/push/send \
  -H "authorization: Bearer $SEND_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"notification":{"title":"hello","navigate":"https://push.example.com/"}}'

That is Kukuroo standalone: its own Worker at its own address, serving the enrollment page it ships with. Your own site needs nothing but the send token and that POST. Answering **no** to the bundled front end keeps the same shape but routes no enrollment page, so you serve your own UI and add its origin to `KUKUROO_ALLOWED_ORIGINS`.

Every question also has a flag, including `--no-deploy` and `--resume` for setting things up before touching your Cloudflare account, and `rotate` for the send token and the invite code: [`npx kukuroo init --help`](scripts/init.mjs).

Mounting it in a Worker you already run

Mounted instead of standalone: the push routes live inside a Worker you already have, so they share your site's origin and a notification click lands back inside your site.

import { mountKukuroo, type KukurooEnv } from "kukuroo";

const kukuroo = mountKukuroo({ prefix: "/push", standalone: false, requireInvite: true });

export default {
  async fetch(request: Request, env: KukurooEnv): Promise<Response> {
    const hit = await kukuroo.handle(request, env);
    if (hit !== null) return hit;
    return yourExistingRouter(request, env);
  },
};

`handle` returns `null` for every path outside `prefix`, so your own routing is untouched. Add the KV binding, `"kv_namespaces": [{ "binding": "KUKUROO_SUBS" }]`, whose name is not configurable; set `KUKUROO_NAVIGATE_ORIGIN`; then run `npx kukuroo init --secrets` from the directory holding that `wrangler.jsonc`. Serve the bundled page from any route of yours with the exported `enrollmentPage()`, or build your own UI against `POST /push/subscribe`.

From inside that Worker, `send(env, options)` sends a notification with no token, since it already holds the bindings. [`KukurooEnv`](src/env.ts), [`MountOptions`](src/mount.ts), and [`SendOptions` and `SendResult`](src/send.ts) are documented where they are declared; `requireInvite: false` is the one to read before setting, since it opens enrollment to anyone who reaches the URL. `buildDeclarativePayload` and `importVapidKeys` are exported too.

Kukuroo ships TypeScript source rather than a build, so your `tsconfig.json` needs `"allowImportingTsExtensions": true` or `tsc` reports errors from inside `node_modules/kukuroo`. The scaffolded project sets this already.

Enrollment can also reach your own hostname through a Worker route or a real proxy that rewrites `Host`; a bare DNS CNAME will not do. All that matters is which origin devices enroll on.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 15 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "$schema": "https://code.claude.com/schemas/marketplace.json",
  3. "name": "kukuroo",
  4. "owner": {
  5. "name": "Saiday",
  6. "url": "https://github.com/saiday/kukuroo"
  7. },
  8. "plugins": [
  9. {
  10. "name": "kukuroo",
  11. "source": "./",
  12. "description": "Notify the user on their own phone, through their own Kukuroo Worker"
  13. }
  14. ]
  15. }
README.md · README · 140 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Kukuroo
  2. Your own Web Push service, on a Cloudflare Worker.
  3. There is no server to keep alive, no notification vendor in the path, and no app to install:
  4. you hold the keys, and the push service relays ciphertext it cannot read.
  5. Kukuroo uses **Declarative Web Push**, which so far has only shipped in Safari, so receiving
  6. needs an iPhone or iPad on iOS 18.4+, or macOS Safari 18.5+. Chrome, Firefox, and Android
  7. cannot enroll. Sending works from anything that can make a request: curl, cron, CI, or a
  8. backend you already run.
  9. ## Install
  10. ```sh
  11. npx kukuroo init my-push
  12. ```
  13. It asks a few questions, writes a Worker into `my-push`, generates and uploads every secret,
  14. and deploys. One answer is irreversible: where devices enroll, a `workers.dev` address or a
  15. domain you have on Cloudflare, fixed once a device has enrolled. Back up
  16. `my-push/kukuroo.credentials.json`, the only copy of your keys.
  17. On the device: open that origin in Safari, **Add to Home Screen**, and open it **from the
  18. icon** to allow notifications. A Safari tab does not work on iOS; [the enrollment
  19. guide](docs/create-pwa-and-subscribe-to-push.md) has the rest. From then on, a notification
  20. is one request:
  21. ```sh
  22. curl -X POST https://push.example.com/push/send \
  23. -H "authorization: Bearer $SEND_TOKEN" \
  24. -H 'content-type: application/json' \
  25. -d '{"notification":{"title":"hello","navigate":"https://push.example.com/"}}'
  26. ```
  27. That is Kukuroo standalone: its own Worker at its own address, serving the enrollment page
  28. it ships with. Your own site needs nothing but the send token and that POST. Answering
  29. **no** to the bundled front end keeps the same shape but routes no enrollment page, so you
  30. serve your own UI and add its origin to `KUKUROO_ALLOWED_ORIGINS`.
  31. Every question also has a flag, including `--no-deploy` and `--resume` for setting things up
  32. before touching your Cloudflare account, and `rotate` for the send token and the invite code:
  33. [`npx kukuroo init --help`](scripts/init.mjs).
  34. ### Mounting it in a Worker you already run
  35. Mounted instead of standalone: the push routes live inside a Worker you already have, so
  36. they share your site's origin and a notification click lands back inside your site.
  37. ```ts
  38. import { mountKukuroo, type KukurooEnv } from "kukuroo";
  39. const kukuroo = mountKukuroo({ prefix: "/push", standalone: false, requireInvite: true });
  40. export default {
  41. async fetch(request: Request, env: KukurooEnv): Promise<Response> {
  42. const hit = await kukuroo.handle(request, env);
  43. if (hit !== null) return hit;
  44. return yourExistingRouter(request, env);
  45. },
  46. };
  47. ```
  48. `handle` returns `null` for every path outside `prefix`, so your own routing is untouched.
  49. Add the KV binding, `"kv_namespaces": [{ "binding": "KUKUROO_SUBS" }]`, whose name is not
  50. configurable; set `KUKUROO_NAVIGATE_ORIGIN`; then run `npx kukuroo init --secrets` from the
  51. directory holding that `wrangler.jsonc`. Serve the bundled page from any route of yours with
  52. the exported `enrollmentPage()`, or build your own UI against `POST /push/subscribe`.
  53. From inside that Worker, `send(env, options)` sends a notification with no token, since it
  54. already holds the bindings. [`KukurooEnv`](src/env.ts), [`MountOptions`](src/mount.ts), and
  55. [`SendOptions` and `SendResult`](src/send.ts) are documented where they are declared;
  56. `requireInvite: false` is the one to read before setting, since it opens enrollment to
  57. anyone who reaches the URL. `buildDeclarativePayload` and `importVapidKeys` are exported too.
  58. Kukuroo ships TypeScript source rather than a build, so your `tsconfig.json` needs
  59. `"allowImportingTsExtensions": true` or `tsc` reports errors from inside
  60. `node_modules/kukuroo`. The scaffolded project sets this already.
  61. Enrollment can also reach your own hostname through a Worker route or a real proxy that
  62. rewrites `Host`; a bare DNS CNAME will not do. All that matters is which origin devices
  63. enroll on.
  64. ## Agent Skill
  65. Your coding agent can send these, which is most of the point of having a phone in the
  66. loop. For Claude Code that is a plugin, and this repository is its own marketplace:
  67. ```sh
  68. claude plugin marketplace add saiday/kukuroo
  69. claude plugin install kukuroo@kukuroo
  70. ```
  71. Set the environment up once per machine:
  72. ```sh
  73. /kukuroo:kukuroo-setup
  74. ```
  75. From then on "ping me on my phone when the tests finish" works in any project.
  76. [The agents guide](docs/agents.md) covers the rest: what makes it fire, what it is told
  77. about the payload, and why a scheduled push needs the session to stay open.
  78. ## API
  79. ```
  80. POST /push/send bearer token RFC 8291 aes128gcm + VAPID ES256, fans out
  81. POST /push/subscribe invite-gated stores the subscription in KV
  82. GET /push/public-key open the VAPID public key, for the client
  83. GET /push/enroll open the bundled enrollment page (standalone only)
  84. ```
  85. `/push/send` takes the notification:
  86. ```sh
  87. curl -X POST https://push.example.com/push/send \
  88. -H "authorization: Bearer $SEND_TOKEN" \
  89. -H 'content-type: application/json' \
  90. -d '{"notification":{"title":"Deploy finished","body":"api v2.3.1 is live","tag":"deploys","navigate":"https://push.example.com/deploys"}}'
  91. ```
  92. `title` and `navigate` are required, and `icon`, if present, must be absolute.
  93. ## Alternatives
  94. | | Server to run | Vendor in the path | How it reaches iOS |
  95. |---|---|---|---|
  96. | **Kukuroo** | none | none | [Declarative Web Push](https://webkit.org/blog/16535/meet-declarative-web-push/), a page on your Home Screen |
  97. | [ntfy](https://ntfy.sh) | host, domain, TLS, a process | none, self-hosted | Web Push, installable PWA |
  98. | [Bark](https://github.com/Finb/Bark) | yes, though it can be a Worker | none | App Store app via APNs |
  99. | [Gotify](https://gotify.net) | yes | none | its own app |
  100. | [Pushover](https://pushover.net) | none | yes, paid hosted | its own app |
  101. If you are happy hosting and want a full app-like UI, use ntfy. It is mature, polished, and
  102. does considerably more than this.
  103. ## Licence
  104. MIT. See [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.