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.- 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. - 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). - 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. - 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.
Set up your phone
This covers the browser phone view. If you use the Overdeck app instead, see Phone.-
Reach the dashboard over HTTPS. Browsers allow push only on a secure
page.
http://localhostcounts, but a phone needs HTTPS. Select Set up Tailscale in Settings → Anywhere, or runpan tailscale setup. To do it by hand, run this on the machine:Then open thehttps://<machine>.<tailnet>.ts.netaddress on the phone. See Remote access for how other devices reach the dashboard. -
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 pairand open its link; seepan pair. -
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). -
Send a test. Tap Send test. The phone should show
Overdeck test notificationwithin 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 withcrypto_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.
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 as3 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 wordsa 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
clickBaseUrlto the HTTPS address of your dashboard if tapping the ntfy notification should open it.urlmust be anhttp:orhttps: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.
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 showsCan'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://localhoston 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).
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.