iOS Real Device Setup

To run cases on a real iOS device, you need a working WebDriverAgent (WDA) installed on the device. The Munk AI release installer (get.munk.sh) does not include one-click WDA setup. Complete this one-time environment preparation first; after that, day-to-day usage is just munk serve.

Pick a path

Once your environment is ready, both paths converge at Connect to Munk and start running.

Prerequisites

Before you begin, confirm:

• You are on a Mac with Xcode installed
• Munk AI is installed (munk version works)
• Your iPhone is connected over USB (USB is recommended for the first setup, not WiFi-only)
• The phone is unlocked and you have tapped Trust This Computer
• The device is running iOS 17 or later
• (Official install path only) You have Apple Developer signing available
• (Individual developer account) The test device UDID is registered under Apple Developer → Devices

Get the device UDID

With the phone connected, run:

xcrun devicectl list devices

Note the UDID of your target device. You will need it when installing WDA.

If you use an individual developer account, register that UDID in the Apple Developer portal (Certificates, Identifiers & Profiles → Devices) and make sure any Provisioning Profile you create later includes this device. Unregistered devices cannot be used for Development signing and installation.

After Munk is running, you can also look up device_ref (the value you usually pass when running a case):

munk devices list --platform ios

Use an existing WDA

If WebDriverAgentRunner is already installed and working on your device, skip the build-and-install steps and only configure the matching bundle id in Munk.

1. Confirm the WDA bundle id

Common examples (use the one actually installed on your device):

• com.facebook.WebDriverAgentRunner.xctrunner
• Or a custom id from your own signing setup

If you are unsure, check Xcode Devices and Simulators, or the bundle id you used when you originally installed WDA.

2. Set iOS WDA bundle id in Apps

1. Start the service:

   munk serve --host 127.0.0.1 --port 16888
   

2. Open the Web UI: http://127.0.0.1:16888/
3. Go to Apps → create or edit your iOS app
4. Fill in iOS bundle id (the app under test)
5. Enter the installed WDA bundle id in iOS WDA bundle id
6. Save

If iOS WDA bundle id is left empty, Munk defaults to sh.munk.wda.xctrunner (for users who followed the official install flow below).

3. Verify it works

In the Web UI Devices page, confirm the real device appears in the list, then try running a case.

If the device is missing, WDA fails to start, or the case errors out, double-check the bundle id first. If it still fails, switch to the official Munk WDA install flow.

Note: WDA from other sources is not officially validated by Munk. Compatibility is not guaranteed. If you hit stability issues, use the official install flow.

Install the official Munk WDA

The release installer does not ship WDA install scripts. Clone the open-source repository and complete signing, build, and installation locally.

1. Clone the repository

git clone https://github.com/chaxiu/munk-ai.git
cd munk-ai

Relevant scripts:

• scripts/device/check_ios_wda_signing.py — verify signing configuration
• scripts/device/install_real_device_wda.py — download, build, and install WDA

Cloning the repo is only for this one-time setup. For day-to-day testing, keep using your installed munk command.

2. Create the signing config file

Create ~/.munk/ios_secrets.env locally (do not commit it to git):

TEAM_ID=YourTeamID
IOS_WDA_BUNDLE_ID=sh.munk.wda
IOS_SIGNING_IDENTITY=Apple Development: Your Name (XXXXXXXXXX)
IOS_PROVISIONING_PROFILE_NAME=YourProfileName

You can also specify the Provisioning Profile in one of these ways (pick one instead of IOS_PROVISIONING_PROFILE_NAME):

# IOS_PROVISIONING_PROFILE_UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
# IOS_PROVISIONING_PROFILE_PATH=~/Downloads/YourProfile.mobileprovision

If the build requires a separate Runner profile, you can add:

# IOS_PROVISIONING_RUNNER_PROFILE_PATH=~/Downloads/YourRunnerProfile.mobileprovision

How to fill each field:

Keep IOS_WDA_BUNDLE_ID as sh.munk.wda. After a successful install, you can leave iOS WDA bundle id empty in Apps—Munk will use the default sh.munk.wda.xctrunner.

3. Check that signing is ready

From the repository root:

python3 scripts/device/check_ios_wda_signing.py \
  --signing-env-file ~/.munk/ios_secrets.env

"ok": true in the output means you can continue. If it is false, fix ios_secrets.env based on the error message and retry.

4. Install WDA on your device

Replace <UDID> with the device UDID from Prerequisites:

python3 scripts/device/install_real_device_wda.py \
  --device-udid <UDID> \
  --signing-env-file ~/.munk/ios_secrets.env

The script downloads source, builds, installs to the phone, launches WDA, and runs a health check. On success, the JSON output includes:

"ok": true,
"stage": "completed"

Useful optional flags:

• --force-rebuild — force a full rebuild
• --force-download — force re-download of WDA source

Reinstall when you change devices, rotate certificates, upgrade iOS major versions, or WDA keeps failing to start.

Connect to Munk and start running

1. Start the service

munk serve --host 127.0.0.1 --port 16888

2. Confirm the device is visible

Open http://127.0.0.1:16888/ in your browser and check the device list under Devices.

You can also confirm via Local API:

http://127.0.0.1:16888/v1/devices?platform=ios

Or via CLI:

munk devices list --platform ios

3. Configure your iOS app

Web UI → Apps → create or edit an app:

4. (Optional) iOS Bridge in Settings

Most users on USB can skip this step.

If you connect over WiFi on iOS 18+, you may need Web UI → Settings:

1. Enable Start ios-device-bridge with sudo
2. Enter your local sudo password

5. Run your first case

Web UI

1. Go to Runs (or start execution from Dashboard)
2. Select your iOS app and connected real device
3. Run a case

CLI quick check

Replace <device-ref> with the device_ref from munk devices list --platform ios:

munk run case \
  --app-id <your-app-id> \
  --plan-id <plan-id> \
  --case-id <case-id> \
  --platform ios \
  --device-ref <device-ref> \
  --bundle-id <app-bundle-id> \
  --config ./munk.yaml

For reproducible workflows like run plan and verify change, maintain the iOS profile in Apps, then launch runs from a JSON request file or the Web UI.

Verify success

After setup, confirm each item:

• munk doctor reports no blocking issues
• The real device appears in the Web UI device list or munk devices list --platform ios
• At least one case completes successfully
• Run details show no persistent WDA launch or session errors

Troubleshooting

What to read next

• Getting Started — install Munk, munk serve, and Web UI basics
• Execution Workflows — run case, run plan, and verify change
• munk-ai repository — WDA install scripts