iphone-use: Let AI Agents Control a Real iPhone

I built iphone-use so Codex, Claude Code and other agents can use a real iPhone: read its screen as text, tap, swipe and type, then check whether the action landed.

A daemon runs on your Mac and a custom XCTest runner runs on the phone. Access it through the CLI, HTTP API, MCP or a browser. It does not drive the Mac’s cursor or window focus.

Install: a Mac, Xcode and a real iPhone

You need macOS 15 or later, Xcode, an Apple ID for signing and a USB cable. A free Apple ID works. Enable Developer Mode on the phone, plug it into the Mac and unlock it.

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

try opens Settings, reads the screen and returns Home: a harmless, reproducible check of basic control. Read the actual output; installation does not establish current device readiness. doctor names missing prerequisites.

Use an iPhone from Codex, Claude Code or an MCP client

The installer prepares the agent skill and registers MCP for installed Claude Code. Other MCP clients can use this configuration; replace the username in the executable path.

{
  "mcpServers": {
    "iphone-use": {
      "command": "/Users/YOUR_USERNAME/Applications/iPhoneUse.app/Contents/MacOS/iphone-use-mcp"
    }
  }
}

The HTTP API lives under /agent/*. MCP covers readiness, screen reading, input, shortcuts and flows. Inspect status first and act against the current element snapshot. Outcomes distinguish executed, not dispatched and uncertain; a response is not proof that a task completed.

Screen text, CJK input and screenshot-restricted apps

The runner reads accessibility snapshots and injects touch and Unicode text through XCTest, without using the Mac’s input method. Accessibility reading can help when an app restricts screenshots, but the readable content depends on what the app exposes. Not every screen is readable.

Save a repeated task as a flow

The browser panel records acknowledged actions. Review the draft before saving an app-specific flow; its normal replay path does not call a model. The official flow registry exposes scripts and verification records.

~/Applications/iPhoneUse.app/Contents/MacOS/iphone-use-mcp flow list
~/Applications/iPhoneUse.app/Contents/MacOS/iphone-use-mcp flow validate my-task.json

Flows can form test suites or scheduled tasks. App updates, account state and permissions can invalidate a flow; reverify after failure.

iphone-use vs agent-device, Mobile MCP and Appium

This compares use cases, not measured speed or reliability. A benchmark needs the same device, actions and settling conditions.

Frequently asked questions

Does it need a jailbreak?

No. It needs Developer Mode and a signed XCTest runner.

Does it still use WebDriverAgent or iPhone Mirroring?

The custom XCTest runner replaced WebDriverAgent in v0.14.0. The current control path does not depend on iPhone Mirroring. Earlier Mirroring and three-layer-input articles describe historical implementations.

Can Windows or Linux host the phone?

The current local device host is a Mac. Remote clients can access its browser UI and APIs; that is not a native Windows device host.

Can it use signed-in apps?

It controls existing phone apps, retaining their signed-in state. The user handles passwords, verification codes, identity checks and final payment.

Where does it run?

You self-host the daemon and device runner. The daemon’s exposed interface requires authentication. The runner on the phone accepts only requests signed with a per-launch token; on iOS 15/16 the LAN path is signed but not encrypted.

Current documentation and source

Website · Install · Ask your agent · GitHub / README · Full guide · XCTest runner · Releases · chrome-use