Getting Started

One command on the Mac the iPhone is plugged into. The installer sets the phone up, shows an agent driving it, registers the MCP server with your agents and opens the control page in your browser. If anything is missing, it says what and how to fix it.

What you need

• A Mac with macOS 15 or later and the full Xcode.app (Command Line Tools alone are not enough), signed in to an Apple ID under Xcode → Settings → Accounts with a development team picked. A free Personal Team works, but its runner profile needs periodic renewal. An App Store Connect API key (IPU_RUNNER_ASC_KEY_PATH, IPU_RUNNER_ASC_KEY_ID, IPU_RUNNER_ASC_ISSUER_ID) signs without an Xcode account.
• An iPhone with iOS 15 or later and Developer Mode on (Settings → Privacy & Security → Developer Mode), paired with and trusted by the Mac over USB.
• A USB cable for the first setup. Plug the iPhone in and unlock it before you install. The phone must stay unlocked and awake while the runner is built, launched and used; nothing gets past Face ID or the passcode.
• No Homebrew packages. A Rust toolchain only if you build from source.

Install

$ curl -fsSL https://raw.githubusercontent.com/leeguooooo/iphone-use/main/install.sh | sh

What the installer does

1. Fetches the latest GitHub Release, registers a per-user LaunchAgent, installs the matching agent skill, lays the device runner sources down at ~/.iphone-use/runner and links the iphone-use command into ~/.local/bin.
2. With an iPhone plugged in, runs iphone-use setup (build, sign, install and launch the runner, start the relays) and iphone-use try (open Settings, read the screen, go Home), so you see an agent drive the phone before the installer exits.
3. Registers the MCP server with Claude Code and Codex, and with Cursor and Claude Desktop when they are installed (IPHONE_USE_NO_CLIENT_SETUP=1 skips those two). The server reads the daemon URL and token from the LaunchAgent, so no secret lands in the client's config.
4. Opens the control page in your browser with a one-time sign-in link and prints a QR code the iPhone camera can scan, so nobody copies the password.

--no-setup (or IPHONE_USE_NO_SETUP=1) skips the phone step; upgrades never run it.

Everyday commands

$ iphone-use status    # is the phone ready for agents?
$ iphone-use doctor    # what is missing, and how to fix it
$ iphone-use setup     # set the phone up again (after a new iPhone or Xcode)
$ iphone-use try       # a harmless check: open Settings, read the screen, go Home
$ iphone-use login     # sign a browser in again, with a QR code for the iPhone
$ iphone-use upgrade   # update everything
$ ~/.iphone-use/uninstall.sh --dry-run   # what uninstalling would remove (drop --dry-run to do it)

Or ask your agent to install it

Paste this into Codex or Claude Code on the Mac the iPhone is plugged into:

Install iphone-use (https://github.com/leeguooooo/iphone-use) on this Mac so you can drive my iPhone.
1. Run: curl -fsSL https://raw.githubusercontent.com/leeguooooo/iphone-use/main/install.sh | sh
2. Run `iphone-use doctor`. Fix what it reports that can be fixed from the terminal, and run
   `iphone-use setup` when it tells you to.
3. Some steps only I can do: signing in to an Apple ID in Xcode, tapping Trust on the iPhone,
   turning on Developer Mode, unlocking the phone. For those, stop, tell me exactly what to do,
   and wait until I say it is done. Never ask me for a password or a code.
4. Run `iphone-use doctor` again until nothing is missing, then `iphone-use try`.
5. If the phone_* tools are not loaded in this chat yet, tell me to start a new chat.

Codex and Claude Code plugins

Each plugin adds the skill and the MCP server; they still need the install above.

$ codex plugin marketplace add leeguooooo/iphone-use && codex plugin add iphone-use@iphone-use

> /plugin marketplace add leeguooooo/iphone-use
> /plugin install iphone-use@iphone-use

Other MCP clients (Cursor, VS Code, Claude Desktop, Gemini CLI, opencode, Windsurf) and the HTTP API: MCP, HTTP API & skill.

Upgrades

$ iphone-use upgrade            # install the latest release (daemon + skill)
$ iphone-use upgrade --check    # change nothing, just report

Automatic upgrades are on by default and wait for the phone to be idle. A daily job (04:30) upgrades every daemon on the Mac when a newer release exists and nobody is using that phone: no owner lease, no hold, no live viewer and no agent request in the last 15 minutes. A busy phone is skipped until the next day. The upgrade is the release's own install.sh, with its SHA-256 checks and rollback, and every setting is carried over.

$ ~/.iphone-use/auto-update.sh disable    # off, and it stays off across installs
$ ~/.iphone-use/auto-update.sh status     # on or off, what it would do now, the last result

A second phone

One daemon drives one phone. To drive another iPhone at the same time, install a named instance for it; the default install is left as it is. The instance gets its own copy of the app, state directory, token and ports.

$ curl -fsSL https://raw.githubusercontent.com/leeguooooo/iphone-use/main/install.sh | sh -s -- --instance lab --udid <UDID>
$ iphone-use setup --instance lab

No phone at hand: simulators (preview)

The runner also runs on an iOS Simulator, which needs no phone, no Apple ID and no signing, only Xcode with a simulator runtime.

$ iphone-use simulator start "iPhone 16 Pro"
$ claude mcp add iphone-sim -e IPHONE_USE_INSTANCE=sim -- iphone-use-mcp

Simulators have no camera, App Store apps, real push notifications or Face ID, so tasks that need those only work on a phone.

The iOS app

The iOS app is not in the App Store. Build and install it with your own signing team, the one setup already uses for the runner:

$ iphone-use setup-app   # add --instance <name> for a second phone

• Free Apple ID: the remote app. It drives phones that a Mac serves, paired by scanning a QR code on the Mac's page.
• Paid developer team: the full app, with local control. The phone serves taps, typing, screen reads and the agent API itself with no Mac at run time (iOS 17.4 or later). The first pairing still needs the USB cable once.

Next: what to ask your agent, or how it works.