Phone Notifications

A banner on your phone when an agent needs input, finishes, or hits an error — the menu-bar flame, for the hours you are not at the desk.

At the Mac, the flame answers the question for you: something is waiting, something went ready, something hit an error, everything else is still working. Away from it, that signal is in another room. Irrlicht Elfdans is the phone half of it — a lock-screen banner on the three transitions that want a human, and nothing else.

Elfdans is not a second dashboard. It is a web app your own relay serves, which you add to your home screen: no App Store listing, no account, no Irrlicht-operated server anywhere in the path. And it is off until you deliberately pair a phone — a Mac with no relay configured behaves exactly as it did before, with no subscription, no service worker installed, and no relay traffic at all.

Tapping a banner takes you to the session it was about — focusing Elfdans if it is already open, or launching it on that session if it is not.

What you need first

This is the part that surprises people: phone notifications need a relay. irrlichtrelay is the standalone fan-out server a daemon can push its session events to — the same one that already lets the macOS app and the web dashboard watch a Mac from somewhere else. Browser push subscriptions and the installed web app are both bound to the origin that served them, so the relay needs one stable HTTPS hostname.

There is no project-run service to sign up for. You host the relay, in one of two shapes.

Setting up the relay

1. Get the binary

   Building from a checkout works everywhere and needs only Go:

   cd core
   go build -o /usr/local/bin/irrlichtrelay ./cmd/irrlichtrelay

   The release build also produces Linux tarballs, irrlichtrelay-linux-amd64.tar.gz and irrlichtrelay-linux-arm64.tar.gz; check the latest release for the version you want and build from source if it is not there yet. If you use a tarball, keep its bin/ and Resources/web/ directories together — the relay finds the dashboard it serves at ../Resources/web relative to the binary, and a lone binary answers 503 on /. A from-source build installs no dashboard at all, so point IRRLICHT_UI_DIR at a copy of platforms/web/; the operator guide below has the details.

2. Serve it over TLS, with auth on

   The usual shape is the relay on loopback behind a TLS-terminating reverse proxy:

   irrlichtrelay serve --addr 127.0.0.1:7839 --auth tokens-file

   The relay can also terminate TLS itself with --tls-cert and --tls-key (both flags are required together).

3. Issue tokens

   One for the daemon, one for the browser you will pair from. Each secret is printed once:

   irrlichtrelay token issue --label "laptop-daemon"
   irrlichtrelay token issue --label "my-browser"

   Run the token subcommand as the same user and IRRLICHT_HOME the relay runs under, so both read one file. A serving relay re-reads it on change, so issuing and revoking need no restart.

4. Point the daemon at it

   Either set IRRLICHT_RELAY_URL and IRRLICHT_RELAY_TOKEN (see Configuration), or enter the URL and token under Settings → Sources in the macOS app or the dashboard. The daemon dials out, so it needs no inbound port and works behind NAT.

5. Open the dashboard the relay serves

   Browse to the relay’s own HTTPS address and enter the browser token under Settings → Sources there. This matters: the pairing endpoints are same-origin, so the Elfdans section appears on the page the relay served — not on the daemon’s local dashboard at 127.0.0.1:7837, which has no push endpoints to offer.

This page stops where the operational detail starts. Reverse-proxy configs, the systemd unit, the launchd agent for a relay on the Mac, and the Oracle Cloud specifics — its firewall is two gates and the console shows you one; it reclaims idle instances, and a relay is the idle profile by construction — all live in the operator guide, examples/relay/DEPLOY.md. The wire protocol and the push REST surface are in docs/relay-protocol.md.

Pairing a phone

Pairing happens once per phone. After it, daily use needs no gestures at all.

1. On the Mac: mint a code

   In the dashboard the relay serves, open Settings and find Irrlicht Elfdans, then press Pair a phone…. You get an eight-character code shown as XXXX-XXXX, with a countdown beside it. Its alphabet leaves out the characters that misread when they are typed from a screen — no I, L, O, U, 0 or 1 — so there is nothing to guess at.

   If the section offers a code box but no button to mint one, the relay token is not entered under Settings → Sources on that page — minting needs an authenticated client, because the code inherits its workspace from that token.

2. On the phone: open the same URL

   Type the relay’s address into the phone’s browser. There is no QR code yet — the URL and the eight characters are what you carry across.

3. Add to Home Screen, then open it from there

   Use the browser’s share menu to add the page to the home screen, close the tab, and launch Elfdans from the new icon.

4. Inside the installed app: type the code

   Open Settings → Irrlicht Elfdans again — this time it offers a code field — enter the code, press Pair this phone, and allow notifications when the phone asks.

Declining the notification prompt does not spend the code: Elfdans asks the phone before it asks the relay, so you can turn notifications on in the phone’s settings and press Pair this phone again with the same code.

Redeeming a code issues an ordinary bearer token for that phone, which is why un-pairing needs no separate machinery — the phone shows up in irrlichtrelay token list like any other client. Once paired, the Elfdans section on the phone turns into a delivery-health line and an Unpair button.

What actually buzzes

Elfdans is deliberately quiet: ten agents flapping for a minute must not mean ten buzzes. The relay decides what to send, with these defaults.

Each notification also carries a lifetime, which bounds how long the push service holds it for a phone that is off: an hour for waiting, ten minutes for ready and for the daemon banners. A question that was asked an hour ago is still a question; a ready from an hour ago is noise.

Every phone paired through the same relay workspace — the isolation unit a token belongs to — receives the same notifications. Filtering per phone or per project, “this phone only wants project X”, does not exist yet.

What Apple and Google can see

The accurate line is: nothing readable leaves your infrastructure. Not “nothing leaves your machine” — the relay is part of the path, and it is yours.

Timing is a named, accepted leak. Whoever carries the pushes learns when your agents need you, which is a work-rhythm signal. Batching would hide it and ruin the feature, so it is weighed and accepted rather than mitigated — it belongs on this page rather than in a footnote nobody reads.

One more, for the same reason: an attacker who reads the relay’s data directory gets no session content and no usable bearer tokens, which are stored hashed. What they do get is the signing key and the subscription registry, and those two together let them send arbitrary notifications to your paired phones until you pair them again.

When it breaks

Start with the health line. Open Elfdans on the phone: the Irrlicht Elfdans section reads something like “Push registered via web.push.apple.com — last delivery at 14:32 succeeded”, or names the failure instead. Delivery health lives only in the relay’s memory, so shortly after a relay restart it says “no delivery attempted since the relay started” — that is honesty about not knowing, not a report that something failed.

It repairs itself where it can. Opening the app re-subscribes when the phone’s subscription has died (iOS invalidates them silently after long idle periods) and re-registers when the relay lost its record of this phone. The token issued at pairing is the durable identity; the subscription is only a delivery address, which is why re-registering is enough.

Un-pairing, from either end. The Unpair button removes the delivery address on the relay, drops the subscription on the phone, and forgets the token locally — the token record itself stays in token list until you revoke it. From the relay side, irrlichtrelay token revoke <id> is the whole story: the phone’s stream access closes with WebSocket code 4401, and its stored subscription resolves to no workspace, so it receives nothing further. The app then says it is no longer paired and offers to pair again.

Nothing arrives at all. Check, in this order:

• Send a test notification, from the button under the health line. It sends one push down the same path a real notification takes and tells you what came back, so it splits the problem in two: a banner means delivery is fine and the fault is between your agents and the relay, while a named failure (“the push service answered 403”, “this phone’s subscription no longer exists”) is the answer itself. If it arrives, the checks below are where to look next; if it does not, the sentence it prints is already the diagnosis.
• curl https://<your-relay>/api/v1/push/info — it should answer {"enabled":true,…}. An enabled:false names its own reason, and the usual reason is a relay running with --auth off.
• The connection-status tooltip in the dashboard — if the daemon is not connected to the relay, there are no transitions to notify about. A daemon that was connected and then dropped becomes a banner of its own after 60 seconds; one that never connected is simply absent, and nothing will arrive.
• What the sessions actually did. A session that never left working is not a missed notification.

Keep the relay’s four files. The relay’s data directory holds tokens.json, vapid-keys.json, push-subscriptions.json and daemon-roster.json, all mode 0600. Copy those and keep the hostname, and every paired phone survives a host rebuild untouched. No session content is ever written to the relay host — before this feature or after it.