pymobiledevice3 remote¶
Create and browse RemoteXPC tunnels (RSD/tunneld) for developer services.
tunneld¶
Run tunneld: keep an iOS 17+ tunnel up for every device (needs root).
Rarely needed: commands build their own no-root tunnel. Use it to share
tunnels across processes or with other tools, then pass --tunnel to
commands. Runs until Ctrl+C (or in the background with --daemonize).
Options:
| Option | Description |
|---|---|
--host <str> |
Address to bind the tunneld server to. [default: 127.0.0.1] |
--port <int> |
Port to bind the tunneld server to. [default: 49151] |
--upstream <str> |
URL of another tunneld to federate (repeatable). Its devices appear in this instance's listing, and connections to them are relayed through it, so clients need a route to this tunneld only. |
-d, --daemonize |
Run tunneld in the background. |
-p, --protocol <tcp\|quic> |
Transport protocol for the tunnels tunneld creates. [default: (tcp on Python >= 3.13, otherwise quic)] |
--usb / --no-usb |
Tunnel USB devices through their USB network (RSD) interface. [default: usb] |
--wifi / --no-wifi |
Tunnel paired devices advertising RemotePairing on the network (bonjour). [default: wifi] |
--usbmux-address <str> |
Address of the usbmuxd daemon (unix socket path or HOST:PORT). Defaults to the platform usbmuxd if omitted. [env var: PYMOBILEDEVICE3_USBMUX, USBMUXD_SOCKET_ADDRESS] |
Accepts the connection options: --usbmux, --mobdev2.
browse¶
List iOS 17+ devices reachable for tunneling.
Asks Apple's remotepairingd on macOS by default, browses bonjour elsewhere.
Options:
| Option | Description |
|---|---|
--timeout <float> |
Browse timeout (in seconds) [default: 3] |
--native / --no-native |
Browse via Apple's remotepairingd (the remoted tunnel daemon) instead of bonjour; no root, macOS only, and the default there unless PYMOBILEDEVICE3_DEFAULT_FALLBACK=tunneld. --no-native forces the bonjour browse. |
rsd-info¶
Print the device's RemoteServiceDiscovery (RSD) info: properties and available services.
Options:
| Option | Description |
|---|---|
--native |
macOS only: reach the iOS 17+ tunnel by piggybacking Apple's own remoted tunnel via the remotepairingd service. NO root, no entitlement, no Xcode. Rides Apple's kernel-routable tunnel, so throughput matches the kernel tunnel, but the device keeps a single RSD connection on it: remoted and this process evict each other's, which can reset connections and leave Xcode/devicectl without the device until remoted reconnects. Mutually exclusive with --rsd/--tunnel/--userspace. [env var: PYMOBILEDEVICE3_NATIVE] |
Accepts the connection options: --rsd, --tunnel, --userspace.
auxiliary-metadata¶
Print the device's auxiliary metadata (decoded deviceKVSData), keyed by preference domain.
e.g. com.apple.WebInspector.EnableRemoteInspection (Web Inspector
on/off). Reliably populated on the macOS --native transport; empty or
partial on others (see the network-stacks guide).
Options:
| Option | Description |
|---|---|
--native |
macOS only: reach the iOS 17+ tunnel by piggybacking Apple's own remoted tunnel via the remotepairingd service. NO root, no entitlement, no Xcode. Rides Apple's kernel-routable tunnel, so throughput matches the kernel tunnel, but the device keeps a single RSD connection on it: remoted and this process evict each other's, which can reset connections and leave Xcode/devicectl without the device until remoted reconnects. Mutually exclusive with --rsd/--tunnel/--userspace. [env var: PYMOBILEDEVICE3_NATIVE] |
Accepts the connection options: --rsd, --tunnel, --userspace.
start-tunnel¶
Start an iOS 17+ tunnel and print the --rsd HOST PORT to reach it.
Rarely needed: commands build their own no-root tunnel. Use it when another process needs --rsd. By default this creates a classic tunnel, which needs root; --native piggybacks Apple's tunnel on macOS without root. Runs until Ctrl+C.
Options:
| Option | Description |
|---|---|
-t, --connection-type <usb\|wifi> |
Connection interface to tunnel (USB, WiFi, etc.). [default: usb] |
--secrets <path> |
File to write TLS secrets for Wireshark decryption. |
--script-mode / --no-script-mode |
Print only HOST and port for scripts instead of formatted output. [default: no-script-mode] |
--max-idle-timeout <float> |
Maximum idle time before QUIC keepalive pings are sent. [default: (30.0)] |
-p, --protocol <tcp\|quic> |
Transport protocol for the tunnel. [default: (TCP on Python >=3.13, otherwise QUIC)] |
--native / --no-native |
Piggyback Apple's remoted tunnel via remotepairingd and publish its RSD address instead of creating a new tunnel; no root, macOS only. Its RSD connection and remoted's evict each other, so it is opt-in (or PYMOBILEDEVICE3_DEFAULT_FALLBACK=native). --no-native forces the classic (root) tunnel, as does passing any of the classic-tunnel options. |
Accepts the connection options: --udid.
pair¶
Pair over the network with a device offering manual pairing (e.g. Apple TV).
Browses bonjour for devices advertising manual pairing, such as Apple TV or Apple Vision Pro; the device shows a PIN to type in. Standard iOS devices usually do not need this.
Options:
| Option | Description |
|---|---|
--name <str> |
Only pair with the device advertising this name. |
pair-host¶
Advertise as a pairable host and accept a device-initiated pairing (iOS 27+).
The device does not browse for pairable hosts automatically. On the device,
enable Developer Mode and open Settings > Developer > Paired Macs; this host
then appears under "Other Devices". Tap it and enter the 6-digit code
printed here. The resulting pairing record is reused by
remote start-tunnel afterwards. Waits until paired, --timeout, or Ctrl+C.
Options:
| Option | Description |
|---|---|
--name <str> |
Name shown on the device (defaults to this machine's hostname) |
--model <str> |
Hardware model identifier shown on the device [default: Mac17,7] |
--port <int> |
TCP port to listen on (0 = pick a free port) [default: 0] |
--timeout <float> |
Give up after this many seconds if no device starts pairing |
delete-pair¶
Delete this host's RemotePairing record for a device (forces pairing again).
Arguments:
| Argument | Description |
|---|---|
udid |
Identifier (UDID) of the device whose pairing record to delete. [required] |
service¶
Connect to a RemoteXPC service and open an IPython shell on it (for exploration).
Arguments:
| Argument | Description |
|---|---|
service_name |
RSD service name (see remote rsd-info). [required] |
Options:
| Option | Description |
|---|---|
--native |
macOS only: reach the iOS 17+ tunnel by piggybacking Apple's own remoted tunnel via the remotepairingd service. NO root, no entitlement, no Xcode. Rides Apple's kernel-routable tunnel, so throughput matches the kernel tunnel, but the device keeps a single RSD connection on it: remoted and this process evict each other's, which can reset connections and leave Xcode/devicectl without the device until remoted reconnects. Mutually exclusive with --rsd/--tunnel/--userspace. [env var: PYMOBILEDEVICE3_NATIVE] |
Accepts the connection options: --rsd, --tunnel, --userspace.