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

# Automatic WDA signing

> Configure App Store Connect or Xcode signing for setup and automatic installation of missing runners.

WDA must be signed for the target iPhone before iOS will install and launch it. `mobilerun-ios setup` can download a prebuilt runner, provision signing material, sign the runner, install it, and check that it launches. You do not need to compile WDA yourself for the App Store Connect path.

There are three workflows:

| Workflow                | Requirements                                                   | Use                                                                                                    |
| ----------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| App Store Connect (ASC) | Paid developer team and an API key with provisioning access    | Programmatic provisioning and signing.                                                                 |
| Local Xcode signing     | macOS, Xcode, Apple Development identity and matching profiles | Sign with your local keychain identity; supports a personal team where Apple's capabilities permit it. |
| Pre-signed artifact     | Runner already signed and provisioned for the device           | Auto installs a missing runner without requesting new signing material.                                |

<Note>
  Signing is needed only for WDA mode. Native iOS 27+ control does not install a WDA runner. Automatic signing is also not automatic renewal: setup normally skips an installed Mobilerun runner, and auto preserves installed runners. Use explicit `setup --reinstall` to renew or replace one.
</Note>

## App Store Connect

### Prepare an API key

In App Store Connect, open **Users and Access → Integrations → App Store Connect API** and obtain a team API key with permission to manage the provisioning resources below. Record its **Key ID**, **Issuer ID**, and download the `.p8` key file. If your account cannot create a suitable key, ask the team's administrator to configure access.

The CLI needs to register or re-enable devices, register bundle IDs, create development certificates, and create/delete development provisioning profiles. An API key restricted to unrelated App Store operations is insufficient.

Store the key privately on the host. Use its absolute path in the configuration:

```bash theme={null}
mkdir -p ~/.mobilerun-ios/keys
chmod 700 ~/.mobilerun-ios/keys
# Move your downloaded key into this directory, then restrict its permissions:
chmod 600 ~/.mobilerun-ios/keys/AuthKey_YOUR_KEY_ID.p8
```

### Configure an account

Merge this into `~/.mobilerun-ios/config.yaml`:

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

Alternatively, run `mobilerun-ios setup <udid> --wda --backend asc` interactively and follow the add-account prompts. Account entries are saved by name; reusing a name replaces that entry. The `.p8` file stays at its configured path.

### Sign and install

```bash theme={null}
mobilerun-ios setup <udid> --wda --backend asc --account automation
mobilerun-ios verify <udid> --deep
```

For non-interactive preparation, add `--non-interactive`. Host trust, Developer Mode, and developer-certificate trust still require any applicable on-device confirmations.

For auto, set the selection in YAML:

```yaml theme={null}
backend: asc
account: automation
```

Then start `mobilerun-ios auto`. Auto signs only when WDA is needed and no runner is installed. If you configure multiple accounts, choose one explicitly; there is no unattended account picker.

### What gets provisioned

The ASC backend creates or reuses a development signing certificate, registers the target UDID (or re-enables a disabled registration), ensures the app identifiers exist, and creates a development profile covering the device. Provisioning can replace matching profiles, so use a deliberate automation account/configuration rather than assuming this workflow is read-only on your Apple team.

The CLI caches signing credentials under `~/.mobilerun-ios/signing/`. This directory contains private keys and certificates; protect it like any other credential. After rotating an API key, update the account configuration and verify signing before resuming unattended operation.

### Artifact and extension limits

Automatic ASC signing does not configure the Network Extension capability or provision separate profiles for every extension in a custom artifact. Do not assume that pointing `runner_url` at a tunnel-enabled artifact is sufficient to enable VPN support.

Xcode signing requires matching profiles for each included extension. For a tunnel-enabled build, use the [manual tunnel build](/guides/connect-iphone#extra-steps-for-a-tunnel-enabled-wda-build) with a paid team and matching entitlements/profiles, or supply a fully signed artifact to auto. The default WDA scheme/artifact is distinct from the opt-in tunnel variant; automatic setup is not a request to enable VPN capabilities.

### Bundle identifiers

Let the CLI derive the identifier unless you have an existing registration/profile to reuse:

* The CLI chooses an account-specific or team-specific identifier to avoid conflicts with other Apple teams.
* A custom installed Mobilerun runner ID can be retained during explicit reinstall.
* An explicit `--bundle-id`, environment `MOBILERUN_IOS_BUNDLE_ID`, or configured `bundle_id` overrides automatic selection.

A custom installed-app ID must contain `WebDriverAgentRunner` and end in `.xctrunner`, for example:

```yaml theme={null}
bundle_id: com.example.WebDriverAgentRunner.xctrunner
```

The `.broadcast` and `.tunnel` extensions must remain under that installed runner's bundle prefix. Do not copy another team's fixed identifier or manually mix profiles from different teams.

## Local Xcode signing

The Xcode backend signs in place with a keychain identity; it does not export that identity's private key. It needs a development provisioning profile for the runner **and every bundled extension**, covering the selected team and target UDID.

1. Install Xcode and add your Apple Account in **Xcode → Settings → Accounts**.
2. Under **Manage Certificates**, create an **Apple Development** certificate if one is missing.
3. Follow the [manual Xcode build steps](/guides/connect-iphone#manual-xcode-signing-and-build) to register the phone and create matching profiles for the runner and Broadcast (plus Tunnel when using the tunnel-enabled scheme).
4. Use the installed runner bundle ID when selecting a profile. The Xcode test target's base ID and the installed runner ID are not identical: the latter ends in `.xctrunner`.

```bash theme={null}
mobilerun-ios setup <udid> --wda --backend xcode \
  --identity 'Apple Development: Your Name (TEAMID)' \
  --bundle-id com.example.WebDriverAgentRunner.xctrunner
```

The identity selector accepts the certificate's SHA-1 fingerprint, Apple account, or full name. Inspect local identities with:

```bash theme={null}
security find-identity -p codesigning
```

For auto, use:

```yaml theme={null}
backend: xcode
identity: 'Apple Development: Your Name (TEAMID)'
bundle_id: com.example.WebDriverAgentRunner.xctrunner
```

<Warning>
  Selecting `backend: xcode` does not automatically create missing extension profiles. If the CLI reports that an extension has no development profile, sign/build that target in Xcode with the same team and device. Personal-team signing has Apple-imposed expiry and capability restrictions; it is not equivalent to a paid team's provisioning access.
</Warning>

## Pre-signed runners for auto

If another build/signing system already produces an artifact for your phones, configure:

```yaml theme={null}
wda_ipa_url: https://artifacts.example.com/automation/runner-signed.ipa
```

When auto needs a missing WDA runner, it downloads and installs this artifact without re-signing. It must already include valid signatures and provisioning profiles for the runner and its extensions, and cover the target UDID. Auto checks that a discoverable runner was installed and that it can launch.

Keep artifact access restricted and treat signed download URLs as secrets. An expired profile, wrong UDID, missing extension profile, or missing developer trust is not repaired by downloading the same artifact again.

`runner_url` and `wda_ipa_url` are deliberately different:

* **`runner_url`:** input to setup/auto's signing flow; the default is the Mobilerun runner ZIP.
* **`wda_ipa_url`:** already-signed artifact for auto's missing-runner path and the explicit reset workflow. Ordinary `setup` does not use it as a shortcut around signing.

## Renew or repair signing

Stop any portal or auto process that owns the device, then explicitly reinstall:

```bash theme={null}
mobilerun-ios setup <udid> --reinstall --backend asc --account automation
mobilerun-ios verify <udid> --deep
```

For Xcode, replace the signing flags with `--backend xcode --identity ...` and, where needed, `--bundle-id ...`. Renew expired profiles in Xcode before retrying. Reinstall implies WDA and retains an existing custom runner ID unless overridden.

Give the iPhone internet access so iOS can validate the developer profile. On the phone, open **Settings → General → VPN & Device Management**, select the developer profile and trust it when prompted. A valid signature on disk is not proof that iOS has accepted trust or can launch the app.

| Failure                                   | Check                                                                                                    |
| ----------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| No account / multiple accounts            | Configure `signing_accounts`; choose `--account` for setup or YAML `account` for auto.                   |
| ASC authorization or provisioning failure | Check issuer/key IDs, readable `.p8` file, API permissions, and the team's device/certificate limits.    |
| No signing identity                       | Sign in to Xcode and create an Apple Development certificate in the host user's keychain.                |
| No matching profile                       | Profile must cover the bundle ID, team, device, and validity period; check extensions separately.        |
| Bundle identifier already registered      | Use the derived identifier or one owned by your team.                                                    |
| Installed runner does not launch          | Check unlock, internet access, developer trust, and expiry; use explicit reinstall if renewal is needed. |