Automatic onboarding

mobilerun-ios auto

auto watches for USB iPhones. For each phone, it runs the same preparation as setup without prompts, verifies readiness, and starts a cloud or local portal. It keeps handling phones that you connect later.

auto changes the phones it finds. It can enable Developer Mode, mount developer disk images, install runners, prepare phones that are still in Setup Assistant, and set Auto-Lock. It never erases a phone, never bypasses Activation Lock or trust prompts, and rejects remote factory-reset requests. By default it manages every USB phone attached to the host. Use --udid to limit it to one phone.

Start with a prepared phone

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

A phone with a working runner needs no signing credentials to be served, and neither does a native-mode phone. auto needs signing configuration only to install a missing runner.

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

# One phone only
mobilerun-ios auto --udid <udid>

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

auto runs in the foreground. Leave it running, or run it under your host’s service manager. Stop it with Ctrl+C or SIGTERM, and let it finish cleaning up. It has no --detach flag, and mobilerun-ios stop does not stop it.

Configuration

auto reads the configuration file and environment once at startup. Restart it after you change credentials, Wi-Fi, or signing settings. To let auto install a missing WDA runner, configure one of these:

App Store Connect: signing.backend: asc, signing.account, and signing.accounts. See App Store Connect.
Xcode: signing.backend: xcode and signing.identity, on a Mac whose login keychain is unlocked. See Unattended Xcode signing.
Pre-signed runner: wda.signed_url, with no signing.* selection. See Pre-signed runners.

signing:
  backend: asc
  account: automation
  accounts:
    - name: automation
      key_id: YOUR_KEY_ID
      issuer_id: YOUR_ISSUER_ID
      p8_path: /Users/you/.mobilerun-ios/keys/AuthKey_YOUR_KEY_ID.p8

auto has none of setup’s --backend, --account, --identity, --wda, or --reinstall flags. Use the YAML keys for signing. To force a control mode, set MOBILERUN_IOS_REMOTE_XPC_ONLY. Otherwise each phone uses its saved or default mode.

Auto-Lock

In WDA mode, auto sets Settings → Display & Brightness → Auto-Lock to Never before it declares a phone ready. It reads the setting back and skips the change if it is already correct. If the setting cannot be changed, readiness fails. The steps expect English Settings, and a device policy can block Never. In native mode, auto leaves Auto-Lock alone. Turning it off is optional: a locked phone still streams, and you can unlock it through the stream or API. To set Never anyway, run:

mobilerun-ios macro run <udid> disable-auto-lock-search

Factory-state phones

When a phone is clearly still in Setup Assistant, auto prepares it without erasing it. It activates and supervises the phone, installs the fleet profile, completes Setup Assistant, and then continues with the normal preparation. This needs:

profile.wifi.ssid and profile.wifi.password, for a protected network with internet access.
supervision_cert and the matching supervision_key, from your device-management process.
The reset_org_name, reset_locale, and reset_lang values you want. Despite the names, these settings do not erase anything.
Signing configuration or wda.signed_url, if the phone will use WDA.

If the state is unknown, auto does not treat the phone as factory-state. A phone that has finished Setup Assistant is served normally even if this configuration is missing. Progress is saved under ~/.mobilerun-ios/onboarding/. If auto stops part-way, the next auto or setup run continues the same onboarding. Keep the same profile: and supervision settings until it has finished. Activation Lock, management by another organization, host trust, developer trust, and the Developer Mode confirmation remain your responsibility. When auto blocks a phone, follow the action in the log.

Flags

Flag	Default	Behavior
`--udid`	All phones	Prepare and serve only this USB phone, including after reconnects.
`--setup-concurrency`	`2`	Most phones prepared at the same time; must be positive. Phones that are already serving do not count.
`--local`	`false`	Serve a local HTTP portal per phone instead of the cloud.
`--local-addr`	`127.0.0.1:8080`	Base local address. The port goes up by one for each phone.
`--local-token`	Unset	Bearer token for the local portal; falls back to `MOBILERUN_IOS_LOCAL_TOKEN`. Required beyond loopback.
`--country`	Detected	ISO two-letter country code for cloud registration. Skips IP-based detection.
`--retry-attempts`	`5`	Reconnect attempts per serving cycle; `0` means unlimited.
`--retry-duration`	`0`	Reconnect window per serving cycle, such as `30m`; `0` means unlimited.
`--retry-base-delay`	`1s`	First reconnect delay; must be positive.
`--retry-max-delay`	`30s`	Longest reconnect delay; at least the base delay.
`--telemetry`	`true`	Send anonymous usage metrics. Environment: `MOBILERUN_IOS_TELEMETRY`.

Global flags: --log-level, --verbose / -v, and --tunnel-mode. auto does not accept the root command’s video and audio flags. Use their environment variables.

Retries do not end auto

The --retry-* flags limit reconnects within one serving cycle. When they run out, auto rebuilds that phone’s portal and keeps going. Preparation errors are retried too, with a delay that grows from 1 second to 30 seconds. Running out of retries does not stop auto or abandon the phone. A phone that needs you to act on it is parked instead of retried. Fix the condition on the phone, then disconnect it and connect it again while auto keeps running. For host configuration changes, restart auto. A parked phone does not block the others.

Local ports

A phone keeps its local port while it reconnects. After a phone disconnects, its port can go to another phone, so do not treat a port as a fixed mapping to a UDID. Read the readiness log line for each phone’s address. auto does not take over a port that another process is using.

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. Keep the portal on a trusted network; it is plain HTTP, not TLS.

Recovery

Log category	What to do
`host-trust`	Unlock the phone and accept Trust This Computer, then reconnect USB.
`developer-mode`	Turn on Developer Mode, restart, unlock, and confirm Turn On. Then reconnect.
`activation`	Activate the phone with the Apple Account that owns it. `auto` cannot remove Activation Lock.
`wifi-config`, `supervision-cert`, `supervision-key`, `configuration`	Stop `auto`, fix the fleet profile or supervision settings, and restart it.
`supervision`	Resolve who manages the phone, and check that this host has the matching supervision identity.
`signing`	Stop `auto` and fix the backend, account, identity, profiles, or pre-signed artifact.
`trust`	Give the phone internet access and trust the developer profile, then reconnect. For an expired signature, stop `auto` and run `setup --reinstall`.
`normalization`	Check that Auto-Lock can be set to Never and that Settings is in English, then reconnect.
`cleanup`	Stop `auto` and wait until the previous session has closed before you restart it. Contact support if it continues.
`local-port`	Restart with enough free ports.

auto keeps installed runners and mounted images. It does not upgrade WDA or renew expired signing. Repair a phone with setup, then let auto serve it again. A ready phone is not proof that every stream and API feature works on every iPhone. Test a real cloud task and the browser stream on your phones, especially with native control or a different tunnel layout.

Get started

Phones

Apps & networking

Run automation

Integrations

Developer tools

Automatic onboarding

Start with a prepared phone

Configuration

Auto-Lock

Factory-state phones

Flags

Retries do not end auto

Local ports

Recovery

​Start with a prepared phone

​Configuration

​Auto-Lock

​Factory-state phones

​Flags

​Retries do not end auto

​Local ports

​Recovery

Start with a prepared phone

Configuration

Auto-Lock

Factory-state phones

Flags

Retries do not end auto

Local ports

Recovery