Automatic onboarding

mobilerun-ios auto

auto watches for USB iPhones, prepares each device, verifies readiness, sets and verifies Auto-Lock to Never, and starts a cloud or local portal. It keeps watching for newly attached phones after startup, unlike the root command’s initial device selection.

Auto is an opt-in device-modifying workflow, not a read-only watcher. It can enable Developer Mode, install missing developer images and runners, configure factory-state phones, and change Auto-Lock. It never erases a device, never bypasses Activation Lock or trust prompts, and refuses remote factory-reset requests. Connect only phones you intend this host to prepare: the command accepts no UDID filter.

Start with a prepared phone

Complete Connect an iPhone, including host trust and Developer Mode.
Stop any existing portal for that phone.
Authenticate with mobilerun-ios login, or export MOBILERUN_IOS_TOKEN for an API key.
Start mobilerun-ios auto and connect the phone over USB.
Wait for the automatic device ready log, then confirm the phone is online in the dashboard and run a task.

A prepared WDA phone does not need signing credentials merely to serve its installed runner. Native devices likewise do not need WDA signing. Credentials are needed only when a missing WDA runner must be installed, unless a usable pre-signed artifact is configured.

# Cloud, with explicit country instead of IP-based country detection
mobilerun-ios auto --country US --setup-concurrency 2

# Local HTTP portals, no cloud login required
mobilerun-ios auto --local --local-addr 127.0.0.1:8080

Auto is a foreground process. Leave it running, or supervise it with your host’s process manager. Stop it with Ctrl+C or SIGTERM and allow cleanup to finish. It has no --detach flag and is not managed by mobilerun-ios stop.

Configuration

Auto reads host configuration and environment values at startup. Restart it after changing credentials, Wi-Fi settings, or signing defaults. For automatic installation of missing WDA runners, choose one of:

An ASC signing account, selected using YAML backend: asc and account.
A local Xcode identity, selected using YAML backend: xcode and identity, with matching provisioning profiles already available.
A pre-signed runner in wda_ipa_url that is valid for the target phone.

Auto does not expose setup’s --account, --backend, --identity, --wda, or --reinstall flags. Use YAML for signing selection and MOBILERUN_IOS_REMOTE_XPC_ONLY for an explicit runtime control mode. Otherwise, the saved/default mode applies independently to each device.

Factory-state phones

When the device is positively identified as still in Setup Assistant, auto can prepare it without erasing it first. This path requires:

wifi_ssid and a non-empty wifi_password.
A valid supervision_cert and matching supervision_key owned by your device-management workflow.
Appropriate reset_org_name, reset_locale, and reset_lang values (these names also apply to non-erasing onboarding).
Signing configuration or a pre-signed artifact if the selected mode needs a missing WDA runner.

Auto checks activation and management state, prepares the device, completes its onboarding session, reopens and verifies it after any reconnect/reboot, and only then attempts to serve it. Unknown Setup Assistant state does not authorize factory preparation. A phone with completed Setup Assistant is not treated as a factory-state device, and missing factory configuration does not by itself block an already-prepared phone. Activation Lock, existing management/supervision ownership, host trust, developer trust, and manual Developer Mode confirmation remain operator responsibilities. Follow the blocked log’s action rather than expecting auto to bypass them.

Flags

Flag	Default	Behavior
`--setup-concurrency`	`2`	Maximum devices preparing concurrently; must be positive. Already-serving devices do not consume preparation slots. Shared signing work is serialized on the host.
`--local`	`false`	Serve a local HTTP portal per phone instead of the cloud relay.
`--local-addr`	`127.0.0.1:8080`	Base local address; port increments per device.
`--local-token`	Unset	Local HTTP bearer token; falls back to `MOBILERUN_IOS_LOCAL_TOKEN`. Mandatory beyond loopback.
`--country`	Auto-detected	ISO two-letter country code for cloud registration; skips IP-based detection.
`--retry-attempts`	`5`	Portal connection attempt budget; `0` means unlimited.
`--retry-duration`	`0`	Portal reconnect window, such as `30m`; `0` means unlimited.
`--retry-base-delay`	`1s`	Initial portal retry backoff; must be positive.
`--retry-max-delay`	`30s`	Maximum portal retry backoff; at least the base delay.
`--telemetry`	`true`	Enable/disable anonymous usage metrics; environment: `MOBILERUN_IOS_TELEMETRY`.

Inherited flags: --log-level, --verbose / -v, and --tunnel-mode. Video/audio root flags are not inherited; use their environment variables.

Retry limits are not a process lifetime

The --retry-* flags govern portal reconnect attempts within a serving cycle. Auto also retries temporary preparation or connection failures with backoff from one second up to 30 seconds. Exhausting a portal retry budget therefore does not mean the auto process exits or gives up on the phone permanently. Manual blockers are parked instead of retried continuously. Resolve the on-device condition, then physically detach and reconnect. For host configuration changes, stop and restart auto. A blocked phone does not prevent other eligible phones from preparing.

Local ports

A device keeps its local port while retrying. After a device disconnects, that port may be assigned to another phone, so do not treat a port number as a permanent UDID mapping. Read the device/address readiness logs. Auto does not displace a process already listening on a requested port.

export MOBILERUN_IOS_LOCAL_TOKEN='replace-with-a-long-random-secret'
mobilerun-ios auto --local --local-addr 0.0.0.0:8080

Clients must send the bearer token. Limit access to a trusted network; local HTTP is not TLS-protected by this flag.

Recovery and limitations

Log category / symptom	What to do
`host-trust`	Unlock and accept Trust This Computer, then reconnect USB.
`developer-mode`	Enable Developer Mode, reboot, unlock, confirm Turn On, then reconnect.
`activation`	Complete activation with the owning Apple Account. Auto cannot remove Activation Lock.
`wifi-config`, `supervision-cert`, `supervision-key`, `configuration`	Stop auto, correct the factory-state configuration, and restart.
`supervision`	Resolve management ownership and the matching host supervision identity.
`signing`	Stop auto and fix the backend, account, identity, profiles, or pre-signed artifact.
`trust`	Give the phone internet access and trust its developer profile, then reconnect. For expired signing, stop auto and explicitly run `setup --reinstall`.
`normalization`	Verify Auto-Lock can be set to Never; check device policy and supported UI language, then reconnect.
`cleanup`	Stop auto and ensure the previous device session has closed before restarting. If the error persists, contact support.
`local-port`	Restart with enough available ports.

Auto intentionally preserves installed runners and mounted images. It is not an automatic WDA upgrade or expired-certificate renewal service. Use setup and verification for explicit repairs, then restart auto. Automatic readiness does not prove every stream or API feature works on every iPhone. Validate an actual cloud task and browser stream for your devices, particularly when using native control or a different tunnel/network layout.

Introduction

Concepts

Guides

Mobilerun iOS

Assistant

Dashboard

Agent Skills

Integrations

Automatic onboarding

Start with a prepared phone

Configuration

Factory-state phones

Flags

Retry limits are not a process lifetime

Local ports

Recovery and limitations

​Start with a prepared phone

​Configuration

​Factory-state phones

​Flags

​Retry limits are not a process lifetime

​Local ports

​Recovery and limitations

Start with a prepared phone

Configuration

Factory-state phones

Flags

Retry limits are not a process lifetime

Local ports

Recovery and limitations