Skip to main content

Push notifications

When an agent or conversation stops to wait for you, Overdeck can tell your phone. Your own machine sends the notification. For Web Push and ntfy, no relay and no overdeck.ai service is involved; notifications for the Overdeck app pass through connect.overdeck.ai as ciphertext that only the phone can open.

What you get

A notification for four kinds of item: Each item notifies once, when it first appears. When you answer it and a new question arrives later, that new question notifies again. A dashboard restart does not replay questions or plan approvals that were already waiting a minute before it started. An agent’s permission prompt has no start time, so a restart notifies it again. The default notification says what kind of item it is and where it is, for example Question · Refactor the billing module with the body Tap to answer. It never contains the question text unless you turn on includePreview. At most 6 notifications go out per minute. If more items arrive, Overdeck counts them and sends one summary, such as 3 more items need you, when the minute ends.

How it works

Overdeck uses standard Web Push, the same system web apps use on Android, iPhone and desktop browsers.
  1. VAPID keys. The first time a device subscribes, your machine creates its own VAPID key pair (RFC 8292) at ~/.overdeck/push/vapid.json, file mode 0600. Each push request is signed with it, so the browser’s push service knows the request came from your machine. The key is never rotated or overwritten: every subscription is bound to it.
  2. Subscribing. When you tap Turn on notifications, your browser creates a subscription: an address at its vendor’s push service (Google for Chrome and Android, Apple for Safari and iPhone, Mozilla for Firefox) plus an encryption key that only your device holds. The dashboard stores it in ~/.overdeck/push/subscriptions.json (mode 0600, at most 20 devices).
  3. Encryption. Every notification is encrypted to your device’s key with RFC 8291 (aes128gcm) before it leaves your machine. The push service only forwards ciphertext. The push service and overdeck.ai cannot read the payload; only your phone can decrypt it.
  4. Delivery. Your machine sends the encrypted message straight to the push service, which wakes your phone. Tapping the notification opens the dashboard at the item (/m?subject=<id>), or, for a finished, failed or stopped item about an issue, at the issue sheet (/m/pipeline?issue=<id>); items with no issue open /m.
Overdeck only sends to the Google, Apple, Mozilla and Microsoft push services. A subscription to any other address is refused.

Set up your phone

This covers the browser phone view. If you use the Overdeck app instead, see Phone.
  1. Reach the dashboard over HTTPS. Browsers allow push only on a secure page. http://localhost counts, but a phone needs HTTPS. Select Set up Tailscale in Settings → Anywhere, or run pan tailscale setup. To do it by hand, run this on the machine:
    Then open the https://<machine>.<tailnet>.ts.net address on the phone. See Remote access for how other devices reach the dashboard.
  2. Pair the phone. On the machine, open Settings → Anywhere → Set up a phone → Browser on the phone and follow its steps; see Phone. On iPhone, add the app to the Home Screen first (Safari offers push only to a Home Screen web app, iOS 16.4 or later) and pair inside the installed app, because it cannot use a pairing made in Safari. You can also run pan pair and open its link; see pan pair.
  3. Turn it on. Open Settings → Anywhere → Phone notifications and tap Turn on notifications, then allow notifications when the browser asks. In the browser phone view (/m), the same control is in the banner below the header and in Settings (the gear in the header).
  4. Send a test. Tap Send test. The phone should show Overdeck test notification within a few seconds.

Configuration

Push is on by default; subscribing a device is the opt-in. The block goes in ~/.overdeck/config.yaml. Every key is optional. This is the full block with its defaults (the ntfy part is an example; it is off unless you set it):
The dashboard reads the block on every send, so changes apply without a restart. A bad value never stops the dashboard from starting: invalid entries are ignored, and a bad ntfy setting shows its reason in the Phone notifications panel.

The Overdeck app

Each phone paired with the Overdeck app receives the notifications its own Settings allow, sealed with crypto_box_seal to that phone’s own push key. Your machine sends the sealed notification to connect.overdeck.ai, which forwards the ciphertext to Apple or Google; neither overdeck.ai nor Apple or Google can read it. A notification holds at most 2,256 bytes, so a long body is shortened and ends with …. The machine must be signed in to overdeck.ai and connected to it. Settings → Anywhere → Phone notifications shows the count, such as Overdeck app: 2 phones, and removing a phone from the device list stops its notifications within 5 seconds. To pair a phone, see Phone. The list above that line holds only paired browsers (web push subscriptions), not phones; when none are paired it reads “No browser receives notifications yet.” On iPhone, the app decrypts each notification on the phone and shows its real title and text. If it cannot (for example before the first unlock after a restart), the notification reads Overdeck · Something needs you. Turn notifications on or off in the app’s Settings.

Pause and notification types

In the app’s Settings, below the Notifications switch:
  • Pause notifications is a separate switch from the Notifications switch above it. Turning it on stops every notification except Send test. Pause for 1 hour and Pause until tomorrow 8:00 pick an end time for you; turning the switch off resumes immediately.
  • Notification types lists six switches, one per kind of item: Agent questions, Plan approvals, Permission prompts, Finished work, Failures and Agent stopped responding. They split the “What you get” table above into finer categories: Approval needed splits into Plan approvals and Permission prompts; Failed splits into Failures and Agent stopped responding. Agent questions covers the Question row and Finished work covers the Finished row, each unchanged. Turning a type off stops that one kind of notification; every other kind still arrives. A low-disk-space push (PAN-5093) follows the Failures switch, same as a merge failure.
Your machine applies pause and the muted types before sealing a notification, so a filtered notification never reaches connect.overdeck.ai, Apple or Google at all: it is simply not sent. Send test always arrives, pause or no pause, because it is your own check that the pipe works. A machine only applies settings it has received: it must run a version that supports this feature and be reachable at least once after you change a setting. The app’s Settings lists any paired machine it has not yet reached, so you can tell when a change is still pending. This is separate from the Notifications switch above it: that switch turns this phone’s own registration with overdeck.ai off, so no paired machine can reach it at all. Pause and notification types stay registered and simply filter what each machine sends.

Live Activity (iPhone)

On iOS 16.2 and later, the Overdeck app shows a Live Activity on the lock screen and in the Dynamic Island, such as 3 need you · 2 running. The first number counts the items that need you; the second counts the running agents. With several paired machines, the card shows their sum. iOS draws the card from a push without running the app, so its content cannot be end-to-end encrypted. Apple and overdeck.ai see these two numbers and nothing else: no titles, no conversation text, no machine names.
  • The card is on by default. Turn it off in the app’s Settings → Live Activity. If iOS Settings does not allow Live Activities for Overdeck, the app tells you to turn them on there.
  • Your machine sends the counts whenever it is connected to overdeck.ai, even when notifications are off.
  • The card dims when it has had no update for 10 minutes.
  • iOS ends a Live Activity after at most 8 hours. The card comes back the next time you open the app.

On Android

  • Permission. On Android 13 and later, the app asks for notification permission once, on the first launch after you sign in. If you decline or dismiss the dialog, the app still works; it just does not notify you.
  • Channels. Notifications arrive on two channels. Needs you carries questions, approvals and failures, at high importance. Updates carries finished work, summaries and test notifications, at default importance. You can change each one in Android Settings.
  • Encryption. The phone opens each notification with its own key, so Google cannot read its content. Firebase Cloud Messaging still sees delivery metadata, such as this phone’s registration token, the message priority and when it was sent.
  • When a notification cannot be opened, the phone shows “Overdeck · Something needs you” instead.
  • Tapping a notification opens the machine and the screen it came from. A notification from a machine this phone is no longer paired with opens the machine list. A notification tapped while signed out waits until you sign in. Sign-out removes this phone’s pairings, so it then opens the machine list unless you have paired that machine again.
  • Force stop in Android Settings blocks notifications until you open the app again. Swiping the app away does not.
  • Turning them back on. The app’s Settings screen has a Notifications switch. Turning it on asks Android again when Android still allows it. When you blocked notifications, Settings says “Off. Turn them on in Android Settings → Apps → Overdeck → Notifications.” Open that screen to allow them. A build without a Firebase configuration says “Not set up in this build.”

Optional: ntfy

ntfy is a simple publish-subscribe notification service. Overdeck can publish to an ntfy topic as well as, or instead of, Web Push. An ntfy server sees what you publish in plain text, so Overdeck sends it titles only: the kind plus the issue id, or the words a conversation. A low-disk alert sends its own title, such as Disk low · 3.2 GiB free. Conversation titles, question text and previews never reach ntfy.
  • Treat the topic name as a secret. Anyone who knows it can subscribe to it. Use an unguessable topic, such as deck- followed by 16 or more random characters. The topic must match ^[A-Za-z0-9_-]{1,64}$; anything else shows “topic must match …” in the panel.
  • Use a publish token (token) so nobody else can post to your topic.
  • Prefer a self-hosted server, so the titles never leave your network.
  • Set clickBaseUrl to the HTTPS address of your dashboard if tapping the ntfy notification should open it. url must be an http: or https: address.

Privacy

  • Lock screen. A notification shows on the phone’s lock screen. By default it shows only the kind and the conversation title or issue id, never the question text.
  • includePreview. Turning it on puts the first 140 characters of the question (or the plan’s first line) on the lock screen. It still travels encrypted; only the phone can read it.
  • Revoking a device stops its push. Each subscription remembers the paired device that created it. When you revoke that device (pan devices revoke, or Revoke in Settings → Anywhere), its subscription is deleted before the next send.
  • Removing a subscription. Remove in the Phone notifications panel deletes it. On the device itself, it also unsubscribes the browser.

Recent notifications

Settings → Anywhere → Phone notifications lists the last 50 notifications Overdeck sent, newest first. Each row shows the title, when it went out, how many devices it reached, and why a device failed, if one did. Open goes to the conversation or issue it was about. Overdeck keeps this list in ~/.overdeck/logs/push-sent.jsonl. It starts a new file at 5 MB and keeps the previous one as push-sent.jsonl.1. The file holds each notification’s title and delivery result, never the question text. A question or approval also shows where it stands now:
  • Waiting: it is still in Needs you.
  • Answered: you answered it from Overdeck, on the desktop or the phone.
  • Answered or withdrawn: it left Needs you without an answer sent from Overdeck. You answered it in the terminal, or the agent moved on without one.
Right after the dashboard starts, an older question can show no state for up to a minute, until Overdeck has checked what is still waiting.

Troubleshooting

A notification arrived but Needs you is empty. Open Recent notifications to see what was sent and where the question stands. Answered or withdrawn means it left Needs you before you got to it. If Needs you shows Can't reach <machine>; it may have items waiting., this machine cannot read that linked machine’s list, so open that machine to see its items. There is no Turn on notifications button. The panel explains why in its place:
  • Open this dashboard over HTTPS: the page is not a secure context. Use the Tailscale Serve address, or http://localhost on the machine itself.
  • On iPhone, add Overdeck to your Home Screen: Safari tabs cannot receive push. Install the app and open it from the Home Screen icon.
  • Notifications are blocked for this site: allow notifications for the dashboard’s address in the browser’s site settings.
  • This browser cannot receive push notifications: the browser has no service worker or Push API support (outside iPhone).
The test sends, but nothing arrives. Check the phone’s notification settings for the browser or the installed app, and turn off Focus or Do Not Disturb. On Android, check that battery saving does not restrict the browser. A device disappeared from the list. When a push service answers 404 or 410, the subscription has expired or the browser removed it, so Overdeck deletes it. Tap Turn on notifications on that device again. A device shows failures. The panel shows a failure count for each device. Other 4xx answers and network errors count as failures. Overdeck keeps sending to the device, and a successful send clears the count. If the count keeps growing, select Remove and tap Turn on notifications on that device again. Still stuck? Ask in the Overdeck Discord or open a GitHub issue.