What it is
One-click remote control of other people's Macs and Android phones from a single Mac app. The far machine installs one silent .pkg that switches on macOS Screen Sharing (ARD) with zero dialogs; my side lists saved targets, and clicking a name opens Screen Sharing for a Mac or mirrors an Android phone with scrcpy. Wireless adb is auto-discovered, USB works as a fallback, and every failed connect returns a plain-language step log instead of a spinner — which is how I found out the real problem was a phone that had left the WiFi and taken a new IP, not the app.
Version history
Straight from the project’s own card data — what each version added.
Mac targets: silent .pkg enables ARD with a baked shared password; controller opens Screen Sharing on click.
Android targets via scrcpy + wireless adb, with a Type field and a per-target port.
Self-diagnosing: ping/ARP/mDNS/subnet probes at /api/scan, a step log on every failure, auto-reconnect, always-on-top mirror window, USB fallback.
Files on the site
What broke, and what I’d change
Not written yet. This is the part only I can write — what actually went wrong, and what I’d do differently. It lives in builds/reflections/remoteconnect.md (see _TEMPLATE.md); as soon as that file has words in it, this section fills in on the next build.
Everything else on this page — the spec, the version history, the file counts — is generated from the project’s own build notes and files, so nothing here is guesswork.
Build spec
The project’s own build notes, rendered. Open the raw .md ↗
Show the spec
RemoteConnect — one-click remote control of Macs and Android phones
A single Mac app that lists machines I'm allowed to reach, and opens the screen when I click a name. Mac targets are driven by the screen sharing macOS already ships; Android targets are mirrored and controlled with scrcpy. There is no relay server, no account, no subscription, and no third-party software on the far end.
Where it came from
I wanted to be able to help friends and family with their computers without walking through it over the phone: "click the Apple menu… no, the other one." Instead of a screensharing link, they install one file, and after that I only ever have to click their name.
The two halves
**RemoteConnect.pkg — the server, run on the other machine.** A standard macOS installer whose postinstall runs as root, which is what makes the silent part possible: it enables the com.apple.screensharing launchd service, then calls ARD's kickstart to set a shared VNC password and grant anyone holding that password full control. No dialog, no "System Settings › General › Sharing", nothing for the other person to configure. The same package ships a password-rotation app and a proper uninstaller that turns sharing back off, because a one-way installer is a bad thing to hand a non-technical friend.
RemoteConnect Controller — my side. A pywebview window over a small Flask API, listing saved targets. Click one and it either opens vnc://IP in macOS Screen Sharing (the app that's already installed) or runs scrcpy --tcpip=IP:PORT, which performs its own adb connection and mirrors the phone screen. Friends live in ~/.remoteconnect/friends.json — deliberately outside the app bundle, so rebuilding or reinstalling the app never loses the list.
What it does
- One click, one viewer. Mac names open Screen Sharing; Android names open scrcpy.
- Wireless Android, handled.
scrcpy --tcpip=owns the whole adb handshake, so the app - Self-diagnosing.
ping, ARP, an mDNS lookup and a 254-address parallel subnet sweep - Reconnects itself. If the phone only presents a TLS/pairing transport (typical right
- USB fallback. A cabled device is detected and used directly, skipping WiFi and ports
- Survives reinstall. The friend list is stored outside the bundle.
- Universal binaries. Every
osacompiled launcher is x86_64 + arm64; macOS 26 refuses
never has to manage the tunnel itself.
are exposed at /api/scan, and every failed connect returns a step log naming what went wrong and what to do — instead of a button that silently does nothing.
after a reboot), the app runs tcpip 5555 and reconnects on the classic port first.
entirely.
script-based .app executables, so the target is a real Mach-O binary.
Stack
Python, pywebview + Flask, pkgbuild / productbuild, macOS ARD (kickstart), Screen Sharing.app, scrcpy, adb, AppleScript launchers via osacompile.
Things that bit me
- **
adb disconnectbefore launching scrcpy kills the wireless tunnel scrcpy is about to - Android 11+ wireless debugging uses random ports, and the pairing port is not the
- Without
--always-on-topthe mirror opens behind the controller — which the user - An app installed by a
.pkginto/Applicationsis root-owned and cannot be kickstart -helprequires root, so the only way to confirm a flag still exists on the
use.** The mirror window appears for about one second and exits with code 2. The fix was to delete every adb call of my own and let scrcpy --tcpip= do the whole connection.
connect port. Neither is 5555 until adb tcpip 5555 has been run once over the TLS transport.
reports, entirely reasonably, as "the screen doesn't open".
replaced without admin auth, so iteration has to happen against a user-owned copy.
current macOS is to read the binary: strings -a <kickstart> | grep vncpw.
The lesson
The code was almost never the bug. I rebuilt the client eleven times against a phone that had quietly left the WiFi and taken a new IP address — every attempt was aimed at a dead address, and no amount of rebuilding could have fixed that. Diagnose the environment before changing the program, and make the program say out loud what it sees.