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

# Connect an iPhone

> Bring your own iPhone into Mobilerun cloud using the mobilerun-ios CLI.

Use the `mobilerun-ios` CLI to connect your own iPhone to Mobilerun so it can run tasks from the Playground or API. This guide is for developers with a Mac, Xcode, and an iPhone they can plug in over USB. Once connected, the iPhone shows up as a [Personal Phone](/device-types#personal-phone) on the [Devices](https://cloud.mobilerun.ai/devices) page.

<iframe className="w-full aspect-video rounded-xl" src="https://www.youtube.com/embed/uOv75EA3n3Y" title="YouTube video player" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />

## Requirements

* A Mobilerun account with a [Personal Phone](/device-types#personal-phone) subscription
* macOS with Xcode installed
* An iPhone connected via USB
* An Apple ID with signing capability (personal team is fine)

<Note>
  Signing with a personal / free team comes with Apple-imposed limits: builds expire after **7 days**, after which you need to rebuild in Xcode and re-trust the certificate on the device, and you can sign for at most **3 devices**. A paid Apple Developer account (\$99/year) lifts both limits.
</Note>

***

## 1. Enable Developer Mode on your iPhone

Developer Mode lets Xcode install and launch development builds (like WebDriverAgent) on your device.

1. On the iPhone, open **Settings → Privacy & Security → Developer Mode**.
2. Toggle **Developer Mode** on.
3. Restart the iPhone when prompted, then confirm the prompt after it boots.

<Info>
  The **Developer Mode** entry only appears after the iPhone has been connected at least once to a Mac running Xcode. If you don't see it, plug the device in, open Xcode, then check Settings again.
</Info>

***

## 2. Configure your iPhone for long-lived connections

A Personal Phone is meant to stay online for hours or days at a time. Three iPhone settings make the difference between a connection that survives and one that needs constant babysitting:

### Disable Auto-Lock

When the iPhone locks, the screen goes black and the session goes offline. Set **Settings → Display & Brightness → Auto-Lock** to **Never**.

### Enable automatic time zone

Set **Settings → General → Date & Time → Set Automatically** to on. This keeps the device's time zone in sync with its (simulated) location. Writing the time zone manually does not work on non-jailbroken devices, so automatic time zone is the only reliable way to keep it matching the location.

### Remove the passcode (for unattended 24/7 setups)

Only do this if you plan to leave the device running around the clock with nobody nearby to unlock it. For supervised use, keep your passcode and skip this.

After running for a while, the XCTest session that hosts WebDriverAgent crashes or expires and has to be restarted. Mobilerun restarts it automatically — but only if the device has no passcode. With a passcode set, the relaunched session lands on the lock screen and the connection stays down until someone enters the passcode by hand. If you're around to unlock the device when that happens, you don't need to remove it.

For a fully unattended device, turn the passcode off under **Settings → Face ID & Passcode → Turn Passcode Off**.

<Warning>
  Removing the passcode also disables Face ID, Apple Pay, and some iCloud features. Use a dedicated automation device rather than your daily phone.
</Warning>

***

## 3. Download Mobilerun WebDriverAgent

Mobilerun controls your iPhone through WebDriverAgent (WDA), an open-source project that exposes input injection and screenshots on iOS. We maintain our own fork, **Mobilerun WebDriverAgent**, tuned for exactly this job: higher-quality streaming, lower-latency accessibility tree fetching and touch input, with more features landing over time.

Clone it:

```bash theme={null}
git clone --branch v1.1.0 https://github.com/droidrun/WebDriverAgent
```

<Info>
  The upstream [Appium WebDriverAgent](https://github.com/appium/WebDriverAgent) works too, but with higher latency and lower streaming FPS.
</Info>

***

## 4. Build and install WebDriverAgent on your iPhone with Xcode

This is the trickiest step. Take it slow — most connection issues later on trace back to signing or trust problems here.

1. Open `WebDriverAgent.xcodeproj` in Xcode.

2. In the top bar, select your connected iPhone as the run destination.

3. Choose the **WebDriverAgentRunner** scheme.

4. Set up signing for the runner and its extension target. For both `WebDriverAgentRunner` and `WebDriverAgentBroadcast`, select the target, open the **Signing & Capabilities** tab, and:

   * Tick **Automatically manage signing**.
   * Pick your Apple ID / Team from the dropdown.

   <Info>
     `WebDriverAgentBroadcast` is an app extension that ships inside the runner app — it's what enables high-FPS screen streaming. It builds and embeds automatically; it just needs a team selected so Xcode can sign it. Skipping it fails the build with "Signing for 'WebDriverAgentBroadcast' requires a development team."
   </Info>

   <Tip>
     If Xcode shows "Failed to register bundle identifier," the **Bundle Identifier** needs to be unique per Apple ID. Append a suffix to the `WebDriverAgentRunner` target's bundle ID (e.g. your initials: `com.facebook.WebDriverAgentRunner.<suffix>`) and mirror it in the extension target, keeping its suffix pattern intact: `WebDriverAgentBroadcast` → `com.facebook.WebDriverAgentRunner.<suffix>.xctrunner.broadcast`.

     If the extension ID doesn't follow the runner's, the app installs with an extension whose provisioning profile no longer matches, and iOS rejects the install.
   </Tip>

5. Press **Cmd+U** to build-for-testing. Xcode builds the runner with the extension embedded and installs it onto the iPhone.

6. On the iPhone, trust the developer certificate: **Settings → General → VPN & Device Management** → tap your team → **Trust**.

<Warning>
  The first Cmd+U run often fails with "Could not launch WebDriverAgentRunner" because the certificate isn't trusted yet. Trust the certificate on the device (step 6) and press **Cmd+U** again.
</Warning>

***

## 5. Install the mobilerun-ios CLI

Pick whichever you prefer:

<CodeGroup>
  ```bash Homebrew theme={null}
  brew install droidrun/tap/mobilerun-ios
  ```

  ```bash curl theme={null}
  curl -fsSL https://media.mobilerun.ai/releases/mobilerun-ios/install.sh | sh
  ```
</CodeGroup>

Both fetch the latest release, verify the checksum, and drop the binary on your `PATH` (`brew` puts it in the Homebrew prefix; the `curl` installer uses `/usr/local/bin` and may prompt for sudo).

<Tip>
  To install into a user-writable directory with the `curl` installer, override `BINDIR`:

  ```bash theme={null}
  curl -fsSL https://media.mobilerun.ai/releases/mobilerun-ios/install.sh | BINDIR=$HOME/.local/bin sh
  ```
</Tip>

Verify the install:

```bash theme={null}
mobilerun-ios --version
```

***

## 6. Log in to Mobilerun

```bash theme={null}
mobilerun-ios login
```

The CLI prints a short code and opens the verification page in your browser. Approve the code and the CLI stores the session token under `~/.mobilerun-ios/config.yaml` (chmod 0600). Confirm with:

```bash theme={null}
mobilerun-ios whoami
```

Run `mobilerun-ios logout` to clear the stored token.

<Info>
  For CI/headless setups where opening a browser isn't possible, skip `login` and export an API key from the [API Keys](/api-keys) tab instead:

  ```bash theme={null}
  export MOBILERUN_IOS_TOKEN=dr_sk_your_api_key
  ```
</Info>

***

## 7. List your connected iPhones

With the iPhone plugged in and unlocked, list everything `mobilerun-ios` can see:

```bash theme={null}
mobilerun-ios list
```

```text theme={null}
UDID                                      NAME             TYPE    OS     STATE    PORTAL
00008020-001A2B3C4D5E6F70                 My iPhone        real    18.2   ready    —
```

Copy the UDID of the device you want to connect. The `PORTAL` column shows `running (pid=…)` once a background portal is up (see below).

***

## 8. Start the connection

Connect the iPhone by passing its UDID:

```bash theme={null}
mobilerun-ios 00008020-001A2B3C4D5E6F70
```

Leave the UDID off to connect every attached iPhone:

```bash theme={null}
mobilerun-ios
```

The command opens a WebSocket to Mobilerun cloud and keeps the device online for as long as it runs. Press **Ctrl+C** to end the session.

### Run in the background

Pass `-d` / `--detach` to release the terminal while the portal stays up:

```bash theme={null}
mobilerun-ios -d 00008020-001A2B3C4D5E6F70
```

The CLI prints a PID and log path, then exits. `mobilerun-ios list` shows the portal as `running` in the `PORTAL` column. Stop it later with:

```bash theme={null}
mobilerun-ios stop 00008020-001A2B3C4D5E6F70
```

Or `mobilerun-ios stop` (no UDID) to stop every background portal.

***

## Verify it worked

Open [Devices](https://cloud.mobilerun.ai/devices) in the Mobilerun dashboard — your iPhone should show up as a connected Personal Phone. Start a task from the Playground and select it to confirm end-to-end control.

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="WebDriverAgentRunner crashes on launch">
    The CLI surfaces this as:

    ```text theme={null}
    failed to start agent: failed to wait for WebDriverAgent: timed out waiting for WebDriverAgent to be ready
    ```

    Re-sign the `WebDriverAgentRunner` target in Xcode and make sure the developer certificate is trusted under **Settings → General → VPN & Device Management**, then press **Cmd+U** again.
  </Accordion>

  <Accordion title="`mobilerun-ios list` shows no devices">
    Confirm your USB cable supports data (not charging-only), the iPhone is unlocked, and you accepted the **Trust This Computer** prompt.
  </Accordion>

  <Accordion title="Auth failures">
    Re-run `mobilerun-ios login` and confirm with `mobilerun-ios whoami`. For API-key setups, verify the token in the [API Keys](/api-keys) tab and that `MOBILERUN_IOS_TOKEN` is exported in the same shell.
  </Accordion>

  <Accordion title="iPhone goes offline or screen goes black during a session">
    Auto-lock put the device to sleep. Disable it under **Settings → Display & Brightness → Auto-Lock → Never** while the iPhone is connected to Mobilerun (see [step 2](#2-configure-your-iphone-for-long-lived-connections)).
  </Accordion>

  <Accordion title="Connection drops after a few hours and the device sits on the lock screen">
    The XCTest session hosting WebDriverAgent expired and was restarted, but a passcode is blocking the relaunch. Unlock the device to let the session reconnect. For an unattended 24/7 device where no one is around to do that, remove the passcode (see [step 2](#2-configure-your-iphone-for-long-lived-connections)) so the session can heal itself automatically.
  </Accordion>
</AccordionGroup>

***

## Known issues

* **TikTok crashes automation.** Dumping TikTok's accessibility tree times out, which crashes the Mobilerun automation session. Avoid tasks that drive the TikTok app for now.

***

## Need Help?

If you run into any issues or need further assistance, reach out to us:

* **Discord:** [discord.gg/droidrun](https://discord.gg/droidrun)
* **Email:** [contact@mobilerun.ai](mailto:contact@mobilerun.ai)