Configuration

Upgrading from v0.4.x? The runner and signing keys moved under wda: and signing:, and v0.5.0 ignores the old names. See Migrate to v0.5.0.

File location and precedence

The configuration file is ~/.mobilerun-ios/config.yaml. It can be missing. login and the interactive account setup in setup create or update it, and they change only the keys they write. For each setting, the first value found wins:

A command flag that you pass explicitly.
A MOBILERUN_IOS_* environment variable. For nested keys, write the name in upper case and replace dots with underscores: wda.unsigned_url becomes MOBILERUN_IOS_WDA_UNSIGNED_URL.
The value in config.yaml.
The built-in default.

Some settings are not YAML keys. Video and audio tuning, control mode, tunnel mode, local authentication, logging, and telemetry are only flags and environment variables. Adding video_fps, remote_xpc_only, or local_token to YAML has no effect. The auto concurrency and retry limits are command flags. The profile: section is read from the file only; see Fleet profile.

Keep secrets out of source control. When you create the file yourself, restrict access:

mkdir -p ~/.mobilerun-ios
chmod 700 ~/.mobilerun-ios
touch ~/.mobilerun-ios/config.yaml
chmod 600 ~/.mobilerun-ios/config.yaml

Use absolute paths for keys, certificates, and images. YAML does not expand ~. A running auto process reads the configuration once at startup, so restart it after you change the file or its environment.

Cloud authentication

Key	Default	Purpose
`token`	Unset	Session token saved by `login`, or a `dr_sk_…` API key. Needed for the cloud, not for `--local`.
`remote_url`	`wss://api.mobilerun.ai/v1/providers/personal/join`	Cloud portal WebSocket endpoint.
`auth_url`	`https://cloud.mobilerun.ai/api/auth`	Authentication service base URL.

On an interactive host, use mobilerun-ios login and mobilerun-ios whoami. On an unattended host, inject an API key:

export MOBILERUN_IOS_TOKEN='dr_sk_your_api_key'
mobilerun-ios auto

logout removes the saved token. It does not clear MOBILERUN_IOS_TOKEN. Do not paste tokens into bug reports.

Developer disk images

Key	Default	Purpose
`ddi_path`	Unset	Path to a local developer disk image (DDI) `Restore` directory. When unset, setup uses Xcode’s image or downloads one.
`ddi_url`	URL below	Base URL for downloading the developer disk image for iOS 17 and later.

https://raw.githubusercontent.com/doronz88/DeveloperDiskImage/main/PersonalizedImages/Xcode_iOS_DDI_Personalized

Downloaded images are cached in ~/.mobilerun-ios/devimages/. For one run, setup --ddi-path and setup --ddi-url override these keys. iOS 16 uses a classic image: setup takes Xcode’s if one is installed and otherwise downloads one.

WDA runner

Key	Environment	Default	Purpose
`wda.unsigned_url`	`MOBILERUN_IOS_WDA_UNSIGNED_URL`	URL below	Runner ZIP or IPA that the CLI signs and installs.
`wda.signed_url`	`MOBILERUN_IOS_WDA_SIGNED_URL`	Unset	Runner IPA already signed for your phones. Used only when no signing backend is selected.
`wda.bundle_id`	`MOBILERUN_IOS_WDA_BUNDLE_ID`	Derived	Runner bundle identifier used to sign and to launch. Must contain `WebDriverAgentRunner` and end in `.xctrunner`.

Default wda.unsigned_url:

https://github.com/droidrun/WebDriverAgent/releases/latest/download/WebDriverAgentRunner-Runner.zip

For the VPN tunnel runner, use WebDriverAgentRunnerTunnel-Runner.zip from the same release. To pin a version, replace latest/download with download/<tag>. See WDA signing for how the CLI chooses between unsigned_url and signed_url.

Signing

setup, auto, and reset all read these keys. The setup flags --backend, --account, and --identity override them for one run.

Key	Environment	Default	Purpose
`signing.backend`	`MOBILERUN_IOS_SIGNING_BACKEND`	Unset	`asc` (App Store Connect) or `xcode`. When unset, `identity` implies Xcode and `account` implies ASC. Otherwise interactive setup asks, and non-interactive runs use ASC.
`signing.account`	`MOBILERUN_IOS_SIGNING_ACCOUNT`	Unset	Name of the `signing.accounts` entry to use. Without it, non-interactive ASC signing needs exactly one account.
`signing.identity`	`MOBILERUN_IOS_SIGNING_IDENTITY`	Unset	Keychain identity for Xcode signing: SHA-1 fingerprint, Apple account, or full name. Without it, non-interactive Xcode signing needs exactly one identity.
`signing.accounts`	YAML only	Empty	App Store Connect API keys. It is a list, so you cannot set it with an environment variable.

Each signing.accounts entry has these fields:

Field	Purpose
`name`	Your label for the account, used by `signing.account` and `--account`.
`key_id`	App Store Connect API key ID.
`issuer_id`	App Store Connect issuer ID.
`p8_path`	Absolute path to the `.p8` private key. The key itself is not copied into the YAML.

wda:
  # Optional; omit to let setup derive one per team.
  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

Merge this into your file; do not overwrite the login token. For what each backend does on your Apple team, see WDA signing.

Fleet profile

These settings are for hosts that prepare phones still in Setup Assistant, or that reset phones. You do not need them to serve a phone that is already set up. The CLI installs one supervised configuration profile, com.mobilerun.fleet, with Wi-Fi and restrictions. It installs the profile during reset and during factory-state onboarding in setup and auto. It also checks the profile every time setup or auto attaches a phone that this host supervises, and reinstalls it when the section changed. The profile comes from the profile: section:

profile:
  wifi:
    ssid: AutomationLab
    password: "REPLACE_WITH_WIFI_PASSWORD"  # or MOBILERUN_IOS_PROFILE_WIFI_PASSWORD
    encryption: WPA2                         # WPA (default), WPA2, WPA3, WEP, Any
    auto_join: true                          # default
  restrictions:                              # Apple com.apple.applicationaccess keys
    allowAirDrop: false                      # built-in default; set to null to drop it
  removal_password: "REPLACE_ME"             # or MOBILERUN_IOS_PROFILE_REMOVAL_PASSWORD

Key	Purpose
`profile.wifi.ssid`, `.password`, `.encryption`, `.auto_join`, `.hidden`	Shortcuts for the Wi-Fi payload. Other keys under `wifi` are passed through as Apple `com.apple.wifi.managed` keys.
`profile.restrictions`	Apple restriction keys, spelled exactly as Apple spells them, for example `allowCamera: false`. `allowAirDrop: false` is on by default.
`profile.payloads`	Extra payloads as a list of `{type, identifier, values}`.
`profile.display_name`	Name shown in Settings. Default: `Mobilerun Fleet`.
`profile.removal_password`	Password needed to remove the profile on the phone.

Rules for this section:

It is read from the file only. The only environment overrides are MOBILERUN_IOS_PROFILE_WIFI_PASSWORD and MOBILERUN_IOS_PROFILE_REMOVAL_PASSWORD. Use them to keep secrets out of the file.
Quote values that YAML reads as numbers, such as an all-digit password or an SSID like 2024. A number is rejected.
An unknown key directly under profile:, such as restriction:, is an error.
The Wi-Fi network must be protected (open networks are not supported) and must reach the internet. iOS checks a new developer-signed runner with Apple before it launches it.
A host with no profile: section leaves phones that are already set up unchanged. reset and factory-state onboarding still need the section.

wifi_ssid, wifi_password, and wifi_enc_type are deprecated aliases for profile.wifi.ssid, .password, and .encryption. They still work and log a warning.

Supervision and onboarding

Key	Default	Purpose
`supervision_cert`	Unset	Absolute path to the PEM X.509 certificate that this host supervises phones with.
`supervision_key`	Unset	Matching PEM private key (PKCS#8, RSA PKCS#1, or EC).
`reset_org_name`	`Mobilerun`	Organization name used when supervising, for reset and for onboarding.
`reset_locale`	`en_US`	Locale applied during factory preparation.
`reset_lang`	`en`	Language applied during factory preparation.

The fleet profile needs the supervision identity: the profile’s content digest is keyed with the supervision private key, so the readable profile description reveals nothing about the Wi-Fi or removal password. Create the identity through your device-management process; it is separate from App Store Connect keys and WDA signing certificates. Do not replace the identity of a phone that is already managed.

These keys do not allow erasing a phone. setup and auto never erase, and auto rejects remote factory-reset requests. Only the explicit reset command erases, after confirmation.

Environment-only settings

These are not config.yaml keys. The flag column refers to the root portal command unless it says otherwise. auto accepts only some of these flags, so use the environment variables with auto.

Environment variable	Flag	Default and behavior
`MOBILERUN_IOS_REMOTE_XPC_ONLY`	`--remote-xpc-only`	Unset: use the saved or default mode. `true`: native only, never WDA. `false`: WDA.
`MOBILERUN_IOS_TUNNEL_MODE`	`--tunnel-mode` (all commands)	`userspace`; also `kernel` and `external`. See native control.
`MOBILERUN_IOS_LOCAL_TOKEN`	`--local-token` (root and `auto`)	Unset. Required when the local HTTP portal listens beyond loopback.
`MOBILERUN_IOS_LOG_LEVEL`	`--log-level` (all commands)	`info`; also `trace`, `debug`, `warn`, `error`. `-v` is `debug`.
`MOBILERUN_IOS_TELEMETRY`	`--telemetry` (root and `auto`)	On. `0` or `--telemetry=false` turns off anonymous usage metrics.
`MOBILERUN_IOS_VPN_CONSENT_BUTTON_LABELS`	`--vpn-consent-button-label`	Labels of the VPN consent button on non-English phones. Comma-separated in the variable; repeat the flag.
`MOBILERUN_IOS_PAIR_RECORDS`	None	Directory of the host’s pairing identity. Default: `~/.mobilerun-ios/pairrecords`.

MOBILERUN_IOS_WDA_BUNDLE_ID is the environment form of wda.bundle_id. The root portal’s --wda-bundle-id sets it for one run.

Video and audio

Environment variable	Root flag	Default	Range
`MOBILERUN_IOS_VIDEO_ENCODER`	`--video-encoder`	`videotoolbox` on macOS, `libx264` elsewhere	`videotoolbox`, `libx264`
`MOBILERUN_IOS_VIDEO_SCALE`	`--video-scale`	`50`	`1`–`100` percent
`MOBILERUN_IOS_VIDEO_QUALITY`	`--video-quality`	`30`	`1`–`100`; JPEG quality of the fallback frame paths
`MOBILERUN_IOS_VIDEO_FPS`	`--video-fps`	`60`	`1`–`120`
`MOBILERUN_IOS_VIDEO_BITRATE_KBPS`	`--video-bitrate-kbps`	`4000`	`100`–`100000` kbps
`MOBILERUN_IOS_VIDEO_GOP`	`--video-gop`	`60`	`1`–`1000` frames between keyframes
`MOBILERUN_IOS_VIDEO_PLAYOUT_MIN_MS`	`--video-playout-min-ms`	`0`	`0`–`500` ms; browser jitter-buffer floor. `0` shows each frame when it arrives.
`MOBILERUN_IOS_VIDEO_PLAYOUT_MAX_MS`	`--video-playout-max-ms`	`100`	`0`–`500` ms; browser jitter-buffer ceiling, at least the floor
`MOBILERUN_IOS_VIDEO_H265`	`--video-h265`	On	`0` or `false` stops offering HEVC
`MOBILERUN_IOS_VIDEO_TRANSCODE`	`--video-transcode`	On	Offers an FFmpeg H.264 stream to browsers that cannot decode the native codec
`MOBILERUN_IOS_AUDIO`	`--audio`	On	`0` or `false` turns off audio
`MOBILERUN_IOS_AUDIO_BITRATE_KBPS`	`--audio-bitrate-kbps`	`128`	`16`–`512` kbps
`MOBILERUN_IOS_AUDIO_CHANNELS`	`--audio-channels`	`2`	`1` mono, `2` stereo
`MOBILERUN_IOS_BROADCAST`	`--broadcast`	On	`0` or `false` stops the automatic ReplayKit broadcast start

These values are requests. Not every phone or capture path supports every value. Flags reject out-of-range numbers; environment values are clamped to the range.

# Root portal flags
mobilerun-ios --video-fps 30 --video-scale 50 --audio=false <udid>

# The same settings for auto
MOBILERUN_IOS_VIDEO_FPS=30 MOBILERUN_IOS_VIDEO_SCALE=50 \
  MOBILERUN_IOS_AUDIO=0 mobilerun-ios auto

FFmpeg 8 is needed for native audio, recordings, and the H.264 fallback. Homebrew installs ffmpeg@8 with the CLI, and the installer adds it when Homebrew is available. The CLI finds Homebrew’s ffmpeg@8 without a PATH change.

Files managed by the CLI

Path under `~/.mobilerun-ios/`	Contents
`config.yaml`	Your settings, the login token, and signing account references.
`devices/<udid>.json`	Saved control mode (WDA or native) per phone.
`devimages/`	Downloaded developer disk images.
`signing/`	Cached signing certificates and private keys. Protect this directory.
`pairrecords/`	The host’s pairing identity. If you lose it, every phone needs a new Trust tap.
`onboarding/`	Checkpoints of unfinished factory-state onboardings.
`portals/`	PID and log files of detached portals.
`country`	Last detected country, used when detection fails.

Do not edit CLI-managed files while the CLI is running.

Get started

Phones

Apps & networking

Run automation

Integrations

Developer tools

File location and precedence

Cloud authentication

Developer disk images

WDA runner

Signing

Fleet profile

Supervision and onboarding

Environment-only settings

Video and audio

Files managed by the CLI

​File location and precedence

​Cloud authentication

​Developer disk images

​WDA runner

​Signing

​Fleet profile

​Supervision and onboarding

​Environment-only settings

​Video and audio

​Files managed by the CLI

File location and precedence

Cloud authentication

Developer disk images

WDA runner

Signing

Fleet profile

Supervision and onboarding

Environment-only settings

Video and audio

Files managed by the CLI