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. This walkthrough covers mobilerun-ios v0.4.0. For unattended hosts, configuration, and command details, see the Mobilerun iOS reference.
The video shows an earlier setup flow. Follow the written steps below for setup, verify, and signing all bundled WDA extensions.

​
Requirements

  • A Mobilerun account with a Personal Phone subscription.
  • A Mac and an iPhone connected with a data-capable USB cable.
  • Internet access on the host and phone for downloads, activation, and developer-profile validation.
  • For WDA signing: either a paid developer team’s App Store Connect API key, or Xcode with an Apple Account, a development identity, and matching provisioning profiles.
  • For the manual build path: Xcode with support for your iPhone’s iOS version.
WDA is required below iOS 27. On iOS 27+, a phone without an installed runner or saved mode defaults to native control, which does not need WDA signing. Native mode has different feature and video-tunnel requirements; see WDA and native control. For the WDA workflow on any supported version, explicitly use setup --wda.

​
1. Install the CLI

Check the installed version and available commands:
For an existing Homebrew installation, run brew update and brew upgrade droidrun/tap/mobilerun-ios. If using the installer, rerun it to update.
To use 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 accept Trust This Computer. Then list devices:
Copy the device’s UDID for the commands below. Replace <udid> with that identifier. Keep the phone unlocked while completing setup.

​
3. Prepare the device

With one connected phone, you can omit the UDID. With multiple phones, interactive setup offers a picker. The walkthrough handles Developer Mode readiness, developer disk image (DDI) preparation, and WDA signing/installation when required. It skips already-satisfied steps and tells you when an on-device action is necessary. It does not start the cloud portal.

​
Developer Mode and trust

When prompted, enable Settings → Privacy & Security → Developer Mode, allow the restart, unlock the phone, and confirm Turn On. If Developer Mode is not visible, connect the phone to Xcode and check again. For WDA, give the phone internet access and trust the developer profile under Settings → General → VPN & Device Management when prompted. Setup checks that the runner can launch, not just that the app was installed.

​
Choose a WDA signing path

Local Xcode signing: use a keychain identity with provisioning profiles for the runner and all extensions. If those profiles do not exist yet, complete the manual build below, then rerun setup. Personal-team signing has expiry and capability restrictions; do not assume a paid team and a personal team can provision the same extensions/capabilities.

​
Manual Xcode signing and build

Use this path to build WDA yourself or bootstrap the local Xcode profiles. The example pins Mobilerun WDA v1.3.0, whose project includes Broadcast and the opt-in Tunnel extension:
  1. Select your connected iPhone as the run destination. Use WebDriverAgentRunner for ordinary automation and broadcasting, or WebDriverAgentRunnerTunnel for on-device SOCKS5/VPN support. The default scheme deliberately excludes the tunnel extension. For the tunnel scheme, complete the extra build and entitlement steps below first.
  2. Configure the runner and every extension your scheme includes—all three targets for a tunnel-enabled build:
  3. For each included target, open Signing & Capabilities, enable Automatically manage signing, and select the same development team. Ensure the included extensions have valid profiles for the selected phone; they are built and embedded with the runner, not installed as unrelated apps.
  4. If the default bundle identifier is already registered, use a unique base identifier. In Configurations/IOSSettings.xcconfig, update WDA_PRODUCT_BUNDLE_IDENTIFIER, for example to com.example.WebDriverAgentRunner. The runner and extension settings reference this value. Verify the resolved identifiers remain aligned: When passing --bundle-id to the CLI, use the installed runner app identifier, including .xctrunner, not the Xcode test target base.
  5. Press Cmd+U (Product → Test) to build, install, and run the test runner on the phone. This is a test action, not just Build for Testing. The default scheme embeds Broadcast; the tunnel scheme embeds Broadcast and Tunnel.
  6. If launch fails because the developer profile is not trusted, open Settings → General → VPN & Device Management on the phone, trust the developer, and run Cmd+U again. The phone needs internet access for profile validation.
  7. Stop the Xcode test session before letting the CLI own the device. Run setup again:
If signing fails for WebDriverAgentBroadcast or WebDriverAgentTunnel, check that target’s team, bundle prefix, profile, and required capabilities. Signing only the runner is insufficient for its included extensions. The tunnel app extension is not the same as the host-side mobilerun-ios tunnel start command used for native RemoteXPC video.

​
Extra steps for a tunnel-enabled WDA build

The WebDriverAgentRunnerTunnel scheme requires a paid Apple developer team. A free/personal team cannot provision the Network Extension capability. The default scheme remains suitable when you do not need the on-device SOCKS5 tunnel.Before building the tunnel scheme, initialize and build its engine from the WDA checkout:
Enable the Network Extensions / Packet Tunnel capability for the runner and tunnel App IDs in your team’s provisioning configuration. Both the installed host app and tunnel extension must carry com.apple.developer.networking.networkextension with packet-tunnel-provider.In Xcode’s build settings, set these user-defined values for the tunnel build:
Alternatively, after configuring the team and unique bundle base, build the tunnel scheme from the terminal:
This command builds for testing; use Cmd+U with the same scheme/settings to install and run on the phone. A successful build without the entitlements does not prove VPN support: iOS can reject the VPN configuration even when the extension is embedded. First use may also require manual VPN/passcode consent.

​
4. Configure long-lived operation

​
Disable Auto-Lock

Set Settings → Display & Brightness → Auto-Lock → Never. A locked or sleeping phone can interrupt automation and streaming. The separate auto workflow attempts and verifies this setting; do not assume an ordinary setup/portal invocation does it for you.

​
Enable automatic date and time

Set Settings → General → Date & Time → Set Automatically to on. This avoids a manually fixed time zone interfering with location-based behavior; actual automatic time-zone updates also depend on the phone’s settings and connectivity.

​
Decide how to handle unlocking

Keep a passcode on a supervised-use phone and unlock it when required. For a dedicated unattended device, decide whether your security policy permits removing the passcode: a lock screen after a reboot or runner recovery can otherwise require someone to unlock it.
Removing a passcode reduces physical security and affects protected device features. Do not remove it from a daily-use phone just to make automation unattended. Use a dedicated device and an explicit security policy.

​
5. Verify readiness

Before starting a portal, run:
This checks the selected mode’s prerequisites and exits non-zero when something is missing. For WDA, also test that the runner can launch:
Normal verify does not repair the device. --deep is an active WDA launch probe, not a native check or a cloud connectivity test. If the installed runner’s signing has expired, explicitly re-sign and reinstall with your signing backend:
See Setup and verification for all flags and recovery guidance.

​
6. Log in to Mobilerun

Approve the code in the browser. The CLI saves the session token in ~/.mobilerun-ios/config.yaml with owner-only permissions. For headless use, export an API key instead:
mobilerun-ios logout clears the saved token; it does not clear an exported environment token.

​
7. Start the connection

Leave off the UDID to connect all phones attached at startup. Keep the process running; Ctrl+C stops the foreground session. For a prepared native-mode device, use the external-tunnel video workflow. To run a prepared device in the background:
The command prints the PID and log path. Stop a detached portal with mobilerun-ios stop <udid>, or stop all detached portals with mobilerun-ios stop. To watch continuously for USB phones and prepare them as they arrive, stop the existing portal and use Automatic onboarding:
Auto is a separate foreground workflow and may modify newly attached phones. Review its scope and configuration before starting it.

​
8. Confirm end-to-end operation

Open Devices, confirm your iPhone is online, open its stream, and run a task from the Playground. A successful verify command alone does not validate cloud authentication, media transport, or task execution.

​
Troubleshooting

Use a data-capable USB cable, unlock the iPhone, and accept Trust This Computer. Reconnect and run mobilerun-ios list again.
Stop the Xcode test, detached portal (mobilerun-ios stop <udid>), or foreground/auto process before retrying. Wait for it to finish shutting down before retrying.
Check Developer Mode, internet access, and developer trust on the phone. Run verify --deep. If signing has expired, stop the portal and use setup --reinstall with the correct signing flags, or rebuild the runner and all included extensions in Xcode.
WebDriverAgentBroadcast and, for the tunnel scheme, WebDriverAgentTunnel need the same team as the runner and profiles for their correctly prefixed bundle IDs. Check capabilities and profile validity, not just the runner’s signing status.
Run mobilerun-ios whoami, then log in again if needed. If an environment token is set, it overrides the saved login: replace or unset MOBILERUN_IOS_TOKEN as appropriate.
Check Auto-Lock and unlock the device. For unattended use, review the device’s passcode/security policy rather than assuming automatic process recovery can bypass the lock screen.

​
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?

For help, join Discord or email contact@mobilerun.ai. Include your CLI version and failed check, but remove tokens, private keys, and signed artifact URLs from logs.