FAQ

Setup

Does it need a jailbreak?

No. It needs Developer Mode on the iPhone and a signed XCTest runner, which iphone-use setup builds, signs and installs with your own Xcode team.

Can Windows or Linux host the phone?

No. The phone is hosted by a Mac running the iphone-use daemon. Other computers, including Windows and Linux ones, can reach that Mac's browser page and APIs, but they are not device hosts themselves.

Which Macs, iPhones and iOS versions work?

A Mac with macOS 15 or later and full Xcode.app (Command Line Tools alone are not enough), and an iPhone with iOS 15 or later and Developer Mode on. A free Apple ID (Personal Team) can sign the runner, but its profile needs periodic renewal; an App Store Connect API key signs without an Xcode account.

iOS 15 and 16 need no update, but they go through a separate legacy path that needs a paid developer account's App Store Connect API key. iOS 14 and older are not supported.

Can I try it without a phone?

Yes, as a preview: iphone-use simulator start "iPhone 16 Pro" builds and starts the runner and a daemon for an iOS Simulator, which needs Xcode but no phone, Apple ID or signing. Simulators have no camera, App Store apps, real push notifications or Face ID, so tasks that need those only work on a phone.

Does it work over Wi-Fi?

Yes. Set the phone up once with a cable; after that the daemon reaches it through CoreDevice's encrypted Wi-Fi tunnel, and USB is still preferred whenever the phone is plugged in. In the maintainer's measurements a tap costs about 330–380 ms over the tunnel against about 280 ms over USB. iOS 15/16 phones use a LAN relay instead, which is signed but not encrypted. A phone whose iOS refuses to start the runner over Wi-Fi needs the cable again whenever the runner has to restart.

How do I uninstall it?

Run ~/.iphone-use/uninstall.sh --dry-run to see what would be removed, then drop --dry-run to do it.

Using the phone

Does it move my Mac's cursor or take focus?

No. It never touches the Mac's screen, cursor or window focus, whether an agent or you in the browser is driving the phone.

Can it use apps I am signed in to?

Yes. It operates the apps already on the phone, with their sign-ins. For logins, passcodes and Face ID the agent stops and asks you to finish on the phone; it never asks for the password or the code.

What about apps that block screenshots?

Banking and payment apps black out screen capture. There the screenshot comes back as a wireframe of the screen's elements, and the agent drives the screen by its elements instead of pixels. What it can read depends on what the app exposes, so not every screen is readable.

Can I use the phone myself while it is installed?

Yes. Hold both volume keys to end iOS UI automation, run iphone-use pause (and iphone-use resume later), or press the hand-back button on the web page; agent input is then refused until you give the phone back. The daemon also releases the phone by itself after 5 minutes without agent activity or a live viewer.

Why does the phone ask for its passcode?

Each runner launch can ask for the passcode on the phone to enable UI automation, and nothing can type the lock-screen passcode for you. That is why the daemon releases idle phones instead of relaunching the runner around the clock, and why on a passcode-protected phone it keeps a runner that is already up running instead of releasing it.

Can I drive two phones at once?

Yes. Install a named instance for the second phone (./install.sh --instance lab --udid <UDID>). Each phone gets its own daemon, runner, token and ports, and MCP calls can pick one with instance.

Is the iOS app in the App Store?

No. iphone-use setup-app builds it with your own signing team and installs it on the phone. With a paid developer team you get the full app, which can also control its own phone with no Mac (iOS 17.4 or later); with a free Apple ID you get the remote app, which drives phones that a Mac serves.

Project

Does it still use WebDriverAgent or iPhone Mirroring?

No. Its own XCTest runner replaced WebDriverAgent in v0.14.0 and still speaks the same HTTP API. The iPhone Mirroring backend was removed in v0.9.

What is the license? Is it open source?

PolyForm Shield 1.0.0. It is source-available, not an OSI-approved open-source license: non-competing use, modification and distribution are permitted, and using it to provide a competing product or service, including a free one, is not. Copies published earlier under MIT keep that grant. See LICENSING.md.

Does it send telemetry?

No. The daemon contains code for anonymous usage counts, but no project token ships with it, so it sends nothing. IPHONE_USE_TELEMETRY=0 or DO_NOT_TRACK=1 turns it off completely even if a token is set. See Privacy & security.

Where do I report a bug?

In GitHub issues. Problems with a saved flow go to the flow registry; an agent can file one for you with phone_flow_report once you agree.