Push notifications: what the relay sees and keeps

The atrium iOS app can notify you when an agent asks for permission, has a question, or finishes, even when the app is closed. It can also show a Live Activity with what your agents are doing. Notifications are optional, and the app offers them only once it's paired with at least one machine. On this page, "phone" also means an iPad running atrium.

When you turn on notifications, your phone and each Mac you've paired agree on a notification key over the encrypted connection they already share. Only public halves are exchanged, so the key itself never travels over any network, and only those two devices hold it. When an agent needs you and you aren't using atrium on your phone or on your Mac, the Mac seals the notification with that key and hands the sealed envelope to atrium's push relay. The relay passes it to Apple, Apple delivers it to your phone, and atrium opens it there.

How a notification reaches your phone

1. Your phone and your Mac agree on a key. They exchange only public halves, over the encrypted connection between them, so the key never travels. Each paired Mac gets its own key.
2. Your Mac seals the notification. It encrypts the details (the agent, project, command or message), pads them to a fixed size, and sends the sealed envelope to the relay along with the delivery pass your phone gave it.
3. The relay hands it to Apple. It checks the delivery pass, then forwards the envelope to Apple's push service (APNs) with the same priority and expiry as every other notification. It keeps no copy.
4. Your phone opens it. Apple delivers the envelope, and atrium on your phone decrypts it and shows the real title and text.

What the relay receives

What	Why	Stored by the relay
Your phone's Apple push token	Tells Apple which phone to wake	No
The sealed envelope, always exactly 2,085 bytes	The notification itself, which the relay can't read	No
A session tag	Lets a newer notification about the same session replace the older one	No
A key identifier	Tells your phone which key opens the envelope	No
A delivery pass	Proves your phone agreed to receive notifications	No
Your device's Live Activity push tokens	Tell Apple which activity to start or update	No
The sealed activity state, always exactly 2,085 bytes	What the Live Activity shows, which the relay can't read	No
Whether a push starts, updates or ends an activity, and when an ended one leaves the Lock Screen	Apple requires these in the clear	No
Whether a Live Activity push alerts	Decides whether it carries the neutral alert, and its priority	No
Network address, user agent and time	Part of every request on the internet	No; Vercel's request logs keep them for about a day

What the relay keeps

• No database. It doesn't store push tokens, delivery passes, notifications, Live Activity states or tags.
• Rate-limit counters. Requests are counted per network address, and per phone using a one-way hash of the push token, in windows of ten minutes or less. Live Activity pushes are also counted per Live Activity push token, including the one that lets a Mac start an activity, using a one-way hash of that token, and per delivery pass, using the hash of your phone's push token.
• One log line per request, with the route (delivery pass, notification, Live Activity or health check), the outcome, Apple's response, how many tries it took, why a rate-limit check failed if one did, the kind of any internal error, and how long it took. The line never contains a push token, the pass, the envelope, the activity state or the tag, and doesn't say whether a Live Activity push starts, updates or ends an activity.
• Vercel's request logs. Vercel, which hosts the relay, logs the time, the requesting IP address, the user agent, the path and the result of each request, and keeps them for about a day. The relay keeps push tokens out of its own log lines, but a push token may still appear in those hosting logs; if it does, it's deleted with them.

The relay has no user accounts and is not used for analytics or advertising.

What the relay can work out

The relay can't read the agent, the project, the command or the message. Every notification envelope is padded to the same size and sent with the same priority and expiry, so it can't tell a permission request from a "finished". What it can see:

• Which phone, when and how often. The push token and the timing of every notification.
• Same-session grouping. Two notifications about the same session carry the same tag, so the relay can tell they're related without learning which session.
• Same-Mac grouping. Every notification one Mac sends your phone carries the same key identifier, so the relay can tell which notifications came from the same Mac.
• Where requests come from. The network address of the Mac or phone making each request.

Live Activities

When agents are running and you're away from atrium on all of your devices, the app can show a Live Activity on your Lock Screen, and in the Dynamic Island on iPhone: how many agents are working, which one needs you, and Allow and Deny for a permission request. Each paired Mac keeps its own activity on each of your devices.

• Sealed like notifications. Your Mac seals what the activity shows with the same notification key and pads it to the same 2,085 bytes. Your phone or iPad opens it; the relay can't read the agent, project, room, command or message.
• Answers don't go through the relay. Allow and Deny on a Live Activity go straight from your device to your Mac over your network or tailnet, the same way the buttons on a notification do. Apple requires the device to be unlocked before a Live Activity's buttons act.
• What the relay additionally sees: your device's Live Activity push tokens, whether each push starts, updates or ends an activity, whether it alerts, and when an ended activity should leave your Lock Screen. It keeps none of it, apart from the rate-limit counters above, which use one-way hashes of the tokens.
• Alerts. While an activity is up, the alerts you'd have had as notifications arrive as activity updates instead, on the same events and with the same neutral text. Every start carries that neutral alert too, because Apple requires an alert to start an activity, so a start can light up your screen. A start that isn't itself one of those alerts carries no sound; whether iOS then keeps it silent is still being verified.
• Priority. Updates that don't alert are new traffic, sent at Apple's lower priority (5); starts, ends and updates that alert go at the same priority as notifications (10). The priority tells the relay nothing it doesn't already see in the request: whether a push starts, updates or ends an activity, and whether it alerts.
• What the timing shows. The relay can see how often your Mac updates an activity, and the spacing of updates can hint at what kind of change happened, though not what it was. An activity that ends with its summary left up tells the relay your agents finished while you were away; one removed at once usually tells it you came back.
• When you come and go. Because a Mac starts an activity when you step away while agents are running and ends it as soon as you're back, the relay can tell when you leave and return to that Mac during a run.
• Turning them off: iOS Settings → atrium → Live Activities, or swipe the activity away. Turning off notifications in the app turns off the activities your Macs start, too.

Delivery passes

A Mac can send your phone notifications only while it holds a delivery pass from your phone.

• Every few days, while atrium is open, your phone asks the relay for a new pass. The relay sends it back only through Apple, to your phone, never in its reply, so nobody else can get one.
• Your phone hands passes only to the Macs you still have paired, when it connects to them. Each pass expires after 14 days.
• If your phone hasn't reached a Mac for 14 days, that Mac pauses its notifications until you open atrium where your phone can reach it.
• You may occasionally see a quiet "Notifications are on." line in Notification Center. That's a delivery pass that arrived just after you left the app. It's harmless, and you can clear it. A Mac you paired in the past that still has your push token could also cause one, but never more than one at a time.

When your Mac sends a notification

Your Mac holds notifications while you're using atrium anywhere: on your phone, on your iPad, or on the Mac itself. Using atrium on one of your devices holds notifications to all of them.

• On your phone or iPad. While atrium is open on one, it tells each connected Mac that you're there, so no Mac pushes to any of your devices. Notifications resume about 30 seconds after you leave the app.
• On your Mac. The desktop app notes the last time you clicked, typed, scrolled or moved the mouse in one of atrium's own windows. Input in other apps doesn't count, and neither do timers or agent output. That time stays on the Mac and is never sent anywhere.
• Permission requests and questions wait while you've used atrium, on any of your devices, in the last 30 seconds. If one is still waiting once you've been away from all of them for 30 seconds, it's sent.
• "Agent finished" and errors count as seen if you used atrium, on the Mac or in the app, after they happened, and aren't sent. "Agent finished" notifications are on by default; you can turn them off in the app under Settings → Notifications.

Turning notifications off

• In the app: Settings → Notifications, for every Mac or one at a time.
• In iOS: Settings → Notifications → atrium.
• On your Mac, for one device: Settings → Remote access → Phones & tablets.
• Revoking your phone on a Mac stops that Mac's notifications immediately.
• Removing a Mac from your phone deletes that Mac's key on your phone right away, and on the Mac too if it's reachable. A Mac that can't be reached may keep sending for up to 14 days, until its last delivery pass expires. Your phone can't open those notifications, so they may show up as a generic "New activity from your agents" alert.
• Removing your last Mac turns push notifications off, and the app deletes its push token, delivery pass and keys.

The connection between your phone and your machine

The iOS app connects directly to the machines you pair it with, over your own network or your tailnet. Apart from the sealed notifications and sealed Live Activity states described above, nothing you see in the app goes through an atrium server.

• Encrypted with TLS 1.3. The connection is encrypted on your local network and on your tailnet alike. On a tailnet, Tailscale's own encryption wraps it as well.
• Pinned to your machine's key. The pairing code carries a fingerprint of the machine's key. Your phone accepts only that key and never falls back to an unencrypted connection, so another device on your network can't read the traffic or pose as your machine.
• Notification setup uses only this connection. Your phone registers for notifications with a Mac only over the encrypted connection, so the push token, the delivery pass and the key exchange never cross your network in the clear.
• Phones paired before encryption learn the machine's key the first time they connect after you update atrium on both sides, and use only encrypted connections from then on. That first step trusts your network at that moment; pairing again with a fresh code from the machine avoids relying on it.
• Older versions of the iOS app connect without encryption. For one release, your machine still accepts them, so they keep working until you update. A phone that has moved to the encrypted connection is never accepted unencrypted again.

What the relay is not

It isn't a network relay. Conversations, terminals, approvals and transcripts travel only directly between your phone and your machine. The relay carries three small things: a sealed envelope of exactly 2,085 bytes per notification, a sealed Live Activity state of the same size per activity push, and a delivery pass every few days. It exists for one reason: Apple delivers notifications to iPhones and iPads only from a sender holding the app's APNs key, and that key can't ship inside the desktop app.

Contact

See the privacy policy for the full terms. If you see behavior that surprises you, open an issue and we will investigate.