Automate iPhone using Mobilerun AI - Guide

Android has always been the easy target for mobile automation and ADB makes it almost trivial. iOS is a different story. Apple's sandboxing means there's no official way to remotely drive a physical iPhone. But with Mobilerun, you can connect your own iPhone to the cloud and have AI agents run real tasks on it: tapping, typing, navigating apps, end to end.

This guide walks you through connecting an iPhone to Mobilerun using the mobilerun-ios CLI. Once connected, your device shows up as a Personal Phone on the Devices page, ready to run tasks from the Playground or API.

What you'll need

A Mobilerun account with a Personal Phone subscription

> A Mac with Xcode installed
> An iPhone connected via USB
> An Apple ID with signing capability (a free personal team works)

How it works

Mobilerun controls your iPhone through WebDriverAgent (WDA), an open-source project that exposes input injection and screenshots on iOS. Mobilerun maintains its own fork, tuned for higher-quality streaming, lower-latency accessibility tree fetching, and faster touch input. You build WDA onto your iPhone once with Xcode, then the mobilerun-ios CLI opens a WebSocket to Mobilerun cloud and keeps the device online.

Let's set it up.

Step 1: Enable Developer Mode on your iPhone

Developer Mode lets Xcode install and launch development builds on your device.

> Open Settings → Privacy & Security → Developer Mode
> Toggle it on
> Restart when prompted, then confirm after reboot

Don't see the Developer Mode entry? It only appears after the iPhone has been connected at least once to a Mac running Xcode. Plug it in, open Xcode, and check again.

Step 2: Configure the iPhone for long-lived connections

A Personal Phone is meant to stay online for hours or days. Three settings make the difference between a connection that survives and one that needs babysitting:

1. Disable Auto-Lock. When the iPhone locks, the screen goes black and the session goes offline. Set Settings → Display & Brightness → Auto-Lock to Never.

2. Enable automatic time zone. Set Settings → General → Date & Time → Set Automatically to on. This keeps the device's time zone in sync with its (simulated) location, manually setting it doesn't work on non-jailbroken devices.

3. Remove the passcode (24/7 setups only). WDA's host session occasionally crashes or expires. Mobilerun restarts it automatically — but only if there's no passcode, otherwise the relaunched session lands on the lock screen and stays stuck until someone unlocks it by hand. If you're around to unlock the device, keep your passcode. For a fully unattended device, turn it off under Settings → Face ID & Passcode → Turn Passcode Off.

Step 3: Build and install WebDriverAgent

Clone Mobilerun's WDA fork:

1git clone --branch v1.1.0 
2https://github.com/droidrun/WebDriverAgent
Copy

(The upstream Appium WebDriverAgent works too, but with higher latency and lower streaming FPS.)

This is the trickiest part of the whole setup — most connection issues later trace back to signing or trust problems here. Take it slow:

1. Open WebDriverAgent.xcodeproj in Xcode
2. Select your connected iPhone as the run destination
3. Choose the WebDriverAgentRunner scheme
4. For both the WebDriverAgentRunner and WebDriverAgentBroadcast targets, open Signing & Capabilities, tick Automatically manage signing, and pick your Apple ID / Team. (WebDriverAgentBroadcast is the extension that enables high-FPS screen streaming — skipping it fails the build.)
5. Press Cmd+U to build-for-testing
6. On the iPhone, trust the certificate: Settings → General → VPN & Device Management → tap your team → Trust

Two common snags:

"Failed to register bundle identifier" — bundle IDs must be unique per Apple ID. Append a suffix to the runner's ID (e.g. com.facebook.WebDriverAgentRunner.<suffix>) and mirror it in the extension: com.facebook.WebDriverAgentRunner.<suffix>.xctrunner.broadcast.

"Could not launch WebDriverAgentRunner" on the first Cmd+U — the certificate isn't trusted yet. Trust it on the device (step 6) and press Cmd+U again.

Step 4: Install the mobilerun-ios CLI

Via Homebrew:

1brew install droidrun/tap/mobilerun-ios
Copy

Or curl:

1curl -fsSL https://media.mobilerun.ai/releases/mobilerun-ios/install.sh | sh
Copy

Verify:

1mobilerun-ios --version
Copy

Step 5: Log in

1mobilerun-ios login
Copy

The CLI prints a short code and opens a verification page in your browser. Approve it, then confirm with mobilerun-ios whoami.

For CI or headless setups, skip the browser flow and use an API key instead:

1export MOBILERUN_IOS_TOKEN=dr_sk_your_api_key
Copy

Step 6: Connect your iPhone

With the iPhone plugged in and unlocked, list your devices:

1mobilerun-ios list
Copy

1UDID                                      NAME             TYPE    OS     STATE    PORTAL
200008020-001A2B3C4D5E6F70                 My iPhone        real    18.2   ready    —
Copy

Copy the UDID and start the connection:

1mobilerun-ios 00008020-001A2B3C4D5E6F70
Copy

Leave the UDID off to connect every attached iPhone. The command keeps the device online for as long as it runs — press Ctrl+C to end the session.

To run in the background instead, pass -d / --detach:

1mobilerun-ios -d 00008020-001A2B3C4D5E6F70
Copy

The CLI prints a PID and log path, then exits. Stop it later with mobilerun-ios stop.

Step 7: Run your first task

Open Devices in the Mobilerun dashboard — your iPhone should appear as a connected Personal Phone. Head to the Playground, select your device, and start a task to confirm end-to-end control. That's it: your iPhone is now driveable by AI agents from anywhere.

Troubleshooting quick hits

WebDriverAgentRunner crashes on launch → re-sign the runner target in Xcode, confirm the certificate is trusted, Cmd+U again

mobilerun-ios list shows no devices → check the cable supports data (not charge-only), the iPhone is unlocked, and you accepted the "Trust This Computer" prompt

Auth failures → re-run mobilerun-ios login; for API keys, verify MOBILERUN_IOS_TOKEN is exported in the same shell

Screen goes black mid-session → Auto-Lock is on; set it to Never

Connection drops after hours, device sits on lock screen → the WDA session restarted but a passcode blocked it; unlock manually, or remove the passcode for unattended setups

One known issue: dumping TikTok's accessibility tree times out and crashes the automation session, avoid TikTok tasks for now.

Wrapping up

That's the full path from a stock iPhone to a cloud-connected automation device: Developer Mode, a one-time WDA build in Xcode, and a single CLI command. The Xcode signing step takes the most patience, but it's a one-time cost (or weekly, on a free Apple ID).

Read the complete documentation here