> ## Documentation Index > Fetch the complete documentation index at: https://docs.mobilerun.ai/llms.txt > Use this file to discover all available pages before exploring further. # Automatic onboarding > Continuously discover USB iPhones, prepare them without erasing, and start their portals. ```bash theme={null} 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 1. Complete [Connect an iPhone](/guides/connect-iphone), including host trust and Developer Mode. 2. Stop any existing portal for that phone. 3. Authenticate with `mobilerun-ios login`, or export `MOBILERUN_IOS_TOKEN` for an API key. 4. Start `mobilerun-ios auto` and connect the phone over USB. 5. 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. ```bash theme={null} # 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](/mobilerun-ios/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](/mobilerun-ios/wda-signing#app-store-connect), selected using YAML `backend: asc` and `account`. * A [local Xcode identity](/mobilerun-ios/wda-signing#local-xcode-signing), selected using YAML `backend: xcode` and `identity`, with matching provisioning profiles already available. * A [pre-signed runner](/mobilerun-ios/wda-signing#pre-signed-runners-for-auto) 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](/mobilerun-ios/setup-and-verify#control-mode-persistence) 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](/mobilerun-ios/configuration#video-and-audio). ### 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. ```bash theme={null} 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](/mobilerun-ios/setup-and-verify) 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.