Setup and verification

setup

mobilerun-ios setup [udid]

setup prepares one connected iPhone so that a portal can serve it. With no UDID, it uses the only connected phone or asks you to pick one. With several phones in a non-interactive session, pass the UDID. Running setup again is safe. It checks each step and skips what is already done. It never erases the phone.

Stop the phone’s portal before you run setup or verify. Only one CLI process can own a phone at a time. Use mobilerun-ios stop <udid> for a detached portal, or Ctrl+C for a foreground portal or auto.

What setup does

Finds and pairs the phone

Setup connects to the phone over USB. On first use, the phone asks you to Trust This Computer. The host keeps its pairing identity in ~/.mobilerun-ios/pairrecords/.

Finishes Setup Assistant, if needed

If the phone is still in Setup Assistant, or was erased, setup can prepare it without erasing it. It activates and supervises the phone, installs the fleet profile with Wi-Fi, and completes Setup Assistant. This needs profile.wifi, supervision_cert, and supervision_key in your configuration. A phone that has finished Setup Assistant skips this step.

Chooses the control mode

Setup chooses WDA or native control and saves the choice for this phone. Phones below iOS 27 use WDA. On iOS 27 and later, a phone with no runner gets native control, and --wda selects WDA.

Enables Developer Mode

On a phone without a passcode, setup turns Developer Mode on, waits for the restart, and confirms it. On a phone with a passcode, iOS requires you to do it: setup shows the Settings → Privacy & Security → Developer Mode switch. Turn it on and tap Restart. After the restart, unlock the phone, tap Turn On, and enter your passcode. You do not need Xcode for this step.

Mounts the developer disk image

The developer disk image (DDI) contains the developer services that automation needs. For iOS 17 and later, setup uses Xcode’s image or downloads one. It has Apple personalize the image for this phone, then mounts it. For iOS 16, it mounts the classic image. Downloads are cached in ~/.mobilerun-ios/devimages/.

Signs and installs WDA (WDA mode only)

Setup downloads the prebuilt Mobilerun runner and signs it for this phone with Xcode or App Store Connect. Then it installs it. If iOS asks, trust the developer in Settings → General → VPN & Device Management. Setup then launches the runner to prove that iOS accepts it. An installed Mobilerun runner is kept and not signed again. Use --reinstall to renew it.

Checks the result

Setup runs the same checks as verify and reports what is ready. It does not log in and does not start a portal.

Setup cannot tap on-phone prompts for you, such as trust, unlock, and confirmations. In an interactive terminal it waits for you. With --non-interactive, it stops and tells you which action is needed.

Flags

Flag	Default	Behavior
`--wda`	Automatic mode	Select and save WDA, also on iOS 27 and later.
`--wda=false`	Automatic mode	Select native control explicitly. Fails if the phone cannot support it.
`--reinstall`	`false`	Sign and install WDA again even if a runner is installed. Implies `--wda`; cannot be combined with `--wda=false`.
`--backend`	`signing.backend`, else ask	`asc` (App Store Connect) or `xcode`.
`--account`	`signing.account`, else the only account or ask	Name of a `signing.accounts` entry. Implies `--backend asc`.
`--identity`	`signing.identity`, else the only identity or ask	Keychain identity: SHA-1 fingerprint, Apple account, or full name. Implies `--backend xcode`.
`--wda-bundle-id`	`wda.bundle_id`, else derived	Runner bundle identifier to sign and launch. Must contain `WebDriverAgentRunner` and end in `.xctrunner`.
`--wda-unsigned-url`	`wda.unsigned_url`	Runner ZIP or IPA to sign and install.
`--wda-signed-url`	`wda.signed_url`	Pre-signed IPA to install as is. Used only when no signing backend is selected.
`--ddi-path`	`ddi_path`	Local developer disk image `Restore` directory.
`--ddi-url`	`ddi_url`	Base URL for downloading developer disk images.
`--non-interactive`	`false`	Fail instead of asking a question or waiting for an on-phone action.

Global flags: --log-level, --verbose / -v, and --tunnel-mode. v0.4.x users: --runner-url and --bundle-id are now --wda-unsigned-url and --wda-bundle-id; see Migrate to v0.5.0.

Examples

# Guided setup of the only connected phone
mobilerun-ios setup

# WDA, signed with your Apple Account through Xcode
mobilerun-ios setup <udid> --wda --backend xcode

# WDA, signed with a configured App Store Connect account
mobilerun-ios setup <udid> --wda --backend asc --account automation

# Renew an expired runner without prompts
mobilerun-ios setup <udid> --reinstall --non-interactive

# Install the VPN tunnel runner (paid team)
mobilerun-ios setup <udid> --reinstall --backend asc \
  --wda-unsigned-url https://github.com/droidrun/WebDriverAgent/releases/latest/download/WebDriverAgentRunnerTunnel-Runner.zip

Control-mode persistence

Setup saves the selected mode in ~/.mobilerun-ios/devices/<udid>.json, not in config.yaml. verify, portals, auto, macro, and reset use the saved mode. Without a saved mode, phones below iOS 27 use WDA. On iOS 27 and later, an installed runner keeps WDA; otherwise the phone gets native control. MOBILERUN_IOS_REMOTE_XPC_ONLY=true forces native control and false forces WDA, ahead of the saved mode. Setup rejects a --wda choice that conflicts with this variable. Unset it, or make it match, before you change the saved mode.

verify

mobilerun-ios verify <udid>

verify checks one phone and prints a table. It exits non-zero if something is missing or cannot be checked. It does not repair anything. It checks the same mode that setup saved:

Device identity and Developer Mode.
Mounted developer disk image.
In WDA mode: the runner is installed.
In native mode: the native services and device capabilities. If a prerequisite is missing, native readiness shows not checked. That does not mean the phone cannot use native control.

Flag	Default	Behavior
`--wda`	`false`	Require WDA even if the phone’s mode is native. Does not change the saved mode.
`--deep`	`false`	Require WDA and launch the runner, to prove that it is signed and trusted, not only installed.

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

Plain verify only shows that the runner is installed. Use --deep to prove that it launches. --deep starts the runner and stops it again; a runner that is already running is left alone. Neither check tests cloud login, the browser stream, or a task. Confirm those in the dashboard.

When verification fails

Check or symptom	Next action
No device, or host not trusted	Unlock the phone, reconnect a USB data cable, and accept Trust This Computer.
Developer Mode off	Run `setup` and complete the restart and Turn On confirmation.
Developer disk image missing	Run `setup`. If it cannot find an image, pass `--ddi-path` or `--ddi-url`. On Linux, the host must trust Apple’s root certificate for personalization. Setup tells you when it does not.
Runner missing	Run `setup --wda` with a signing backend.
Runner installed but does not launch	Give the phone internet access and trust the developer profile. If the signature has expired, run `setup --reinstall`.
Device already owned	Stop its portal or `auto` process, then try again.
Native services unavailable	Fix the developer disk image first. If the phone cannot use native control, select WDA with `setup --wda`.

After a repair, run verify again, start the portal, and confirm streaming and a task in the dashboard.

Get started

Phones

Apps & networking

Run automation

Integrations

Developer tools

Setup and verification

setup

What setup does

Flags

Examples

Control-mode persistence

verify

When verification fails

​setup

​What setup does

​Flags

​Examples

​Control-mode persistence

​verify

​When verification fails

setup

What setup does

Flags

Examples

Control-mode persistence

verify

When verification fails