Debugging iOS Devices with Xcode over Wi‑Fi and Remote usbmuxd Forwarding

Xcode is Apple’s integrated development environment for iOS development, and traditionally it requires a USB connection to a physical iOS device for debugging.

Because newer MacBooks only have USB‑C ports, connecting a device via cable is inconvenient, and Xcode cannot directly debug a device that is not physically attached.

The article first describes the official Xcode 9 Wi‑Fi debugging method: install the latest Xcode 9, run iOS 11 on the device, ensure both Mac and iOS device are on the same Wi‑Fi network, open Window → Devices and Simulators, select the device, and enable “Connect via network”. Once enabled, the device can be debugged wirelessly even after unplugging the cable.

While convenient, this approach has limitations: it only works with Xcode 9 and iOS 11 (both still in beta at the time) and requires the device to be on the same local network, which is not suitable for remote debugging.

To overcome these limits, the article explains the iOS‑Mac communication protocol. macOS runs a service called usbmuxd (USB multiplexing daemon) that translates USB traffic into TCP streams. Xcode and iTunes communicate with the device via a local Unix socket ( /var/run/usbmuxd), not directly over USB.

Two key observations are made: (1) implementing usbmuxd on any OS allows communication with iOS devices without macOS, and (2) forwarding the TCP stream of usbmuxd enables device connections across different machines.

The article introduces socat, a Linux utility similar to an enhanced netcat, which can forward ports and Unix sockets. It can be installed on macOS via brew install socat or through standard package managers on Linux.

Using socat, the local /var/run/usbmuxd socket is redirected to a remote machine’s TCP port, and the remote machine forwards that port back to its own /var/run/usbmuxd socket, effectively making the remote iOS device appear as if it were connected locally.

Specific socat commands are provided:

mv /var/run/usbmuxd /var/run/usbmuxx

socat UNIX-LISTEN:/var/run/usbmuxd,mode=777,reuseaddr,fork TCP:XXX.XXX.XXX.XXX:8555

(run on the local machine)

socat TCP-LISTEN:8555,reuseaddr,fork UNIX-CONNECT:/var/run/usbmuxd

(run on the remote machine)

After setting up the forwarding, all iOS devices connected to the remote machine can be accessed by Xcode on the local machine just like locally attached devices.

For further details, the article links to an expert column on the principles of remote control for non‑jailbroken iOS devices.