Configuration

File location and precedence

The configuration file is ~/.mobilerun-ios/config.yaml (note the spelling: .mobilerun-ios). A missing file is allowed. login and interactive signing-account setup create or update it. For scalar YAML settings, a non-empty MOBILERUN_IOS_<UPPERCASE_KEY> environment variable overrides the file. For example, MOBILERUN_IOS_TOKEN overrides token. A supported, explicitly supplied command flag takes precedence over its corresponding config/environment value; unset values use the defaults below.

Not every CLI flag is a YAML setting. Video/audio tuning, control mode, tunnel mode, local authentication, logging, and telemetry read environment variables directly. Adding video_fps, remote_xpc_only, or local_token to YAML does not configure them. auto concurrency and retry policy are command flags, not YAML keys.

Keep secrets out of source control. When creating the file manually, restrict access:

mkdir -p ~/.mobilerun-ios
chmod 700 ~/.mobilerun-ios
# After creating config.yaml:
chmod 600 ~/.mobilerun-ios/config.yaml

Use absolute paths for key, certificate, and image files. A ~ inside a YAML string is not expanded by the shell. Restart auto after editing the file or changing its environment: configuration changes take effect on the next run.

Cloud authentication

Key	Type / default	Purpose
`remote_url`	String: `wss://api.mobilerun.ai/v1/providers/personal/join`	Cloud portal WebSocket endpoint.
`auth_url`	String: `https://cloud.mobilerun.ai/api/auth`	Authentication service base URL.
`token`	String: unset	Session token saved by `login`, or a `dr_sk_…` API key. Required for normal cloud authentication, not local HTTP mode.

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

export MOBILERUN_IOS_TOKEN='dr_sk_your_api_key'
mobilerun-ios auto

logout removes the saved token, not environment overrides. Do not paste tokens into diagnostic reports.

Developer disk images

Key	Type / default	Purpose
`ddi_path`	String: unset	Path to a local DDI `Restore` directory. When unset, preparation can use Xcode’s image and download/cache images as needed.
`ddi_url`	String: URL below	Base URL for downloading the personalized developer image.

Default ddi_url:

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

Images are cached in ~/.mobilerun-ios/devimages/. setup --ddi-path and setup --ddi-url override the configured values for that invocation. auto repairs an observed missing DDI rather than replacing an already-mounted image indiscriminately.

Runner and signing

Key	Type / default	Purpose
`runner_url`	String: URL below	Runner ZIP or IPA to sign before installation. Used by setup and by auto when signing a missing runner.
`bundle_id`	String: automatic	Installed runner identifier. Normally derived from the signing team/account or retained from an existing custom Mobilerun runner. Custom IDs must contain `WebDriverAgentRunner` and end in `.xctrunner`.
`signing_accounts`	List: empty	App Store Connect API-key accounts; fields below. Configure this as a YAML list, not a scalar environment string.
`backend`	String: unset	Auto only: `asc` or `xcode`. Without an explicit backend, `identity` implies Xcode, `account` implies ASC, otherwise non-interactive signing falls back to ASC.
`account`	String: unset	Auto only: select a `signing_accounts[].name`. With no selection, non-interactive ASC signing requires exactly one account.
`identity`	String: unset	Auto only: local Xcode signing identity, matched by SHA-1 fingerprint, account, or full name. With no selection, non-interactive Xcode signing requires exactly one identity.
`wda_ipa_url`	String: unset	Already-signed runner artifact. Auto uses it when WDA is required and no runner is installed; explicit factory reset also requires this setting. It is not the input for setup’s signing flow.

Default runner_url:

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

setup does not read backend, account, or identity from YAML. Pass --backend, --account, or --identity to setup. Both setup and auto read signing_accounts, bundle_id, runner_url, and DDI settings. Do not confuse provisioning bundle_id with the runtime-only MOBILERUN_IOS_WDA_BUNDLE_ID launch selector.

Signing account fields

Field	Required	Purpose
`name`	Yes	Local label, used by `--account` or auto’s `account`.
`key_id`	Yes	App Store Connect API key ID.
`issuer_id`	Yes	App Store Connect issuer ID.
`p8_path`	Yes	Absolute path to the downloaded `.p8` private key. The key contents are not stored in YAML.

Minimal ASC-backed auto configuration (merge this into an existing file rather than overwriting login settings):

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

For account creation, Xcode bootstrap, and renewal, see Automatic WDA signing.

Factory-state onboarding and reset

These settings are not needed just to serve a prepared phone. auto consults them when a phone is positively identified as still in Setup Assistant. Explicit reset uses them for its erase-and-reprovision workflow.

Key	Type / default	Purpose
`wifi_ssid`	String: unset	Wi-Fi network for activation and provisioning. Required by factory-state onboarding and reset.
`wifi_password`	String: unset	Wi-Fi password. The current preflight requires a non-empty value.
`wifi_enc_type`	String: `WPA`	Wi-Fi profile encryption type. Keep `WPA` for the documented password-protected setup.
`supervision_cert`	String: unset	Absolute path to an X.509 certificate in PEM format used as the host supervision identity.
`supervision_key`	String: unset	Matching PEM private key; supports PKCS#8, RSA PKCS#1, or EC key encoding. The public key must match the certificate.
`reset_org_name`	String: `Mobilerun`	Organization name used for supervision, also during auto onboarding.
`reset_locale`	String: `en_US`	Locale applied during factory preparation.
`reset_lang`	String: `en`	Language applied during factory preparation.

# Add only when this host should prepare factory-state automation phones.
wifi_ssid: AutomationLab
wifi_password: REPLACE_WITH_WIFI_PASSWORD
wifi_enc_type: WPA
supervision_cert: /Users/you/.mobilerun-ios/supervision/cert.pem
supervision_key: /Users/you/.mobilerun-ios/supervision/key.pem
reset_org_name: Mobilerun
reset_locale: en_US
reset_lang: en

Provision the supervision identity through your device-management process; it is separate from an ASC API key or WDA signing certificate. Do not replace an existing managed device’s identity with an arbitrary certificate.

Configuring these keys does not authorize erasure. auto never erases and rejects remote factory-reset requests. The explicit reset command is destructive and additionally requires wda_ipa_url, confirmation, and exclusive device ownership.

Environment-only runtime settings

These are not config.yaml keys. The flag column describes the root portal command unless marked global. Most root flags are not inherited by auto; use the environment equivalents for auto’s media/control settings.

Environment variable	Flag	Default / behavior
`MOBILERUN_IOS_REMOTE_XPC_ONLY`	`--remote-xpc-only`	Unset: saved/device default; `true`: native-only; `false`: WDA. Native mode never falls back to WDA.
`MOBILERUN_IOS_TUNNEL_MODE`	`--tunnel-mode` (global)	`userspace`; also `kernel` and `external`. See native operation.
`MOBILERUN_IOS_WDA_BUNDLE_ID`	`--wda-bundle-id`	Unset: discover runner; otherwise launch this installed bundle ID. Does not provision or rename a runner.
`MOBILERUN_IOS_LOCAL_TOKEN`	`--local-token` (root and auto)	Unset; required for non-loopback local HTTP binding.
`MOBILERUN_IOS_LOG_LEVEL`	`--log-level` (global)	`info`; `trace`, `debug`, `info`, `warn`, `error`. `-v` / `--verbose` selects debug.
`MOBILERUN_IOS_TELEMETRY`	`--telemetry` (root and auto)	Enabled; use `0` or `--telemetry=false` to disable.
`MOBILERUN_IOS_VPN_CONSENT_BUTTON_LABELS`	`--vpn-consent-button-label`	Localized VPN-consent labels; environment value is comma-separated, flag can be repeated.

Video and audio

Environment variable	Root flag	Default	Accepted values
`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 fallback quality
`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_H265`	`--video-h265`	Enabled	`0` / `false` disables HEVC advertisement
`MOBILERUN_IOS_AUDIO`	`--audio`	Enabled	`0` / `false` disables audio capture
`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`	Enabled	`0` / `false` disables automatic ReplayKit broadcast startup

These are requests to the relevant capture/encoding paths, not guarantees that every backend or phone supports every value. In particular, JPEG quality affects fallback paths rather than the primary encoded broadcast. Integer flags reject out-of-range values; the media environment loaders clamp numeric values to their supported bounds.

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

# Equivalent environment overrides for auto
MOBILERUN_IOS_VIDEO_FPS=30 MOBILERUN_IOS_VIDEO_SCALE=50 \
  MOBILERUN_IOS_AUDIO=0 mobilerun-ios auto

Files managed by the CLI

Path under `~/.mobilerun-ios/`	Contents
`config.yaml`	Explicit host settings, login token, and signing account references.
`devices/<udid>.json`	Saved per-device control mode.
`devimages/`	Downloaded developer disk images.
`signing/`	Cached development signing credentials. Contains private keys; protect it.
`portals/`	Detached portal PID and log files.

Do not modify CLI-managed files while processes are running. Saving login/account settings preserves your file settings without copying temporary environment overrides into YAML.

Introduction

Concepts

Guides

Mobilerun iOS

Assistant

Dashboard

Agent Skills

Integrations

File location and precedence

Cloud authentication

Developer disk images

Runner and signing

Signing account fields

Factory-state onboarding and reset

Environment-only runtime settings

Video and audio

Files managed by the CLI

​File location and precedence

​Cloud authentication

​Developer disk images

​Runner and signing

​Signing account fields

​Factory-state onboarding and reset

​Environment-only runtime settings

​Video and audio

​Files managed by the CLI

File location and precedence

Cloud authentication

Developer disk images

Runner and signing

Signing account fields

Factory-state onboarding and reset

Environment-only runtime settings

Video and audio

Files managed by the CLI