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

# Setup and verification

> Prepare a device with setup, choose WDA or native control, and check readiness with verify.

## setup

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

<Note>
  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.
</Note>

### 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](/mobilerun-ios/configuration) for their environment equivalents.

### Examples

```bash theme={null}
# 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](/mobilerun-ios/overview#wda-and-native-control) for the video tunnel and feature limitations.

## verify

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

```bash theme={null}
mobilerun-ios verify <udid>
mobilerun-ios verify <udid> --wda
mobilerun-ios verify <udid> --deep
```

<Warning>
  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.
</Warning>

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