Skip to main content
mobilerun-ios runs on the host that your iPhone is connected to. It prepares the phone, then gives Mobilerun cloud control of its screen and input. It can also serve a local HTTP portal instead. This reference covers mobilerun-ios v0.5.0. Check your version with mobilerun-ios --version, and a command’s options with mobilerun-ios <command> --help. For your first phone, follow Connect an iPhone.
Upgrading from v0.4.x? Signing and runner settings have new names, and the old ones are ignored. Read Migrate to v0.5.0 first.

​
Requirements

  • Host: macOS, or Linux with usbmuxd. Xcode signing needs macOS. App Store Connect signing and native control also work on Linux.
  • iPhone: iOS 16 or later. iOS 16 to 26 use WDA. iOS 27 and later can also use native control.
  • FFmpeg 8, for native audio, recordings, and the H.264 browser fallback. Homebrew installs ffmpeg@8 with the CLI. The installer adds it when Homebrew is available.

​
Choose a workflow

Setup and verification

What setup does, its flags, control modes, and readiness checks.

WDA signing

Xcode and App Store Connect signing, and how to renew it.

Configuration

Every config.yaml key, environment overrides, and runtime tuning.

Automatic onboarding

USB discovery, concurrency, factory-state onboarding, and recovery.

​
Connect and operate

Replace <udid> with the identifier from list. setup does not log in or connect to the cloud. A passing verify shows that the prerequisites are in place; it does not prove that cloud streaming works. Check that the phone is online in the dashboard, and run a task.

​
Background portals

Detached portals write PID and log files to ~/.mobilerun-ios/portals/. stop without a UDID stops all detached portals. Stop foreground sessions, including auto, with Ctrl+C or SIGTERM.

​
Reconnects

When the cloud connection drops, the portal reconnects with exponential backoff. Foreground portals allow five attempts per serving cycle, and detached portals allow up to 30 minutes. Change this with --retry-attempts, --retry-duration, --retry-base-delay, and --retry-max-delay. A value of 0 for attempts or duration removes that limit. When a cycle runs out of attempts, the CLI rebuilds that phone’s portal, with a delay from 5 seconds up to 5 minutes. The other phones keep running. Authentication failures stop the phone instead, because retrying cannot fix them. Run whoami, log in again, or replace the API key.

​
Local HTTP portal

Local mode needs no Mobilerun login. With several phones, the port goes up by one for each phone. To listen beyond loopback, set a bearer token:
Clients send Authorization: Bearer <token>. This endpoint controls the phone. Keep it on a trusted network and never expose it to the internet.

​
WDA and native control

mobilerun-ios controls a phone in one of two modes:
  • WDA: WebDriverAgent, a test runner signed for your Apple team, runs on the phone. It works on iOS 16 and later, and supports every feature. Setup signs and installs it for you.
  • Native: on iOS 27 and later, the CLI uses Apple’s built-in developer services. Nothing is installed on the phone, so no signing is needed.
Setup chooses the mode and saves it for each phone:
  • Below iOS 27: WDA.
  • iOS 27 and later: native, unless a runner is already installed. To select WDA, run mobilerun-ios setup <udid> --wda.
Both modes need Developer Mode and a mounted developer disk image. Native control supports touch, text, hardware buttons, screenshots, the accessibility tree, the clipboard, app management, deep links that name an app, location, video, and system audio. The following do not work in native mode yet: deep links without an app, the on-device proxy, and the virtual /mobilerun app folder. Native mode streams even while the phone is locked, so Auto-Lock can stay on. Native video needs a privileged tunnel process. Run only the tunnel with sudo. Run the portal as your normal user, so it uses your login and configuration:
Terminal 1
Terminal 2
The default userspace tunnel is enough for input, but use this external-tunnel layout for video. The host tunnel has nothing to do with the VPN extension in the tunnel-enabled WDA runner.

​
Other commands

Run mobilerun-ios --help for the full list.
mobilerun-ios reset <udid> erases all data on the phone. Then it supervises the phone, installs the fleet profile, and installs the saved control mode, signing WDA if needed. It needs the fleet profile, the supervision identity, and signing configuration (or wda.signed_url) for WDA phones. It asks for confirmation; pass --yes for non-interactive runs. It refuses to run while a portal or auto owns the phone. To repair a runner, use setup --reinstall, not reset.