Skip to main content
mobilerun-ios runs on the host connected to your iPhone. It prepares the device and exposes its controls and screen to Mobilerun cloud, or serves a local HTTP portal. This reference covers mobilerun-ios v0.4.0. Check mobilerun-ios --version and the installed command’s --help if an option is unavailable. Start with Connect an iPhone for the complete first-device walkthrough.

​
Choose a workflow

Setup and verification

Device preparation, command flags, control modes, and readiness checks.

Configuration

Every config.yaml key, environment overrides, and runtime tuning.

Automatic onboarding

USB discovery, concurrency, factory-state onboarding, and recovery.

Automatic WDA signing

App Store Connect, local Xcode identities, and pre-signed runners.

​
Connect and operate

Replace <udid> with the identifier from list. setup does not log in or start the cloud connection; successful verification is a prerequisite check, not proof that cloud streaming works. Confirm the device appears online in the dashboard and run a task.

​
Background portals

Detached portals write PID and log files under ~/.mobilerun-ios/portals/. stop without a UDID stops all detached portals. Foreground sessions, including auto, are stopped with Ctrl+C or SIGTERM, not with stop. Foreground cloud connections default to a five-attempt retry budget; detached connections retry for up to 30 minutes. Both use exponential backoff. Override with --retry-attempts, --retry-duration, --retry-base-delay, and --retry-max-delay. A zero attempt or duration limit disables that limit. Authentication failures are not fixed by retrying; check whoami, log in again, or replace the API key.

​
Local HTTP portal

Local mode does not require a Mobilerun cloud token. For multiple devices, the port increments from the base address. To bind beyond loopback, provide a bearer token:
Clients send Authorization: Bearer <token>. This is a device-control endpoint, not a public website. Keep it on a trusted network; do not expose it directly to the internet.

​
WDA and native control

  • iOS versions below 27: use WebDriverAgent (WDA).
  • iOS 27+: without a saved choice or installed runner, setup selects native RemoteXPC control. An existing runner keeps WDA as the default.
  • Saved choice: successful setup saves the mode per device; subsequent setup, verify, and portal sessions reuse it.
  • Explicit WDA: use mobilerun-ios setup <udid> --wda.
Native mode still needs Developer Mode and a compatible developer disk image (DDI). It is not feature-equivalent to WDA: system audio, deep links, the on-device SOCKS proxy, the virtual /mobilerun app folder, and factory reset do not have native parity in this release. For native video, use the separate privileged tunnel process. Run only the tunnel with sudo; keep the portal under your normal desktop user so it uses your login and configuration:
Terminal 1
Terminal 2
The default userspace tunnel supports native input, but should not be treated as equivalent to this external-tunnel video layout. The host RemoteXPC tunnel is separate from the WebDriverAgentTunnel app extension used by WDA.

​
Other commands

Use mobilerun-ios --help for the command inventory and mobilerun-ios <command> --help for command-specific syntax. logout clears the saved session token; an exported MOBILERUN_IOS_TOKEN still overrides the file.
mobilerun-ios reset <udid> is a separate, destructive factory-reset operation. It erases device data, requires reset configuration and explicit confirmation (or --yes for non-interactive execution), and must not run alongside a portal or auto. It is not a troubleshooting substitute for setup --reinstall. Automatic onboarding never authorizes a factory reset.