Migrate to v0.5.0

v0.5.0 groups all WDA runner and signing settings under two YAML sections, wda: and signing:, and renames the matching setup flags. There are no compatibility aliases. Update every host’s configuration before or right after you upgrade, from v0.4.0 through v0.4.3.

v0.5.0 ignores the old keys without a warning and falls back to defaults, and the removed flags fail with Error: unknown flag. See Configuration keys and Setup flags for the new names.

Upgrade checklist

Stop everything that owns a phone

Stop detached portals with mobilerun-ios stop. Stop foreground portals and auto with Ctrl+C and wait for them to exit. Do not run v0.4.x and v0.5.0 against the same phone at the same time: the older binary does not honor the new device-ownership lock.

Finish pending factory onboardings

If auto or reset is part-way through preparing a factory-state phone, let it finish before you upgrade. v0.5.0 does not resume a checkpoint written by v0.4.x: it stops with checkpoint written by an older version. If that happens, remove the phone’s directory under ~/.mobilerun-ios/onboarding/ and prepare the phone again.

Find the old settings

Run both checks. Any output is a setting that v0.5.0 ignores.

grep -nE '^(runner_url|bundle_id|wda_ipa_url|backend|account|identity|signing_accounts):' \
  ~/.mobilerun-ios/config.yaml

env | grep -E '^MOBILERUN_IOS_(RUNNER_URL|BUNDLE_ID|WDA_IPA_URL|BACKEND|ACCOUNT|IDENTITY)='

Also search your scripts, launchd/systemd units, and CI jobs for --runner-url and --bundle-id.

Rename them

Move each setting to its new key, environment variable, or flag. See Configuration keys, Environment variables, and Setup flags.

Upgrade and check

brew update && brew upgrade droidrun/tap/mobilerun-ios
mobilerun-ios --version
mobilerun-ios verify <udid>

Installer users rerun the install script instead. Rerun the two checks from the previous step; both must print nothing. When the CLI next signs a runner, it logs the backend, Apple account or identity, and runner bundle identifier it chose. Check that they match your configuration.

Configuration keys

Change these keys in ~/.mobilerun-ios/config.yaml. The values and their meaning stay the same. Until you do, the CLI signs the default runner with a derived bundle ID, finds no App Store Connect accounts, and skips your pre-signed runner.

v0.4.x key	v0.5.0 key	Purpose
`runner_url`	`wda.unsigned_url`	Runner ZIP or IPA that the CLI signs before it installs it.
`wda_ipa_url`	`wda.signed_url`	Runner IPA that is already signed for the phone.
`bundle_id`	`wda.bundle_id`	Runner bundle identifier, now used to sign and to launch.
`backend`	`signing.backend`	Signing backend: `asc` or `xcode`.
`account`	`signing.account`	Name of the App Store Connect account to use.
`identity`	`signing.identity`	Keychain identity for Xcode signing.
`signing_accounts`	`signing.accounts`	List of App Store Connect API keys. Fields are unchanged: `name`, `key_id`, `issuer_id`, `p8_path`.

runner_url: https://github.com/droidrun/WebDriverAgent/releases/download/v1.3.1/WebDriverAgentRunner-Runner.zip
bundle_id: com.example.WebDriverAgentRunner.xctrunner
backend: asc
account: automation
signing_accounts:
  - name: automation
    key_id: YOUR_KEY_ID
    issuer_id: YOUR_ISSUER_ID
    p8_path: /Users/you/.mobilerun-ios/keys/AuthKey_YOUR_KEY_ID.p8

wda:
  unsigned_url: https://github.com/droidrun/WebDriverAgent/releases/download/v1.3.1/WebDriverAgentRunner-Runner.zip
  bundle_id: com.example.WebDriverAgentRunner.xctrunner
signing:
  backend: asc
  account: automation
  accounts:
    - name: automation
      key_id: YOUR_KEY_ID
      issuer_id: YOUR_ISSUER_ID
      p8_path: /Users/you/.mobilerun-ios/keys/AuthKey_YOUR_KEY_ID.p8

Keep token, remote_url, auth_url, ddi_path, ddi_url, supervision_cert, supervision_key, and the reset_* keys as they are.

Environment variables

Nested keys map to environment variables in upper case, with dots replaced by underscores.

v0.4.x variable	v0.5.0 variable
`MOBILERUN_IOS_RUNNER_URL`	`MOBILERUN_IOS_WDA_UNSIGNED_URL`
`MOBILERUN_IOS_WDA_IPA_URL`	`MOBILERUN_IOS_WDA_SIGNED_URL`
`MOBILERUN_IOS_BUNDLE_ID`	`MOBILERUN_IOS_WDA_BUNDLE_ID`
`MOBILERUN_IOS_BACKEND`	`MOBILERUN_IOS_SIGNING_BACKEND`
`MOBILERUN_IOS_ACCOUNT`	`MOBILERUN_IOS_SIGNING_ACCOUNT`
`MOBILERUN_IOS_IDENTITY`	`MOBILERUN_IOS_SIGNING_IDENTITY`

signing.accounts is a list. Set it in YAML, not in an environment variable.

`MOBILERUN_IOS_WDA_BUNDLE_ID` changed meaning

In v0.4.x, MOBILERUN_IOS_WDA_BUNDLE_ID and the portal’s --wda-bundle-id only picked which installed runner to launch. In v0.5.0 the same value, and wda.bundle_id, is also the identifier that setup, auto, and reset sign and install. If you set it only to pick a launch target, make sure it is the identifier you want to provision too, or remove it and let the CLI discover the runner.

Setup flags

v0.4.x flag	v0.5.0 flag
`--runner-url <url>`	`--wda-unsigned-url <url>`
`--bundle-id <id>`	`--wda-bundle-id <id>`
(none)	`--wda-signed-url <url>`: install an IPA that is already signed, when no signing backend is selected

# v0.4.x
mobilerun-ios setup <udid> --reinstall --backend xcode \
  --bundle-id com.example.WebDriverAgentRunner.xctrunner

# v0.5.0
mobilerun-ios setup <udid> --reinstall --backend xcode \
  --wda-bundle-id com.example.WebDriverAgentRunner.xctrunner

--backend, --account, --identity, --ddi-path, --ddi-url, --wda, --reinstall, and --non-interactive are unchanged.

Other changes that need action

setup reads the signing selection from config

In v0.4.x, only auto read backend, account, and identity from YAML. In v0.5.0, setup, auto, and reset all read signing.backend, signing.account, and signing.identity. If these are set, interactive setup uses them without asking. Pass --backend, --account, or --identity to override them for one run. If signing.* selects a backend, the CLI signs even when wda.signed_url is set, and it logs that choice. A signing error never falls back to the pre-signed artifact. See Runner source precedence.

reset no longer requires a pre-signed runner

reset used to require wda_ipa_url. It now uses the same signing pipeline as setup: your signing.* configuration, or wda.signed_url when no signing backend is selected. Before it erases the phone, it checks the local signing prerequisites. It also keeps the phone’s saved control mode, so a native-mode phone is not given a WDA runner.

Wi-Fi settings moved into the fleet profile (deprecated, still work)

wifi_ssid, wifi_password, and wifi_enc_type still work in v0.5.0, but they log a deprecation warning at startup. Move them into the new profile: section:

Deprecated key	New key
`wifi_ssid`	`profile.wifi.ssid`
`wifi_password`	`profile.wifi.password`
`wifi_enc_type`	`profile.wifi.encryption`
`MOBILERUN_IOS_WIFI_PASSWORD`	`MOBILERUN_IOS_PROFILE_WIFI_PASSWORD`

profile:
  wifi:
    ssid: AutomationLab
    password: "REPLACE_WITH_WIFI_PASSWORD"   # or MOBILERUN_IOS_PROFILE_WIFI_PASSWORD
    encryption: WPA2

The CLI now installs one supervised configuration profile, com.mobilerun.fleet, that carries Wi-Fi and device restrictions. On a host with a fleet profile configured, every attach of a phone this host supervises checks that profile. It installs or updates the profile, and removes the separate Wi-Fi profile that v0.4.x installed. The built-in restrictions turn off AirDrop. See Fleet profile. Quote all-digit passwords and SSIDs in YAML. A numeric value is rejected.

Behavior changes

You do not need to change anything for these, but they can change what you see.

Area	v0.5.0 behavior
Factory-state phones	`setup` now detects a phone that is still in Setup Assistant. If you configured the fleet profile and supervision identity, it prepares that phone without erasing it, like `auto`.
`auto`	New `--udid <udid>` flag limits discovery and onboarding to one USB phone.
`auto` in native mode	`auto` and `reset` no longer set Auto-Lock on native-mode phones. That is optional there: a locked phone still streams and can be unlocked through the stream or API.
Portal retries	Running out of `--retry-attempts` or `--retry-duration` no longer ends the device’s session. The CLI rebuilds that device’s portal, with a backoff from 5 seconds up to 5 minutes, and other devices keep running. Authentication failures still stop the device: run `mobilerun-ios login` or replace the API key.
Signing	Both signing backends now sign the Broadcast and VPN tunnel extensions that they find in the runner, each with its own profile. The tunnel-enabled runner (`WebDriverAgentRunnerTunnel-Runner.zip`) can be signed by `setup` with a paid team; you no longer build it in Xcode.
Native control (iOS 27+)	Adds system audio and deep links that name an app.
iOS 16	Supported in WDA mode with the classic developer disk image. No Xcode is needed on the host.
FFmpeg 8	Required for native audio, portal recordings, and the H.264 fallback for browsers that cannot decode the native codec. Homebrew installs `ffmpeg@8` with the CLI; the installer adds it when Homebrew is available.
Country	The last detected country is cached in `~/.mobilerun-ios/country` and used if detection fails.
New flags	`--video-playout-min-ms` and `--video-playout-max-ms` tune the browser’s jitter buffer.
New command	`mobilerun-ios profile` lists, installs, and removes configuration profiles without WDA.

Get started

Phones

Apps & networking

Run automation

Integrations

Developer tools

Upgrade checklist

Configuration keys

Environment variables

`MOBILERUN_IOS_WDA_BUNDLE_ID` changed meaning

Setup flags

Other changes that need action

setup reads the signing selection from config

reset no longer requires a pre-signed runner

Wi-Fi settings moved into the fleet profile (deprecated, still work)

Behavior changes

​Upgrade checklist

​Configuration keys

​Environment variables

​MOBILERUN_IOS_WDA_BUNDLE_ID changed meaning

​Setup flags

​Other changes that need action

​setup reads the signing selection from config

​reset no longer requires a pre-signed runner

​Wi-Fi settings moved into the fleet profile (deprecated, still work)

​Behavior changes

Upgrade checklist

Configuration keys

Environment variables

`MOBILERUN_IOS_WDA_BUNDLE_ID` changed meaning

Setup flags

Other changes that need action

setup reads the signing selection from config

reset no longer requires a pre-signed runner

Wi-Fi settings moved into the fleet profile (deprecated, still work)

Behavior changes