Setup and verification

setup

mobilerun-ios setup [udid]

setup prepares one connected iPhone. With no UDID, it selects the sole connected device or opens an interactive picker. With multiple phones in a non-interactive session, pass the UDID explicitly. The walkthrough checks and repairs prerequisites in order: Developer Mode, a compatible developer disk image (DDI), and—when WDA is selected—the runner’s signing, installation, and ability to launch. It handles reconnects around Developer Mode changes, but cannot accept on-device trust, unlock, or confirmation prompts for you. A rerun skips satisfied steps. In particular, an installed Mobilerun runner is not automatically re-signed. If its signature has expired, use --reinstall.

Stop the device’s portal before running setup or verify. Only one setup or portal session can use the device at a time. Use mobilerun-ios stop <udid> for a detached portal, or stop the foreground process with Ctrl+C.

Flags

Flag	Default	Behavior
`--wda`	Automatic mode selection	Select and save WDA, including on iOS 27+.
`--wda=false`	Not explicitly set	Explicitly select native control; fails if native prerequisites are unsupported.
`--reinstall`	`false`	Re-sign and reinstall WDA even if already installed; implies `--wda`. Cannot be combined with `--wda=false`.
`--backend`	Interactive choice or ASC fallback	`asc` for App Store Connect; `xcode` for a local macOS signing identity.
`--account`	Picker, or sole configured account	Name from `signing_accounts`; implies ASC when no backend is supplied.
`--identity`	Picker, or sole local identity	SHA-1 fingerprint, Apple account, or full keychain identity name; implies Xcode when no backend is supplied.
`--bundle-id`	Existing custom runner ID or derived account/team ID	Installed runner identifier; must contain `WebDriverAgentRunner` and end in `.xctrunner`.
`--runner-url`	`runner_url` configuration	Runner download to sign and install; accepts an IPA or runner ZIP.
`--ddi-path`	`ddi_path` configuration	Local developer image `Restore` directory. Otherwise use Xcode’s image or a download.
`--ddi-url`	`ddi_url` configuration	Developer image download base URL.
`--non-interactive`	`false`	Fail rather than open a picker or wait for manual confirmation.

--log-level, --verbose / -v, and --tunnel-mode are inherited global flags. See Configuration for their environment equivalents.

Examples

# Guided preparation
mobilerun-ios setup

# Explicit WDA with a configured signing account
mobilerun-ios setup <udid> --wda --backend asc --account automation

# Repair an expired runner, without a terminal picker
mobilerun-ios setup <udid> --reinstall --backend asc \
  --account automation --non-interactive

# Use a local Xcode identity and a matching installed-app bundle ID
mobilerun-ios setup <udid> --wda --backend xcode \
  --identity 'Apple Development: Your Name (TEAMID)' \
  --bundle-id com.example.WebDriverAgentRunner.xctrunner

Non-interactive setup is not a way around Apple device prompts. Complete host trust, Developer Mode confirmation, and developer trust on the phone before expecting unattended success.

Control-mode persistence

The selected mode is stored in ~/.mobilerun-ios/devices/<udid>.json, not in config.yaml. Without a saved choice, versions below iOS 27 use WDA; iOS 27+ preserves an installed runner or selects native control when none exists. MOBILERUN_IOS_REMOTE_XPC_ONLY=true selects native control; false selects WDA. An explicit setup mode that conflicts with this environment override is rejected. Unset or align the environment variable before changing the saved choice. See native operation for the video tunnel and feature limitations.

verify

mobilerun-ios verify <udid>

verify requires exactly one UDID. It prints a check table and exits non-zero if readiness is incomplete or cannot be determined. It does not repair Developer Mode, mount a missing DDI, or install a runner. Checks follow the same saved/default mode as setup:

Device identity and Developer Mode.
Mounted developer disk image.
Runner presence in WDA mode.
Required native services and device capabilities in native mode. If prerequisites are missing, native readiness is reported as not checked, not as proof that native control is unsupported.

Flag	Default	Behavior
`--wda`	`false`	Require WDA even if the normal mode is native. Does not change the saved choice.
`--deep`	`false`	Require WDA and probe whether its runner can launch, checking more than installation alone.

mobilerun-ios verify <udid>
mobilerun-ios verify <udid> --wda
mobilerun-ios verify <udid> --deep

Normal verification checks readiness without repairing the device. --deep is an active launch probe: it may start the runner and clean up that probe process. An already-running runner is preserved. It is not a native-mode deep check and does not test cloud authentication, browser decoding, or end-to-end task execution.

When verification fails

Check or symptom	Next action
No device / host trust	Unlock, reconnect a data-capable USB cable, and accept Trust This Computer.
Developer Mode disabled	Run setup and complete the phone’s reboot and Turn On confirmation.
DDI missing or incompatible	Run setup; check Xcode/image compatibility or supply `--ddi-path` / `--ddi-url`.
Runner missing	Run setup with `--wda` and a valid signing backend.
Runner installed but cannot launch	Give the phone internet access and trust the developer profile. For expired signing, explicitly run `setup --reinstall`.
Device already owned	Stop its existing portal or auto process before retrying.
Native services unavailable	Resolve DDI readiness first. If the device cannot support native control, explicitly choose WDA.

After repairs, rerun verification, start the portal, then confirm streaming and a task in the cloud dashboard.

Introduction

Concepts

Guides

Mobilerun iOS

Assistant

Dashboard

Agent Skills

Integrations

Setup and verification

setup

Flags

Examples

Control-mode persistence

verify

When verification fails

​setup

​Flags

​Examples

​Control-mode persistence

​verify

​When verification fails

setup

Flags

Examples

Control-mode persistence

verify

When verification fails