Telepin

Telepin for Apple Silicon Mac

The 0.5.0 Mac port uses the same map, route, jump, joystick, GPX, and saved-place features as Windows. It targets Apple Silicon and macOS 14 or later. This handoff contains source and a native build launcher; it is not yet a compiled Mac installer. macOS execution and the reported iOS 26.7 still need verification on your Mac and iPhone.

Build on your Mac

Extract Telepin-Mac-Build-0.5.0-arm64.zip, then open its Telepin folder in Codex. Start with MAC-HANDOFF.md, which records the completed work and remaining checks.

The build machine needs native Python 3.13, Node.js 24 or later, and Xcode Command Line Tools. Use Apple Silicon versions rather than Rosetta. Python is available from python.org and Node from nodejs.org. The build reports missing prerequisites before packaging. The finished app bundles Python and does not require Python or Node where it is installed.

Open Build Mac.command, or run this from the extracted project folder:

bash "Build Mac.command"

The launcher creates .venv-mac-build-arm64-py313, installs dependencies, runs the Python and desktop tests, builds the native iPhone engine and interface, and packages a DMG and ZIP. It checks their bundled engine, app identity, architecture, signature integrity, and startup without connecting to a phone. Internet is required for dependencies. Existing Windows releases are not rebuilt or overwritten.

After successful completion, outputs in releases/mac-arm64 include Telepin-0.5.0-arm64.dmg, Telepin-0.5.0-arm64.zip, BUILD-VERIFICATION.json, and SHA256SUMS.txt. Open the DMG and drag Telepin into Applications.

The default build has a local ad-hoc signature, not a Developer ID signature or Apple notarization. It is intended for local testing. With existing Apple credentials, bash "Build Mac.command" --signed requires a Developer ID identity; adding --notarize submits the signed build to Apple. Neither option creates accounts or certificates. See electron-builder signing for credential setup.

Connect the iPhone

  1. Connect by USB, unlock the phone, accept its Trust prompt, and check it appears in Finder. macOS provides its own USB device service; Apple Devices for Windows is not needed. Apple's Finder guide
  2. Enable Settings → Privacy & Security → Developer Mode on the iPhone and complete Apple's restart/confirmation steps. If the option is missing, follow Apple's Developer Mode guidance.
  3. Open Telepin and connect the iPhone. The first connection can download developer support files; keep the phone unlocked.
  4. Pick a location and set it, then verify in Maps on the phone. Test a short route, Pause/Resume/Stop, and Restore real GPS, checking Maps after each step.

Selecting a pin or previewing a route does not send it. Starting movement sends its first location immediately. Pause, Stop, and completion hold the last location; Restore removes the override. Closing or choosing Quit requests restoration before exiting. Sleep pauses movement. If reset cannot be confirmed, reconnect and restore; the warning remains visible.

The iOS 17.4+ userspace USB tunnel does not require running Telepin as root. Individual apps may handle simulated location differently. Physical iOS 26.7 behavior remains unverified until tested with your phone.

Connect over Wi-Fi

  1. Complete the USB connection above. Stop any movement and select Restore real GPS if an override is active.
  2. Open the connected iPhone's device card and select Set up Wi-Fi. This explicitly saves wireless pairing on this Mac; it does not set a location.
  3. Choose Disconnect iPhone in Telepin, then unplug the cable.
  4. Put the computer and unlocked iPhone on the same reachable local network. Choose Wi-Fi, refresh, select the paired phone, and choose Connect over Wi-Fi. A discovered phone's iOS version is checked when connecting.

Wi-Fi requires iOS 17.4 or later and Developer Mode. Allow local network access if macOS asks. Guest-network isolation, a VPN, or a firewall can prevent discovery; use a network where the devices can communicate. Finder's Wi-Fi sync option is not required by this connection path. The app requests local-network access through its Mac permission declaration.

If the wireless connection drops, movement stops when the failure is detected and the GPS-reset warning remains. Use Reconnect & restore on Wi-Fi, or plug in the same iPhone and select USB cable in Connection recovery. Recovery restores location before allowing further movement; it does not resume a route automatically. Wi-Fi pairing, actual phone movement, and recovery on iOS 26.7 still need the physical-device checks in MAC-HANDOFF.md.

Data and scope

Places, routes, and recovery information live in ~/Library/Application Support/Telepin/places.json. The phone library also keeps local pairing records and developer-image caches. The map uses OpenStreetMap, searches use Photon, and road previews send chosen stops/travel mode to Valhalla/FOSSGIS. No account or analytics service is added. MOVEMENT-PARITY.md records movement behavior, limits, and provider requirements.

Launch Mac.command is the earlier coordinate-only interface. Build Mac.command produces the new map-based desktop app.