Skip to content
xcross
Documentation menu

Run over Wi-Fi

Pair an iPhone for wireless development, open its RSD tunnel, and run Flutter apps without a USB cable.

xcross can install, launch, debug, and hot-reload a Flutter app over Wi-Fi. Wireless use needs a one-time pairing between the host and iPhone, followed by a wireless RSD tunnel.

Quick setup

Keep the iPhone unlocked and on the same local network as the host, then run:

xcross tunnel --wifi

The command chooses the best available setup path automatically:

  1. iPhone connected over USB: xcross creates the wireless RemotePairing record through the trusted USB lockdown connection, enables Wi-Fi connections, opens the RSD tunnel, and mounts the Developer Disk Image. When it finishes, unplug the cable.
  2. No USB, but a saved wireless pairing exists: xcross first tries to reconnect to the saved device.
  3. No USB and reconnection fails: xcross advertises a fresh pairing host. This device-initiated flow requires iOS 27 or later.

After the tunnel is ready, run the app explicitly over Wi-Fi:

cd my_flutter_app
xcross flutter run --wifi

NotePlain xcross tunnel is the USB-only preparation command. Use xcross tunnel --wifi when preparing a wireless connection.

The most reliable first-time setup works on every supported iOS version:

  1. Connect the iPhone over USB.
  2. Unlock it and tap Trust This Computer if prompted.
  3. Run xcross tunnel --wifi.
  4. Wait for Device ready — paired over USB, wireless RSD tunnel up.
  5. Unplug USB and run xcross flutter run --wifi.

xcross uses pymobiledevice3 lockdown remotepairing --pair for this step. It reuses the existing USB trust without requiring the six-digit Paired Devices flow.

Pair without USB on iOS 27+

When there is no usable saved pairing and no USB device, xcross tunnel --wifi prints an entry such as xcross-my-host-a1b2 and waits for the iPhone:

  1. On the iPhone, open Settings > Privacy and Security > Developer Mode > Paired Devices > Other Devices.
  2. Tap the exact xcross-... name printed by the command.
  3. Enter the six-digit code shown in the xcross terminal.
  4. Keep the phone unlocked while xcross creates the tunnel and mounts the Developer Disk Image.

Device-initiated remote pair-host pairing is available only on iOS 27+. On iOS 17 through 26, connect over USB once and use the recommended setup above.

If xcross found a saved record but could not reconnect, it waits for that attempt first, then advertises a fresh suffixed name. Tap that exact new name under Other Devices. Delete the older unsuffixed xcross-<host> entry if it is still shown under Paired Devices because it represents the stale pairing.

Device selection

CommandBehavior
xcross flutter runSearches both transports, but prefers a locally attached USB device when USB and Wi-Fi are both available. Falls back to Wi-Fi when no USB device exists.
xcross flutter run --wifiSearches Wi-Fi devices only.
xcross flutter run --usbSearches USB devices only.
xcross flutter run -u <UDID>Selects a specific device explicitly.

Network requirements

  • The iPhone and host must be on the same local subnet.
  • Keep the iPhone unlocked with its screen on during pairing and initial connection.
  • Multicast DNS must be allowed. Wireless discovery uses mDNS on UDP port 5353.
  • Guest Wi-Fi client isolation, VPN routing, firewalls, NAT, and bridged VM or WSL networking can prevent discovery.
  • Creating the kernel RSD tunnel requires sudo on Linux or an Administrator terminal on Windows unless a compatible daemon is already running.

Troubleshooting

Run with verbose logging to see USB detection, Bonjour discovery, saved-pairing retries, and pair-host output:

xcross tunnel --wifi -v

Saved device does not reconnect

Keep the phone unlocked and wait for the saved-device attempt to finish. xcross then starts a fresh pair-host automatically. On iOS 27+, tap the newly suffixed host under Other Devices. On older iOS, reconnect USB and rerun xcross tunnel --wifi to refresh the RemotePairing record.

The host appears on the iPhone, but no code appears

Confirm you tapped the exact fresh name printed by the current command, not an older entry. Also verify both devices are on the same subnet and that UDP 5353 and the advertised TCP pairing port are not blocked.

USB is connected but not detected

On Linux, check that usbmuxd is running and that the phone is trusted:

sudo systemctl start usbmuxd
pymobiledevice3 usbmux list --usb

With WSL or usbipd, also verify USBMUXD_SOCKET_ADDRESS and that the iPhone is attached to the Linux side.

See also

Edit on GitHubReport an issue
ESC