Skip to main content
Use the mobilerun-ios CLI to connect your own iPhone to Mobilerun so it can run tasks from the Playground or API. This guide is for developers with a Mac, Xcode, and an iPhone they can plug in over USB. Once connected, the iPhone shows up as a Personal Phone on the Devices page.

​
Requirements

  • A Mobilerun account with a Personal Phone subscription
  • macOS with Xcode installed
  • An iPhone connected via USB
  • An Apple ID with signing capability (personal team is fine)
Signing with a personal / free team comes with Apple-imposed limits: builds expire after 7 days, after which you need to rebuild in Xcode and re-trust the certificate on the device, and you can sign for at most 3 devices. A paid Apple Developer account ($99/year) lifts both limits.

​
1. Enable Developer Mode on your iPhone

Developer Mode lets Xcode install and launch development builds (like WebDriverAgent) on your device.
  1. On the iPhone, open Settings → Privacy & Security → Developer Mode.
  2. Toggle Developer Mode on.
  3. Restart the iPhone when prompted, then confirm the prompt after it boots.
The Developer Mode entry only appears after the iPhone has been connected at least once to a Mac running Xcode. If you don’t see it, plug the device in, open Xcode, then check Settings again.

​
2. Configure your iPhone for long-lived connections

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

​
Disable Auto-Lock

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

​
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. Writing the time zone manually does not work on non-jailbroken devices, so automatic time zone is the only reliable way to keep it matching the location.

​
Remove the passcode (for unattended 24/7 setups)

Only do this if you plan to leave the device running around the clock with nobody nearby to unlock it. For supervised use, keep your passcode and skip this. After running for a while, the XCTest session that hosts WebDriverAgent crashes or expires and has to be restarted. Mobilerun restarts it automatically — but only if the device has no passcode. With a passcode set, the relaunched session lands on the lock screen and the connection stays down until someone enters the passcode by hand. If you’re around to unlock the device when that happens, you don’t need to remove it. For a fully unattended device, turn the passcode off under Settings → Face ID & Passcode → Turn Passcode Off.
Removing the passcode also disables Face ID, Apple Pay, and some iCloud features. Use a dedicated automation device rather than your daily phone.

​
3. Download Mobilerun WebDriverAgent

Mobilerun controls your iPhone through WebDriverAgent (WDA), an open-source project that exposes input injection and screenshots on iOS. We maintain our own fork, Mobilerun WebDriverAgent, tuned for exactly this job: higher-quality streaming, lower-latency accessibility tree fetching and touch input, with more features landing over time. Clone it:
The upstream Appium WebDriverAgent works too, but with higher latency and lower streaming FPS.

​
4. Build and install WebDriverAgent on your iPhone with Xcode

This is the trickiest step. Take it slow — most connection issues later on trace back to signing or trust problems here.
  1. Open WebDriverAgent.xcodeproj in Xcode.
  2. In the top bar, select your connected iPhone as the run destination.
  3. Choose the WebDriverAgentRunner scheme.
  4. Set up signing for the runner and its extension target. For both WebDriverAgentRunner and WebDriverAgentBroadcast, select the target, open the Signing & Capabilities tab, and:
    • Tick Automatically manage signing.
    • Pick your Apple ID / Team from the dropdown.
    WebDriverAgentBroadcast is an app extension that ships inside the runner app — it’s what enables high-FPS screen streaming. It builds and embeds automatically; it just needs a team selected so Xcode can sign it. Skipping it fails the build with “Signing for ‘WebDriverAgentBroadcast’ requires a development team.”
    If Xcode shows “Failed to register bundle identifier,” the Bundle Identifier needs to be unique per Apple ID. Append a suffix to the WebDriverAgentRunner target’s bundle ID (e.g. your initials: com.facebook.WebDriverAgentRunner.<suffix>) and mirror it in the extension target, keeping its suffix pattern intact: WebDriverAgentBroadcast → com.facebook.WebDriverAgentRunner.<suffix>.xctrunner.broadcast.If the extension ID doesn’t follow the runner’s, the app installs with an extension whose provisioning profile no longer matches, and iOS rejects the install.
  5. Press Cmd+U to build-for-testing. Xcode builds the runner with the extension embedded and installs it onto the iPhone.
  6. On the iPhone, trust the developer certificate: Settings → General → VPN & Device Management → tap your team → Trust.
The first Cmd+U run often fails with “Could not launch WebDriverAgentRunner” because the certificate isn’t trusted yet. Trust the certificate on the device (step 6) and press Cmd+U again.

​
5. Install the mobilerun-ios CLI

Pick whichever you prefer:
Both fetch the latest release, verify the checksum, and drop the binary on your PATH (brew puts it in the Homebrew prefix; the curl installer uses /usr/local/bin and may prompt for sudo).
To install into a user-writable directory with the curl installer, override BINDIR:
Verify the install:

​
6. Log in to Mobilerun

The CLI prints a short code and opens the verification page in your browser. Approve the code and the CLI stores the session token under ~/.mobilerun-ios/config.yaml (chmod 0600). Confirm with:
Run mobilerun-ios logout to clear the stored token.
For CI/headless setups where opening a browser isn’t possible, skip login and export an API key from the API Keys tab instead:

​
7. List your connected iPhones

With the iPhone plugged in and unlocked, list everything mobilerun-ios can see:
Copy the UDID of the device you want to connect. The PORTAL column shows running (pid=…) once a background portal is up (see below).

​
8. Start the connection

Connect the iPhone by passing its UDID:
Leave the UDID off to connect every attached iPhone:
The command opens a WebSocket to Mobilerun cloud and keeps the device online for as long as it runs. Press Ctrl+C to end the session.

​
Run in the background

Pass -d / --detach to release the terminal while the portal stays up:
The CLI prints a PID and log path, then exits. mobilerun-ios list shows the portal as running in the PORTAL column. Stop it later with:
Or mobilerun-ios stop (no UDID) to stop every background portal.

​
Verify it worked

Open Devices in the Mobilerun dashboard — your iPhone should show up as a connected Personal Phone. Start a task from the Playground and select it to confirm end-to-end control.

​
Troubleshooting

The CLI surfaces this as:
Re-sign the WebDriverAgentRunner target in Xcode and make sure the developer certificate is trusted under Settings → General → VPN & Device Management, then press Cmd+U again.
Confirm your USB cable supports data (not charging-only), the iPhone is unlocked, and you accepted the Trust This Computer prompt.
Re-run mobilerun-ios login and confirm with mobilerun-ios whoami. For API-key setups, verify the token in the API Keys tab and that MOBILERUN_IOS_TOKEN is exported in the same shell.
Auto-lock put the device to sleep. Disable it under Settings → Display & Brightness → Auto-Lock → Never while the iPhone is connected to Mobilerun (see step 2).
The XCTest session hosting WebDriverAgent expired and was restarted, but a passcode is blocking the relaunch. Unlock the device to let the session reconnect. For an unattended 24/7 device where no one is around to do that, remove the passcode (see step 2) so the session can heal itself automatically.

​
Known issues

  • TikTok crashes automation. Dumping TikTok’s accessibility tree times out, which crashes the Mobilerun automation session. Avoid tasks that drive the TikTok app for now.

​
Need Help?

If you run into any issues or need further assistance, reach out to us: