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. 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
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 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.
• One log line per request, with the route, the outcome, Apple's response and how long it took. The line never contains the push token, the pass, the envelope or the tag.
• 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 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.

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 → Locations → This Mac → Paired devices.
• 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 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 two small things: a sealed envelope of exactly 2,085 bytes per notification, 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.