> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mobilerun.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrate to v0.5.0

> Breaking changes from mobilerun-ios v0.4.x to v0.5.0, with old → new configuration keys, environment variables, and flags.

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.

<Warning>
  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](#configuration-keys) and [Setup flags](#setup-flags) for the new names.
</Warning>

## Upgrade checklist

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Find the old settings">
    Run both checks. Any output is a setting that v0.5.0 ignores.

    ```bash theme={null}
    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`.
  </Step>

  <Step title="Rename them">
    Move each setting to its new key, environment variable, or flag. See [Configuration keys](#configuration-keys), [Environment variables](#environment-variables), and [Setup flags](#setup-flags).
  </Step>

  <Step title="Upgrade and check">
    ```bash theme={null}
    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.
  </Step>
</Steps>

## 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`. |

<CodeGroup>
  ```yaml v0.4.x (ignored by v0.5.0) theme={null}
  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
  ```

  ```yaml v0.5.0 theme={null}
  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
  ```
</CodeGroup>

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 |

```bash theme={null}
# 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](/mobilerun-ios/wda-signing#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` |

```yaml theme={null}
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](/mobilerun-ios/configuration#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. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.