> ## Documentation Index
> Fetch the complete documentation index at: https://panopticon-cli.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Push notifications: get alerted when an agent needs you

> Get a phone notification when an agent or conversation needs you, sent by your own machine with end-to-end encrypted Web Push and an optional ntfy topic

# 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:

| Kind | When it fires |
| - | - |
| **Question** | An agent or conversation asks an AskUserQuestion, or a `pan ask` decision is waiting for you. |
| **Approval needed** | A plan waits for approval, or a permission prompt waits in an agent or conversation. |
| **Finished** | A work agent ran `pan done` (verification started), or an issue merged. |
| **Failed** | An agent stopped responding, a merge failed, a stalled review escalated, a conflict repair escalated, or free disk space dropped below the alert level (5 GiB by default, `resources.disk_warn_gb`) or the critical level (2 GiB by default, `resources.disk_critical_gb`). An agent that ended normally, such as a planning agent after its plan is finalized, does not notify. |

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](https://panopticon-cli.com/configuration/phone.md#overdeck-app).

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:

   ```bash theme={null}
   tailscale serve --bg 3011
   ```

   Then open the `https://<machine>.<tailnet>.ts.net` address on the phone. See
   [Remote access](https://panopticon-cli.com/configuration/remote-access.md) 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](https://panopticon-cli.com/configuration/phone.md). 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`](https://panopticon-cli.com/cli/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):

```yaml theme={null}
push:
  enabled: true            # default true; subscribing a phone is the opt-in
  events: [question, approval, finished, failed]   # default: all four
  includePreview: false    # default false
  webpush:
    subject: https://overdeck.ai   # default; must be an https: or mailto: URL
  ntfy:                    # optional; active only when url AND topic are set
    url: https://ntfy.example.net
    topic: deck-k3J9xQ2mV7pL4sTa
    token: tk_...          # optional bearer token for publishing
    clickBaseUrl: https://desk.tailnet.ts.net   # optional; tapping opens this dashboard
```

| Key | Default | Effect |
| - | - | - |
| `enabled` | `true` | `false` stops every push except **Send test**, and stops the conversation scan. |
| `events` | all four | Which kinds notify. Unknown entries are ignored. |
| `includePreview` | `false` | Adds the first question text (or the plan's first line), cut to 140 characters, to Web Push and Overdeck app notifications. Never sent to ntfy. |
| `webpush.subject` | `https://overdeck.ai` | The VAPID contact URL. Apple rejects values that are not `https:` or `mailto:`. |
| `ntfy.*` | off | See below. |

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](https://panopticon-cli.com/configuration/phone.md).

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](https://ntfy.sh) 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](https://discord.gg/ZpHE2ZTv5P) or open a
[GitHub issue](https://github.com/eltmon/overdeck/issues).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.