Skip to content
ios-agent

Installation

Requirements

Section titled “Requirements”
For You need
Simulator macOS, Xcode 16.3+, an iOS runtime, Python 3.12+
Physical iPhone the above plus go-ios, Developer Mode, and a signing identity. Follow docs/real-device-setup.md, which is a longer road than the simulator and has a few steps that look like bugs but are not

Xcode ships without a simulator runtime. If xcrun simctl list runtimes is empty, xcodebuild -downloadPlatform iOS fetches one (around 8 GB). If a runtime is installed but no simulator has been created, ios-agent offers to create one for you: that part takes about a second.

Setup

Section titled “Setup”
Terminal window
uv sync
./scripts/prepare_wda.sh simulator   # builds WebDriverAgent, once
uv run ios-agent doctor              # says exactly what is still missing

doctor is the first thing to run whenever anything misbehaves. It checks the toolchain, the simulator runtimes, the tunnel, WebDriverAgent’s signing expiry and the model, and returns a remedy for each failure rather than letting it surface later as a connection error.

The app runs those same checks before it touches a device, so a machine that is not set up is told so in about a second rather than after a simulator has booted.