Requirements

- macOS 15 Sequoia or later (iPhone Mirroring's requirement) with iPhone Mirroring set up and signed in. Validated on macOS 15 Sequoia / 26 Tahoe; see the Roadmap for macOS 27 support. - Rust toolchain (to build) — cargo. - Zero external runtime dependencies — all input (tap, scroll, text, key, shortcuts) is injected via native CGEvent directly, and screenshots use the built-in screencapture CLI. No third-party binary (cua-driver or otherwise) is required at runtime. - (optional) a Cloudflare TURN key for cross-network (cellular / remote) access.

Deployment — a GUI-session LaunchAgent

ScreenCaptureKit (Screen Recording) and input injection (Accessibility) require TCC grants tied to a signed identity in the login session — an SSH-spawned binary is denied. So the daemon runs as a codesigned LaunchAgent in the desktop session, granted once; SSH shells, agents, and the iPhone Safari controller all connect to it.

Install

Build, bundle into a signed .app, and register the LaunchAgent:

cargo build --release --bin iphone-use
./scripts/make-app.sh                 # → ./iPhoneUse.app
./install.sh ./iPhoneUse.app       # signs, installs, writes the LaunchAgent

install.sh binds 0.0.0.0, generates a password (or uses $PHONE_REMOTE_PASSWORD), opens the Screen Recording + Accessibility panes to grant once, and prints the iPhone connect URL. On the iPhone (same Wi-Fi) open http://<mac-lan-ip>:44321/phone and enter the password.

Pre-built binaries are published from CI on every version tag — see the Releases page. To cut the first release: trigger the smoke-test via Actions → workflow_dispatch, then git tag v0.1.0 && git push origin v0.1.0. install.sh self-signs the app locally with codesign -s -; Gatekeeper will prompt unless the binary is notarized (optional secrets: APPLE_SIGNING_CERTIFICATE / APPLE_SIGNING_CERTIFICATE_PASSWORD / APPLE_SIGN_IDENTITY; notarization: APPLE_ID / APPLE_ID_PASSWORD / APPLE_TEAM_ID). Unsigned is the default path.

Run without installing (dev)

PHONE_REMOTE_HOST=0.0.0.0 PHONE_REMOTE_PASSWORD=secret \
  ./target/release/iphone-use serve

Configuration (environment)

Agent API

Agents drive the phone by connecting in to the running daemon (never by spawning their own input process — macOS makes a spawned child's events untrusted). Bearer auth: Authorization: Bearer <token> where token is PHONE_REMOTE_AGENT_TOKEN when set, otherwise PHONE_REMOTE_PASSWORD (legacy fallback).

Gate actions on drivable, not phone_target: the Mirroring window can be up yet showing the "Connection Paused" / "iPhone in Use" interstitial, where taps land in the void. mirror_state (active/paused/in_use/offline) + hint say what to do (paused → tap Resume; in_use → lock the phone; offline → open Mirroring). human_active:true warns a person is using the Mac — in mirror mode an L3 tap steals their focus, so back off or switch to agent mode (/agent/mode, on-device).

Full reference: docs/agent-api.html.

HOST=http://<mac-lan-ip>:44321; AUTH="Authorization: Bearer $PW"
curl -s -H "$AUTH" "$HOST/agent/screenshot" -o screen.png
curl -s -H "$AUTH" -X POST "$HOST/agent/input" -d '{"type":"shortcut","name":"home"}'
curl -s -H "$AUTH" -X POST "$HOST/agent/input" -d '{"type":"tap","x":0.5,"y":0.3}'
curl -s -H "$AUTH" -X POST "$HOST/agent/input" -d '{"type":"keyboard"}'   # dismiss the keyboard (wda)