Support

What you need

• An iPhone on iOS 16.4 or later, with Belay Remote from the App Store.
• A Mac on macOS 13 or later, or a PC on Windows 10 or 11.
• Node.js 20 or later on that computer.

Install the host on a Mac

1. Install the Xcode command line tools: xcode-select --install
2. Install Node.js 20 or later.
3. In Terminal, run:

   npx belay-host

   The first run builds the screen helper, which takes a few seconds. Prefer the source? Clone the repository and run npm start in its server folder.
4. Leave the window open. It shows the computer’s addresses, its certificate fingerprint (the Cert line) and a pairing QR code with a 6-digit code.
5. Grant two permissions in System Settings → Privacy & Security: Screen & System Audio Recording and Accessibility. macOS gives them to the app you started the host from (Terminal, iTerm, VS Code…), not to “node” or “Belay”. After granting, fully quit that app with ⌘Q, reopen it and start the host again.

Install the host on Windows

1. Install Node.js 20 or later.
2. In PowerShell, run:

   npx belay-host

3. Leave the window open. It shows the addresses, the certificate fingerprint and the pairing code.
4. Windows Defender may flag BelayHost.exe, the small helper the build compiles to capture the screen and send input. It is built on your machine from the open source. If it is quarantined, add an exclusion for the server\native folder and rebuild — only on a computer you control.

To keep the host running at login and stop the computer sleeping, follow the full setup guide.

Pair your iPhone

1. Put the iPhone on the same Wi-Fi network as the computer, and open Belay Remote.
2. Scan the QR code in the host window. That’s it: the app saves the pairing and pins the computer’s certificate.
3. Or type the computer’s address and the 6-digit code. The app shows the fingerprint of the certificate it found: check it matches the Cert line on the computer before you enter the code. A different fingerprint means something else is answering at that address.

The code lasts five minutes and refreshes itself in the host window until a phone pairs. You only pair once.

Away from home (optional)

Install Tailscale on the computer and the iPhone, signed in to the same account. The computer then has a 100.x.y.z address that works from any network, and a phone on your own Tailscale network can pair with it without a code.

Common questions

The app says “the computer did not answer”

• Check the host window is still open and running, and the computer is awake.
• At home, check the iPhone and the computer are on the same Wi-Fi network.
• Away from home, check Tailscale is switched on and signed in on both devices.
• Check a firewall is not blocking the host (below).

No pairing code is shown

The host only shows a code while no phone is paired with it. If you have deleted the app, changed phones or want to start over, reset pairing on the computer and it shows a fresh code:

npx belay-host --reset-pairing

If a code has expired, just read the new one from the host window.

Firewall and port 8787

The host listens on port 8787. On a Mac, go to System Settings → Network → Firewall → Options and allow incoming connections for node. On Windows, allow Node.js through Windows Defender Firewall on private networks. Your router does not need any port forwarding.

Do I need Tailscale?

Only to reach your computer away from home. On the same Wi-Fi network, Belay connects directly without it.

How do I unpair and erase my data?

Delete Belay Remote from your iPhone: that removes everything it stored, including pairing tokens. To make the computer forget every paired phone, run npx belay-host --reset-pairing. We hold no data about you anywhere else; see the privacy policy.

Which versions are supported?

iPhone: iOS 16.4 or later. Computer: macOS 13 or later, or Windows 10 or 11, with Node.js 20 or later.

Re-pair after the security update

Phones paired before the update that added certificate pinning have no certificate fingerprint saved, so on your home network the app asks you to pair again to secure the connection. Over Tailscale they keep working. To re-pair:

1. Update the host: npx belay-host@latest fetches the newest version.
2. Start it with npx belay-host --reset-pairing so it shows a fresh QR code.
3. Scan the QR code in Belay Remote. It replaces the old entry and takes a few seconds.

Still stuck?

Email [email protected] or open an issue on GitHub. It helps to include your iPhone’s iOS version, your computer’s operating system, and what the host window printed (hide the pairing code first).