Fix connection problems

Knowing what is supposed to happen makes the fixes obvious. A PocketCtrl connection has four parts, and each one can fail on its own:

1. The Mac is hosting. The Mac app captures the screen and listens for viewers. If hosting is stopped, or the Mac is asleep, there is nothing to connect to.
2. The devices can reach each other. Either both are on the same Wi-Fi network, or Tailscale is on and signed in on both. PocketCtrl tries local Wi-Fi first and Tailscale second, automatically.
3. The device is trusted. The first time, you pair: the phone sends a request and the Mac owner approves it. After that the phone holds its own credential and reconnects without asking.
4. Video flows. Once the phone is trusted and reachable, the Mac starts streaming. The phone waits up to about 12 seconds for the first frame before it reports a problem.

The status text in the app tells you which part it is working on. The message table below decodes every one of them.

1. Is the Mac awake and hosting?

Look at the Mac. Open PocketCtrl there and click Host in the top-right corner (or choose Start hosting on this device on the home screen). The side panel that slides in should say This Mac is hosting. If it says Hosting is stopped, click Start Hosting.

• If Start Hosting is greyed out, a permission is missing. The panel tells you which. See Permissions on Mac and iPhone.
• A Mac with the lid closed or the display asleep may still host, but a Mac that has gone fully to sleep will not. Turn on Keep Mac awake while hosting in the Hosting section of the side panel.
• Only one copy of PocketCtrl can host at a time. If you ran a second copy from Xcode or a download folder, quit it.

2. Are both devices on the same network, or both on Tailscale?

This is the single most common cause. “Same network” means the iPhone and the Mac are joined to the same Wi-Fi name at the same place. A phone on cellular, a guest network, a hotel or office Wi-Fi with client isolation, or a personal hotspot is not on the same network as the Mac, even if you are standing next to it.

Not sure? Are my devices on the same network? shows how to check in under a minute. If they are not, either move both to the same Wi-Fi, or turn on Tailscale on both. The Tailscale guide takes about five minutes.

3. Is Local Network allowed on the iPhone or iPad?

iOS asks once whether PocketCtrl may find devices on your local network. If anyone tapped Don't Allow, iOS silently blocks every nearby connection and PocketCtrl shows Local Network access is off. Fix it in Settings → Apps → PocketCtrl → Local Network, then return to PocketCtrl and tap Try Again. The Mac has the same permission in System Settings → Privacy & Security → Local Network.

4. Did the Mac approve this device?

The first connection from any device needs approval on the Mac. When your phone sends a request, a New Device Request window appears on the Mac. Choose what the device may do and click Authenticate and Approve. If nobody approves within three minutes the request expires and the phone shows The host Mac did not approve the request in time. Just send the request again and approve it. Details are in the approval section.

5. Is the pairing code still valid?

The QR code and Computer Code expire two minutes after they appear. If the phone shows That computer code expired or That pairing code expired, click Pair New Device on the Mac again to get a fresh one, then scan or type it. Typing the code is case-insensitive.

6. Still nothing? Restart the pieces

1. On the phone, tap Stop, then try the saved Mac again.
2. On the Mac, click Stop Hosting, wait two seconds, click Start Hosting.
3. Toggle Wi-Fi off and on, on the phone. This forces it to rejoin the network.
4. Quit and reopen PocketCtrl on both devices.
5. If you use Tailscale, open the Tailscale app on both devices and confirm each says Connected.

Messages from the iPhone and iPad app, and the status the Mac app shows for the same situation.

Approval is what keeps a random person on the same Wi-Fi from viewing your screen. Every new device has to be accepted, in person, on the Mac. Here is exactly what to expect:

1. On the Mac, with hosting running, click Pair New Device. A QR code and a Computer Code appear. Leave this window open.
2. On the phone, scan the QR or type the code. The phone says Found … Waiting for approval….
3. On the Mac, a New Device Request window appears within a second or two. It shows the requesting device's name, the route it came in on, and a fingerprint you can compare with the phone.
4. Choose what the device may do. Screen viewing is always included. Allow mouse and keyboard control, Allow clipboard access, and Allow Mac audio are off by default. Allow future unattended access keeps the device trusted after hosting stops; leave it off for a one-time session.
5. Click Authenticate and Approve and confirm with Touch ID or your Mac password. The phone connects within a few seconds.

The request never appears on the Mac

• The phone must show Found … Waiting for approval. If it is still Looking for your Mac, the request never arrived: go back to step 2.
• PocketCtrl on the Mac may be behind another window. Click its Dock icon.
• If the Mac shows Pairing is closed, click Pair New Device again. Pairing closes automatically after each approval and when the code expires.

Approve was clicked but the phone still says waiting

Approving with the wrong Touch ID finger or cancelling the password prompt counts as a deny. Try again and complete the authentication. If the Mac reports This Mac could not securely save the device credential, the Mac's Keychain refused the write; this happens with unsigned builds run from Xcode. Use the downloaded, notarized app from the download page.

Almost always one of these changed:

• The Mac went to sleep or restarted and hosting is off. If you want hosting to survive restarts, turn on Launch at login and Start hosting automatically in the Mac's Hosting section.
• The phone is on a different network than last time: cellular, a guest network, or the neighbour's Wi-Fi it auto-joined. Check Settings → Wi-Fi.
• Tailscale signed out or its key expired. Open Tailscale on both devices. It will say if you need to sign in again.
• The device was removed on the Mac. If someone chose Remove from List in the Mac's trusted devices, the phone's credential is no longer valid. Pair again.
• It was a session-only approval. If Allow future unattended access was off when approved, access ended when hosting stopped. Pair again and turn it on this time.
• The Mac's IP address changed after a router restart. PocketCtrl re-discovers the Mac by its identity, not its address, so this normally heals itself within a few seconds of the Mac hosting. Give it a moment, then try again.

The Mac app is also a viewer. On the Mac you want to control from, choose Connect a new Mac on the home screen. You can paste a pocketctrl:// pairing link (the Mac being controlled can copy it from its pairing window) or upload a screenshot of the QR code. Everything else, including the approval window and the three-minute wait, is identical to the iPhone flow. Both Macs must share a Wi-Fi network or both have Tailscale on.

Most people never need this section. If you have a corporate VPN, a strict firewall, or a network you do not control, read on.

• Other VPNs. A VPN app on the phone or Mac that routes all traffic will usually hide the local network. Turn it off while pairing, or use Tailscale, which coexists with most VPNs.
• macOS Firewall. If System Settings → Network → Firewall is on, allow incoming connections for PocketCtrl when macOS asks. Block-all mode will prevent hosting.
• Ports. Video, input, and audio travel over UDP ports 5555, 5556, and 5557 by default. Pairing requests arrive on TCP port 47778. You can change the three UDP ports in the Mac's Network section; change them on the phone only if the Mac tells you to.
• Do not port-forward. PocketCtrl is pre-release software that has not had an independent security audit. Never expose these ports to the internet. Use Tailscale for remote access.
• Discovery. On local Wi-Fi the phone finds the Mac with Bonjour (the service is _pocketctrl._udp). Networks that block multicast defeat discovery; Tailscale routes do not need it.