Background Wake

Why this matters

Multipeer Connectivity, the framework RemoteSignerPhone uses to talk to paired Macs and Vision Pros, is a foreground-friendly transport. iOS aggressively suspends apps that have been backgrounded for more than a few seconds, and a suspended app cannot maintain a Multipeer session or respond to incoming signing requests. If the only way to reach your iPhone-held SSH keys was "wake up the iPhone, find RemoteSignerPhone, foreground it, then try ssh," the system would be unusable.

The fix is Apple Push Notification Service (APNs). vmuxAgent on the Mac owns the iPhone's APNs device token and sends a silent push every time it needs to reach the iPhone for signing. iOS delivers the push in milliseconds; RemoteSignerPhone wakes briefly in the background, restarts Multipeer advertising, and is ready to accept the impending sign request.

The whole flow is invisible from your perspective. You type ssh on the Mac, the Mac pushes the iPhone, the iPhone wakes silently, vmuxAgent connects, the iPhone shows a Sign Request notification, you Face ID, and the connection completes. Lockscreen, sleep, even closed-pocket — none of that prevents the round trip.

Notification permissions

On first launch, RemoteSignerPhone requests authorization for alert, sound, and badge. Allow this. The same permission grant covers two distinct uses:

If you denied the prompt, you can re-enable from Settings → Notifications → RemoteSigner. Make sure Allow Notifications and Time Sensitive Notifications are both on. Without notifications, you will miss sign-request alerts when the app is not foregrounded — and silent push delivery will degrade because iOS uses notification permission as one signal in its push throttling decisions.

Registering the APNs device token

When RemoteSignerPhone launches, it asks iOS to register for remote notifications. iOS contacts Apple's APNs servers (over Apple's hardened internet path) and issues a per-app, per-device, opaque token. The token looks like a 64-character hex string. RemoteSignerPhone displays the first sixteen characters on the home screen for sanity-checking and stores the full value in memory.

When vmuxAgent on the Mac connects to the iPhone over Multipeer, the iPhone sends the token through the encrypted channel. vmuxAgent stores the token in its persistent state and uses it for subsequent push wakes — even after vmuxAgent restarts.

The Transport section of the home screen shows the registration state:

A registered token is required for push wake. If yours says Not registered, the troubleshooting page covers recovery.

The 30-second reconnect window

When a silent push arrives, iOS gives the app roughly 30 seconds of background runtime to do useful work and then suspends it again. RemoteSignerPhone uses this window like so:

1. Push arrives. iOS hands the payload to the app delegate's didReceiveRemoteNotification handler.
2. The app calls into the signer host to restart Multipeer advertising. This is necessary because Multipeer state may be stale or torn down depending on how long the app was suspended.
3. Multipeer broadcasts. The Mac, which sent the push, receives the advertisement and immediately invites.
4. The encrypted Multipeer session establishes. The Mac sends the actual sign request payload.
5. The iPhone shows a time-sensitive notification banner. You either tap it (which foregrounds the app and shows the Sign Request sheet) or simply unlock and look.
6. You approve. Signature flows back. Done.

The whole sequence typically takes five to ten seconds from your ssh keystroke on the Mac. If it takes longer, there's network latency in the APNs delivery — not the local Multipeer link.

Test Notification button

The Transport section has a Test Notification button. Tap it to schedule a one-second-delayed local notification with title "Test" and body "Notifications are working." Use this to confirm:

• iOS notification permission is granted.
• Lock-screen, banner, and sound settings are correct in Settings → Notifications → RemoteSigner.
• The phone is not in a Focus mode that suppresses notifications from this app.

This test does not verify silent push wake — that requires an end-to-end test from a paired Mac. It only verifies local notification delivery, which is a strict subset.

What to do if push doesn't arrive

If you initiate ssh on the Mac and the iPhone never wakes:

1. Check APNs Token: Registered. Open RemoteSignerPhone and look at Transport. If it says Not registered, force-quit and relaunch the app while connected to the internet. iOS retries token registration on app launch.
2. Check the iPhone has internet. APNs delivery requires either Wi-Fi or cellular. Airplane mode, or a captive Wi-Fi network you haven't logged into, will silently drop pushes.
3. Check Focus mode. Some Focus modes suppress notifications even at the time-sensitive interruption level if you've explicitly excluded the app. Settings → Focus → (your mode) → Apps — make sure RemoteSigner is allowed.
4. Force-relaunch the app. Swipe RemoteSignerPhone away in the App Switcher and reopen it. This re-bootstraps Multipeer and re-sends the APNs token to the Mac on the next pairing. Until you do this, the Mac may be holding an expired token.
5. Restart the iPhone. Last resort. Apple occasionally has iCloud or APNs issues that a reboot clears.

If you have RemoteSignerPhone open and foregrounded, push wake doesn't apply — you'll see the Sign Request sheet directly the moment the Mac connects, with no APNs hop involved. So a quick way to bypass push troubles temporarily is to keep the app in the foreground while you make connections from the Mac.

What the silent push payload contains

For transparency: the silent push from vmuxAgent carries content-available: 1 and an empty data payload. It does not include any host name, identity, signature, or other security-sensitive content. Its only purpose is to wake the app; the actual sign request payload travels over the encrypted Multipeer Connectivity link, never through Apple's push infrastructure.

This means a network-level adversary observing APNs traffic learns at most that "your iPhone was woken by your Mac at this time" — not what was being signed, what host, or what key. The interesting cryptographic material stays local.

Will my iPhone wake when locked or in my pocket?

Yes. iOS delivers silent pushes regardless of lock state. The screen does not turn on; the app does not produce sound. A few seconds later the local notification posts (because a sign request arrived over Multipeer), and that local notification respects all your normal lock-screen and Focus settings.

If you want to suppress lock-screen banners but still want push wake, set the local notification style to "Banners (off lock screen)" or similar in Settings → Notifications → RemoteSigner. The wake mechanism still works; only the notification UI changes.

Battery impact

Silent push wakes are short — a few seconds of background CPU each — and infrequent on a typical day (one wake per ssh session you initiate from a paired device). Battery impact is negligible compared to ordinary apps that maintain continuous background activity. Multipeer Connectivity, even when actively advertising, is also extremely low-power because it leverages the Wi-Fi and Bluetooth radios that are already on.

Related

• Approving signing — the per-request UX once the iPhone has woken.
• Pairing and discovery — Multipeer behavior on top of which APNs sits.
• vmuxAgent — the Mac side that sends the push and drives the wake.