Access your Mac from a phone
The encrypted relay lets a phone reach uuBright Console on a home Mac without opening a port or using a VPN. The Mac dials out to your relay. The relay also serves the phone app at one fixed HTTPS origin.
Choose a relay. Either sign in to the uuBright relay, or take the relay URL and registration secret from your relay operator and configure the Mac with
CCR_CLOUD_RELAY_URLandCCR_CLOUD_RELAY_REGISTRATION_SECRET. Then restart uuBright Console. Keep the registration secret on the Mac; it never belongs in a pairing link. OnceGET /api/relay/statusreportsregistered: true, the relay has admitted this Mac's host key. The desktop app can then remove the registration secret from its LaunchAgent settings and restart the service; the host reconnects without it. Until then the secret is readable by other processes running as you, in the LaunchAgent plist and the service environment (launchctl print,ps eww): usually seconds to minutes, and indefinitely if registration fails. Keep a Keychain copy in case the host key or relay URL changes, or the relay loses its registration. If the relay closes the host with code 4412 (registration required), status returns toregistered: falseso the desktop can restore the secret; no other refusal clears it. A uuBright relay sign-in works the same way with the account token (see Use the uuBright relay).registeredneeds a relay deployed with the registration acknowledgement. Redeploy an older relay withdeploy.shfirst. An older relay still showsconnected: trueonce it has accepted the host, butregisteredstaysfalse, so the desktop keeps the secret in place. That is safe; it just stays readable as described above.- On the Mac, choose Connect your phone: in the ⋯ menu, under Server settings → Devices, or in the desktop app's menu. It shows a large 8-character code such as
K7Q4-MD2X, a QR code and the Mac's fingerprint. They work once, for ten minutes. If the relay is not configured, the code connects the phone to this server's own address instead, which works only if the phone can reach it. - On the iPhone, install the phone app first: open your relay's address in Safari, tap Share → Add to Home Screen, and open it from there (or use the uuBright Console iPhone app). Tap Add a computer and type the code. Case, spaces and dashes don't matter, and
Oreads as0,IandLas1. Once the eighth character is in, the phone looks the code up by itself, once; if that fails, fix the code or tap Add computer to try again. - The same card shows the computer's name and fingerprint. Check it matches the one on the Mac, then tap It matches. Add computer. Nothing is added before that tap. The phone connects in place and opens the app. It keeps a device signing key in IndexedDB (in the Keychain in the iPhone app) and a record of the computer without the pairing secret. Inside the encrypted pairing it tells the Mac what it is (iPhone, iPad (app), Android phone…), and the Mac lists it under that name; the relay never sees it.
- To add another computer, open Your computers (Server settings on the phone), tap Add a computer and type that computer's code. Pick a computer from the same list. The phone shows every computer's tasks together; see Several computers in one window.
- To remove a phone, open Devices on the Mac and click Remove under Paired phones. Its live channel closes, and it cannot reconnect. A removed phone shows “This phone was removed from the Mac.” Connect it again with a new code. Only you can do this, and only you can create a code: both need the owner's access on the Mac (or, for a remote host, the Mac app that manages it over SSH), so a paired phone or browser is refused (it can still disconnect itself).
- Adding a computer the phone already has is fine. A phone keeps one key per computer, so a new code typed on a phone that is still paired (after removing the computer on the phone only, say) reconnects it as the same entry under Paired phones: no second entry, no “New device paired” notice, and it does not count as a wrong try. The code is still used up.
Scanning the QR code with the Camera opens Safari, and Safari keeps its own storage, apart from the Home Screen app. The page goes straight to the same card: the computer's name, its fingerprint and It matches. Add computer. The card says that a computer added there stays in that browser, and on iPhone and iPad it offers Open in the uuBright Console iPhone app (the link hands the pairing over, to the same card in the app). To use the Home Screen app instead, open it and type the code. A link pasted into the code box lands on the same card. Every route shows the fingerprint, because the phone can't tell where a link came from.
#How the code stays safe
The code is short, but it never weakens pairing:
- The relay sees half of it, and can't use it. The relay routes on the first four characters, so it learns 20 of the code's 40 bits. The whole code is the password of a CPace exchange between the phone and the Mac, so the relay never learns the other 20 bits or the pairing the code unlocks, and has nothing to test guesses against offline. Even a relay that turns hostile can only guess online, one attempt at a time, and the Mac stops after ten: about one chance in 100,000 per ten minutes. See the protocol.
- Guesses are online and counted. The relay allows five tries per address for each code. The Mac answers one phone at a time per code and counts every attempt when the phone arrives, giving it back only if the phone pairs: after ten in ten minutes it revokes all its open codes and pauses new ones for ten minutes (the QR code still works). Over direct access, five wrong codes from one address are refused for ten minutes, and ten across the server do the same.
- Pairing is unchanged after the code. The code unlocks the same one-use payload as the QR code. The fingerprint is shown before the phone joins, the encrypted handshake pins the Mac's key, and using the code or the link uses up both.
When the relay's app is out of date. The relay serves the phone its own copy of the app, deployed separately from your Mac. The Mac compares that copy with its own when it connects and every hour. If they differ, the console shows a banner and a Needs you card, for example “The relay serves an older app (built 2026-10-22 10:05 UTC); redeploy it: services/relay/deploy.sh --managed”. Until it is redeployed, phones can load an app that doesn't match the Mac, and the iPhone app may refuse to connect. While the warning shows, the Mac checks again every two minutes, so it clears within a few minutes of the redeploy.
If the phone says to check its clock. The relay accepts a connection only when the phone's clock is close to right: up to two minutes fast or four minutes slow. Outside that it refuses the phone and the app says “Check this device’s clock”. Set the date and time to automatic (iPhone: Settings → General → Date & Time → Set Automatically) and the app reconnects by itself; there is nothing to pair again. The same limits apply to the Mac's clock: while it is outside them the Mac can't connect to the relay, and GET /api/relay/status reports closeReason: "clock_skew".
Keep the Mac awake and online while using the phone. A sleeping, shut down, or disconnected Mac cannot answer requests; the relay does not queue tasks or messages for it. Existing work on the Mac follows the host's own process state.
The relay transports encrypted API requests, task events and the files you attach. If the Mac's console is older than relay uploads, 📎 is dimmed and a tap says so; update the console on the Mac (the phone app doesn't need updating), and messages work meanwhile. On the uuBright relay, files a task published open on the phone too: the Mac encrypts each one and the phone downloads it from the relay's storage (how). A self-hosted relay has no file storage, and the live screen isn't available through any relay yet. Direct local access continues to work without a relay.
Trust boundary: whoever controls the relay origin serves the phone app's JavaScript. Malicious JavaScript there can read browser device material and plaintext. Use an origin you trust and protect its deployment credentials. The relay routes encrypted frames but can still see connection metadata and interrupt availability.
See What tasks on your Mac can access before opening an untrusted repository.
#Computer names
Pairing shows a recognizable computer name rather than the relay address. Macs use the name from macOS; generated EC2 names appear as Cloud server. Give each server a distinct name with CCR_CLOUD_COMPUTER_NAME (for example, Research server) and restart its service. On iPhone, you can also swipe a computer and choose Rename to set a name just for that phone. Your custom name survives reconnects. Names are labels; the stable computer ID and pinned keys still verify the connection.