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

# Configuration

> Complete config.yaml reference, signing defaults, environment overrides, and runtime settings.

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

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

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

```bash theme={null}
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](/api-keys):

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

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

```text theme={null}
https://github.com/droidrun/WebDriverAgent/releases/latest/download/WebDriverAgentRunner-Runner.zip
```

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

### 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):

```yaml theme={null}
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](/mobilerun-ios/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. |

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

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

## 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/overview#wda-and-native-control). |
| `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.

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.