Let an AI agent operate a real iPhone or iPad plugged into a Linux machine or a Mac, reliably and fast — one Rust binary, no Xcode, no paid developer account, no jailbreak, and from iOS 27 no Apple ID either.
🚀 Quick Start · 📖 Docs · 📦 Releases · 🐛 Issues · 🌐 简体中文
Asking Claude Code to “open Clock, switch to the stopwatch and start it”. Left: Claude Code’s tool calls (first part only). Right: the phone afterwards.
AI agents can drive browsers and desktops, but a real iPhone is harder: Apple's automation tools need a Mac and Xcode, and the open-source alternatives come as separate pieces that each need their own setup, signing and babysitting.
iphone-control does it all in one Rust binary on Linux or macOS, built on idevice, Impactor and WebDriverAgent. It succeeds iphone-control-toolkit and keeps its MCP tools compatible.
It has three layers, and device control is the core:
| Layer | What it does | Needs the control page? |
|---|---|---|
| Device control (core) | A long-running daemon owns the phone and serves the MCP tools; recovers from unplugging and reboots; pausing, taking over and confirming AI tasks | No |
| Access | AI clients on this machine connect over stdio; other machines over HTTP MCP (/mcp) or mcp --url |
Locally no; remotely the viewer service must run |
| Control page (optional) | Watch the live screen in a browser, act on it, hand out AI tasks | It is the control page |
Device control has two routes, picked by iOS version:
- iOS 27 and later: native control (default). The screen is read through the system's accessibility service, taps, swipes and buttons go through HID, and apps launch through CoreDevice. Nothing is installed on the phone: no Apple ID, no signing, ready in seconds.
- iOS 17–26: WebDriverAgent. Signed with a free Apple ID, installed on the phone and re-signed before the 7-day profile expires. This route stays maintained.
Tip
Use a device on iOS 27 or later if you can, or update the phone to iOS 27: no Apple ID sign-in, no signing, no "Enable UI Automation" passcode after a reboot, and none of the expiring profiles, revoked certificates or stuck WebDriverAgent that come with it.
Device control (core)
- See and touch the screen: screenshots with region zoom, tap, swipe, long-press, text input (including Chinese), hardware buttons
- Work with UI elements: read the element tree, tap by text (on a part not covered by floating bars or the keyboard), launch and close apps, open URLs, wait for text to appear
- Fewer round trips: any action can return the resulting screen once it has settled, say whether it changed, and flag pages still loading and blocking alerts;
iphone_batchruns up to 20 steps in one call - Runs unattended: recovers from replugging, phone reboots and lost connections, and keeps serving with the control page closed; a stuck WebDriverAgent is restarted and re-signed before it expires
- A person stays in charge: AI tasks can be paused, taken over or stopped at any time; paying, deleting or sending waits for your OK, and an agent can't approve its own task
- Several devices: connect several iPhones and iPads and switch which one is controlled
- Optional auto-unlock: every passcode digit is verified, and a wrong passcode disables auto-unlock after one attempt
- Alerts: Telegram or Bark notifications when the phone goes offline, a passcode is needed after a reboot, or re-signing fails
- Diagnostics:
doctorchecks every layer from USB up and tells you how to fix each failure
Access
- On this machine: Claude Code, Codex or any MCP client over stdio;
task runruns any agent platform in a task whose every step you can follow - Remotely: the viewer service serves HTTP MCP (
/mcp) on its port, over HTTPS with a login token (read-only ones too) when opened to the network;mcp --urlandtask --urluse a phone on another machine
Control page (optional)
- Live screen: on iOS 27 and later the phone's own video (about 60 fps), otherwise H.264; a low-bandwidth mode
- Act on it: the mouse taps and drags like a finger; system alerts missing from the video are drawn on it and can be tapped
- Hand out tasks: give a task to a local Claude Code or Codex, watch it work and take over at any time
You need an iPhone or iPad (iOS 27+ recommended, iOS 17+ supported) connected by a data cable, and an Apple Silicon Mac or a Linux machine. On iOS 26 and earlier you also need a free Apple ID (use a dedicated one) to sign WebDriverAgent.
macOS or Linux, one command (upstream example; for a fork, use the installer asset from its own signed release)
curl -fsSLo iphone-control-install.sh https://github.com/Derrors/iphone-control/releases/latest/download/install.sh && sh iphone-control-install.shIt downloads the release for your machine, verifies the Ed25519 release manifest and archive SHA-256 (Python 3 and OpenSSL 3 required), installs iphone-control into ~/.local/bin and runs the daemon as a per-user service that starts at login (launchd on macOS, systemd on Linux). Run it as your regular user. Use iphone-control update to upgrade this managed service. Running sh iphone-control-install.sh --uninstall removes it and keeps your data.
Upstream v0.2.0 predates the signed installer. To install that release or migrate an existing script installation, follow the v0.2.0 instructions.
Or with a package manager
# macOS or Linux (Homebrew)
brew install derrors/tap/iphone-control && brew services start iphone-control
# Debian 12+ / Ubuntu 22.04+: the .deb from Releases (amd64 or arm64), pulls in usbmuxd
sudo apt install ./iphone-control_<version>_amd64.deb && systemctl --user enable --now iphone-controlOn Linux the system usbmuxd is needed (sudo apt install usbmuxd; the .deb brings it). On an Intel Mac, build from source.
Then, on every system
Connect the phone with the cable and run:
iphone-controlThe first time, it walks you through setup in the terminal, one step at a time: language, proxy, the background service, pairing, Developer Mode (and on iOS 26 and earlier, Apple ID and signing and installing WebDriverAgent), the optional auto-unlock and notifications, and registering with Claude Code and Codex. Do what it asks on the phone. Steps already done are skipped; afterwards, iphone-control just shows the status.
Then open a new Claude Code or Codex session and ask, for example, “Open Clock, switch to the stopwatch and start it.” That is device control, complete; the control page is optional. To watch the phone in a browser, run iphone-control viewer for the control page in the browser (http://127.0.0.1:8200; log in with the link iphone-control viewer token prints), where you can act on the live screen and hand tasks to a local Claude Code or Codex; it works from the local network and other machines too, see Viewer and Remote Use.
More: step-by-step guide · build from source · macOS guide · other MCP clients.
| Tool | Description |
|---|---|
iphone_status |
Connection, lock state, foreground app, screen size |
iphone_screenshot |
Screenshot scaled to points; pass x/y/width/height to zoom into a region |
iphone_list_elements |
Elements with text and their center coordinates; filter by text or type |
iphone_tap / iphone_tap_element |
Tap by coordinates or by element text |
iphone_swipe / iphone_long_press |
Swipe (returns once the list stops), long-press |
iphone_type_text |
Type into the focused field; reads it back and fixes dropped characters |
iphone_press_button |
home, volume_up, volume_down, lock |
iphone_list_apps / iphone_launch_app / iphone_terminate_app |
Manage apps by name or bundle ID |
iphone_open_url |
Open a URL or URL scheme |
iphone_wait_for |
Wait until some text appears instead of polling with screenshots |
iphone_batch |
Run up to 20 steps in one call, stopping at the first error |
iphone_list_devices |
Every iPhone/iPad on USB; marks the one being controlled |
iphone_select_device |
Switch to another device, or back to automatic choice |
IPHONE_CONTROL_DEV_TOOLS=1 adds six opt-in developer tools: logs, crash reports, installing and removing apps, and two for Web Inspector (list web pages, run JavaScript in them). They are off by default; read the security notes before turning them on.
Action tools accept then: "elements" | "screenshot" to return the screen after the action. Screenshot pixels are tap coordinates, so the agent can tap what it sees. Games, maps and video players draw their own UI and have no element tree — use screenshots and coordinates there. Full parameters: docs/tools.md.
Tool texts, results, CLI output and logs are in Simplified Chinese by default; set IPHONE_CONTROL_LANG=en for English (configuration).
| Command | What it does |
|---|---|
| (none) | The first time, the setup guide; after that, the status (and starts the service if it isn't running) |
setup [--reconfigure] |
Run the setup guide again; --reconfigure redoes one part (language, proxy, service, Apple ID, phone, auto-unlock, notifications, MCP registration) |
service install|uninstall|start|stop|restart|status |
The background service (launchd on macOS, systemd user unit on Linux) |
daemon |
The long-running daemon; the service runs it, or start it by hand |
mcp [--url <viewer>] |
The MCP server; your AI client starts it. With --url it bridges to another machine's viewer |
status |
Daemon state, time left on the signing profile, recent log |
doctor |
Layer-by-layer health check with a fix for each failure |
login |
Sign in to the Apple ID again when the session expires (WebDriverAgent devices only) |
sign |
Sign and install WebDriverAgent now (likewise) |
resign [--force] |
Re-sign WebDriverAgent if it expires soon (or now) (likewise) |
passcode set|clear |
Turn auto-unlock on or off for a device (passcodes are kept per device) |
unlock-reset |
Turn auto-unlock back on after it was disabled |
devices / select <UDID|name|auto> |
List connected devices / switch which one is controlled |
notify-test [event] |
Send test notifications |
mcp-config |
Print the command that registers the MCP server |
wda-bridge [--port] |
Expose WebDriverAgent on 127.0.0.1 for other tools; stop it when done (WebDriverAgent devices only) |
viewer [--port] [--lan] |
Control page on 127.0.0.1:8200, behind a login (viewer token shows the token and a link; read-only tokens too): live screen you can tap, swipe and type on, device panel, and AI tasks run by a local Claude Code or Codex. --lan opens it to the local network (HTTPS), and MCP over HTTP is on the same port (/mcp) |
task run [--url <viewer>] -- <command> |
AI tasks for other agent platforms; with --url the phone is on another machine. task list, pause, approve… follow and control tasks |
viewer token [add <name> [--read-only]|list|show <name>|remove <name>] |
The viewer's login tokens: show the owner's, or add named and read-only ones |
service viewer install|uninstall|start|stop|restart |
Run the viewer as a background service of its own |
update check|apply|policy |
Check for, install, or set the policy for updates |
completions <shell> |
Bash, Zsh or Fish completion script |
All commands and options: CLI reference.
Run iphone-control update to check for a stable release. When an upgrade is available, it uses the signed update for a managed service, Homebrew for a tap installation, or apt for a Debian package. It reports when you're up to date. Source installations follow the source upgrade instructions.
To check versions, open About & updates in Viewer or run iphone-control update check --json. Managed services can opt in to signed patches while idle with iphone-control update policy auto-patch. Use iphone-control update policy notify to return to checks only. Read the upgrade notes before upgrading.
Uninstall with sh iphone-control-install.sh --uninstall, brew uninstall iphone-control or sudo apt remove iphone-control; your data stays. Settings live in ~/.config/iphone-control/env: the guide writes it, and after editing it by hand run iphone-control service restart — see configuration. All state lives in ~/.local/share/iphone-control: the Apple ID session and signing key, and the passcode if auto-unlock is on. Back it up; never commit or share it.
| Guide | What is it · Limitations · Getting started · AI clients · Tools |
| Usage | Configuration · CLI · Several devices · Notifications · Auto-unlock |
| Deployment | Install · Build from source · macOS · Data and backups |
| Problems | FAQ · Troubleshooting · Issues |
| Security | SECURITY.md: what is stored, who can reach it, reporting vulnerabilities |
| Development | Contributing · Architecture · Decisions · Changelog |
| Licensing | THIRD_PARTY.md: vendored components, versions and licenses |
The architecture and design documents are in Chinese for now.
Warning
This tool can fully control your phone. An agent may tap payment, delete or send buttons — keep tool-call confirmation on in your MCP client. Not affiliated with Apple; use it only with devices and accounts you own. Read SECURITY.md before enabling auto-unlock.
Issues and pull requests are welcome — see the contributing guide.
MIT. Third-party components: THIRD_PARTY.md.