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