Skip to main content
Use mobilerun-ios to connect your own iPhone to Mobilerun and run tasks from the Playground or API. Once connected, it appears as a Personal Phone on the Devices page. One command, mobilerun-ios setup, prepares the phone. It enables Developer Mode, mounts the developer disk image, and signs and installs WebDriverAgent (WDA) with your Apple account. You do not build anything in Xcode. This walkthrough covers mobilerun-ios v0.5.0. Upgrading from v0.4.x? Read Migrate to v0.5.0 first: some settings and flags were renamed. For unattended hosts and every option, see the CLI reference.
The video shows an earlier version of the setup flow. Where it differs, follow the written steps below.

​
Requirements

  • A Mobilerun account with a Personal Phone subscription.
  • An iPhone on iOS 16 or later, and a USB data cable.
  • A Mac. A Linux host with usbmuxd also works with App Store Connect signing.
  • Internet access on the host and on the phone.
  • An Apple account to sign WDA. Either:
    • Xcode: any Apple Account, free or paid, signed in to Xcode on the Mac.
    • App Store Connect: an API key from a paid Apple Developer Program team.
On iOS 27 and later, the CLI can control the phone with Apple’s built-in services instead of WDA. This is called native control. Native control needs no Apple account or signing. See WDA and native control.

​
1. Install the CLI

Homebrew also installs FFmpeg 8, which the CLI needs for audio, recordings, and the H.264 browser fallback. The installer adds it through Homebrew when Homebrew is available, and otherwise tells you how to install it. Check the installed version:
To update, run brew update && brew upgrade droidrun/tap/mobilerun-ios, or rerun the installer.
To install into a user-writable directory with the installer:
Make sure $HOME/.local/bin is on your PATH.

​
2. Connect and trust the iPhone

Unlock the phone, connect it over USB, and tap Trust on Trust This Computer. Then list devices:
Copy the phone’s UDID and use it for <udid> in the commands below. Keep the phone unlocked during setup.

​
3. Run setup

Prepare your signing account first, then run mobilerun-ios setup. Choose the tab for your account:
Use this path for your own phone with any Apple Account, free or paid.
  1. Install Xcode from the Mac App Store. Open it once and let it install its components.
  2. In Xcode, open Settings → Accounts, click +, choose Apple Account, and sign in.
  3. Run setup:
  4. When setup suggests a runner bundle identifier, press Enter to accept it.
  5. Follow the prompts on the phone (see What to expect on the phone).
Setup uses Xcode for your signing certificate and for Apple’s automatic provisioning. It does not build WDA in Xcode. Step by step, setup:
  • Picks the Apple Development certificate that Xcode created in your keychain. If there is none yet, setup opens Xcode and waits while you sign in.
  • Downloads the prebuilt Mobilerun WDA runner.
  • Gets a provisioning profile for the runner and its screen-broadcast extension. If none exists, setup has Xcode create one: Xcode registers your iPhone and the app identifier on your team.
  • Signs the runner on your Mac with that certificate. Your private key never leaves the keychain.
  • Installs the runner and checks that it launches.
With a free Apple Account, Apple’s signing expires after 7 days. After that, the runner no longer launches. Renew it with mobilerun-ios setup <udid> --reinstall --backend xcode. A paid team’s signing lasts a year.
On iOS 27 and later, setup picks native control by default and skips signing. To use WDA there, add --wda to the setup command. With only one phone connected, you can leave out the UDID. Running setup again is safe: it skips the steps that are done. For every step and flag, see What setup does.

​
What to expect on the phone

Setup waits while you do these steps:
  • Developer Mode. If the phone has a passcode, open Settings → Privacy & Security → Developer Mode, turn it on, and tap Restart. After the restart, unlock the phone, tap Turn On, and enter your passcode. Without a passcode, setup turns Developer Mode on by itself.
  • Developer trust. The first time, iOS can block the new runner. Open Settings → General → VPN & Device Management, select your developer account, and tap Trust. The phone needs internet access for iOS to check the developer with Apple.

​
4. Configure the phone for long sessions

​
Turn off Auto-Lock

Set Settings → Display & Brightness → Auto-Lock to Never. In WDA mode, a locked phone interrupts automation and streaming. setup does not change this setting. In native mode this is optional: a locked phone still streams and can be unlocked through the stream or API.

​
Set date and time automatically

Turn on Settings → General → Date & Time → Set Automatically. A fixed manual time zone can interfere with location-based behavior.

​
Decide how to handle unlocking

Keep a passcode on a phone you also use day to day, and unlock it when needed. For a dedicated automation phone, decide whether your security policy allows removing the passcode. Otherwise, someone has to unlock the phone after every restart.
Removing a passcode reduces physical security and turns off some protected features. Do not remove it from a daily-use phone just to run automation unattended.

​
5. Verify the phone

verify checks Developer Mode, the developer disk image, and the runner. It exits non-zero if something is missing. --deep also launches the runner to prove that iOS accepts its signature. Without --deep, verify checks only that the runner is installed. For a native-mode phone, run mobilerun-ios verify <udid>. If the signature has expired, renew it:

​
6. Log in to Mobilerun

Approve the code in the browser. The CLI saves the session token in ~/.mobilerun-ios/config.yaml, readable only by you. On a headless host, export an API key instead:
mobilerun-ios logout clears the saved token, but not an exported MOBILERUN_IOS_TOKEN.

​
7. Start the connection

Leave out the UDID to connect all phones attached at startup. Keep the process running. Ctrl+C stops it. For video in native mode, use the external-tunnel layout. To run in the background instead:
The command prints the PID and the log path. Stop it with mobilerun-ios stop <udid>, or stop all background portals with mobilerun-ios stop. To prepare and serve phones automatically as you connect them, use Automatic onboarding (mobilerun-ios auto). It changes the phones it finds, so read that page first.

​
8. Confirm it works

Open Devices, check that your iPhone is online, open its stream, and run a task from the Playground. A passing verify does not test cloud login, the stream, or tasks.

​
Troubleshooting

Use a USB cable that carries data, unlock the iPhone, and accept Trust This Computer. Reconnect and run mobilerun-ios list again. On Linux, check that usbmuxd is running.
Another process owns the phone: a detached portal (mobilerun-ios stop <udid>), a foreground portal, or auto. Stop it, wait for it to exit, and try again.
Open Xcode → Settings → Accounts and check that your Apple Account is signed in. Select it, open Manage Certificates, and add an Apple Development certificate. Run setup as the same macOS user that owns the keychain.
App identifiers are unique across all Apple teams, and another team registered this one. Accept the identifier that setup suggests, or pass your own with --wda-bundle-id. It must contain WebDriverAgentRunner and end in .xctrunner.
Check Developer Mode, the phone’s internet access, and the developer trust under Settings → General → VPN & Device Management. Run mobilerun-ios verify <udid> --deep. If the signature has expired (after 7 days with a free account), run mobilerun-ios setup <udid> --reinstall.
v0.5.0 renamed the signing and runner keys and the --runner-url and --bundle-id flags. The old keys are ignored. See Migrate to v0.5.0.
Run mobilerun-ios whoami, and log in again if needed. An exported MOBILERUN_IOS_TOKEN overrides the saved login, so replace or unset it.
Check that Auto-Lock is set to Never, and unlock the phone. The CLI cannot get past a passcode lock screen after a restart.

​
Known issues

  • TikTok crashes automation. Reading TikTok’s accessibility tree times out, and this crashes the Mobilerun automation session. Avoid tasks that use the TikTok app for now.

​
Need help?

Join Discord or email contact@mobilerun.ai. Include your CLI version and the failed check. Remove tokens, private keys, and signed download URLs from logs.