Why pairing exists
Anyone on your Wi-Fi could, in principle, find a Mac that is hosting. Pairing is what stops them from seeing anything. A device that has not been approved on the Mac gets nothing: no video, no control, no clipboard. When you approve a device, the Mac generates a random credential just for it and sends it over an encrypted channel. From then on every packet between the two is authenticated and encrypted with keys derived from that credential.
Because each device has its own credential, you can remove one phone without affecting another, and a credential copied off one device does not help anyone on a different device.
Three ways to send a request
On the Mac, with hosting running, click Pair New Device. The pairing window shows three representations of the same short-lived invitation. They all expire together.
QR code
Fastest on an iPhone or iPad. Choose Connect a new Mac, point the camera at the Mac's screen, and PocketCtrl immediately starts looking for the Mac over local Wi-Fi and Tailscale. If the camera is not available, iOS offers to pick a screenshot instead.
Computer Code
A 12-character code shown under the QR. Type it into Computer Code on the phone. It is not case-sensitive. The code encodes the Mac's identity and, if Tailscale is on, its Tailscale address, so the phone knows where to send the request even when Bonjour discovery is unavailable.
Pairing link
A pocketctrl:// link that a Mac viewer can paste, or that you can send to your own other Mac. It contains only connection details. Like the QR and code, it cannot grant access; the Mac owner still has to approve.
The approval window
Within a second or two of the phone sending its request, the Mac shows New Device Request. It contains:
- The device name, as supplied by the requesting device. Treat it as a hint, not proof.
- The route: local Wi-Fi or Tailscale, and the address the request came from.
- A fingerprint of the requesting device. If you are ever unsure who is asking, compare it with the one shown on the phone.
- Four switches (below) and two buttons: Deny and Authenticate and Approve.
Authenticate and Approve asks for Touch ID or your Mac password. This is deliberate: only someone who can unlock the Mac can add a device. Cancelling the prompt denies the request.
The window waits three minutes. If nobody acts, the request is dropped and the phone shows The host Mac did not approve the request in time.
Nothing is stored; just send the request again. The phone shows a Need help? button after about twenty seconds of waiting, which brings you back here.
The four permissions
Screen viewing is always included. Everything else is off unless you turn it on for this device. These are per-device: approving your iPad with control does not give your phone control.
- Allow mouse and keyboard control. The device may move the pointer, click, scroll, and type. This is what people mean by “remote control”. Without it the device is view-only, and the remote view will show the screen but ignore taps and typing. Also requires the Accessibility permission on the Mac.
- Allow clipboard access. Text copied on one device appears on the other. Off by default because clipboards often contain passwords.
- Allow Mac audio. The Mac's system audio streams to the device. Uses more bandwidth.
- Allow future unattended access. Explained next.
Unattended versus session-only
Unattended (the switch on) means the Mac saves this device's credential in its Keychain. The device can reconnect any time the Mac is hosting, including after the Mac restarts, without anyone approving again. This is what you want for your own phone.
Session-only (the switch off) means the credential lives only in memory. The device can connect as often as it likes during this hosting session. When you click Stop Hosting or quit the Mac app, the credential is discarded and the device would have to be approved again. Use this for a friend's phone or a one-off.
The Mac lists session-only devices with the note Session only: access ends when hosting stops and is not saved on this Mac.
Codes expire after two minutes
The QR code, Computer Code, and pairing link are valid for two minutes from the moment they appear. The Mac then quietly generates a new one while the pairing window stays open, so if you are looking at the Mac you will see the code change. A phone that scanned the old one gets That computer code expired. Generate a new code on the host Mac.
Scan or type the current code.
The two-minute limit is separate from the three-minute approval wait. Once the request has reached the Mac and the approval window is showing, the code expiring does not cancel the request.
Managing and removing devices
In the Mac's Host panel, the trusted devices list shows every approved device, what it may do, and when it last connected. Choose Remove from List to revoke a device. It takes effect immediately: if that device is connected it is dropped, and its saved credential is deleted from the Mac so it cannot come back without pairing again.
On the iPhone, swipe or use the menu on a saved Mac to forget it. That deletes the phone's copy of the credential; the Mac's list is unaffected until you remove the device there too.
To start completely fresh, on the Mac choose Regenerate pairing (also available from the pocketctrl regenerate-pairing command). It invalidates the current invitation, not existing trusted devices.
Questions
Can someone pair without me noticing?
No. Pairing is closed unless you open it, every request shows a window on the Mac, and approving requires Touch ID or your password. Invalid codes are rejected and repeated failures are rate-limited.
Is it safe to post a screenshot with the QR code?
The QR is only an invitation that expires in two minutes and still needs your approval, so a leaked one cannot grant access by itself. Even so, treat it like a house key you are about to change: do not share it publicly.
Why did the Mac ask me for my password instead of Touch ID?
macOS falls back to your password when Touch ID is unavailable, for example on a Mac mini without a Touch ID keyboard or when the lid is closed. Either one approves the request.
Where are credentials stored?
In the device-only, non-syncing Keychain on each device. They are never uploaded anywhere and are not included in iCloud Keychain sync. See the Mac app tour and SECURITY.md.
Still stuck?
Email hello@talkupapp.com with your device models, OS versions, whether you are on the same Wi-Fi or using Tailscale, and the exact message PocketCtrl shows. Screenshots help. Never send pairing codes, QR images, or credentials.