Skip to main content
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:
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.

​
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:

​
Configure an account

Merge this into ~/.mobilerun-ios/config.yaml:
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

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:
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 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:
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 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.
The identity selector accepts the certificate’s SHA-1 fingerprint, Apple account, or full name. Inspect local identities with:
For auto, use:
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.

​
Pre-signed runners for auto

If another build/signing system already produces an artifact for your phones, configure:
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:
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.