remote-device

Pair an iPhone over Apple's DeviceHub and let coding agents drive it, the way they drive a simulator. No Xcode, no native modules, zero dependencies.

npx remote-device

The first run advertises this computer as a pairable host. On the iPhone, open Settings → Privacy & Security → Developer Mode → Remote Device Pairing, pick this computer, and type the 6-digit code from the terminal. The pairing is saved in ~/.remote-device/, and every later run finds the phone on the network and goes straight to serving.

Hand it to an agent

npx remote-device argent        # publishes an Argent provider; drive it with argent's own tools
npx remote-device agent-device  # prints the `agent-device connect proxy` command to run
npx remote-device mcp           # MCP server on stdio

For MCP, point your client at it:

{ "mcpServers": { "iphone": { "command": "npx", "args": ["-y", "remote-device", "mcp"] } } }

Tools: device_info, screenshot, list_elements, list_apps, launch_app, list_processes, tap, swipe, type_text, press_key, press_button, release_keyboard.

Everything is also an HTTP API on http://127.0.0.1:41777. GET / lists the routes. --token (or REMOTE_DEVICE_TOKEN) adds bearer auth; the bridge only binds localhost.

Commands

remote-device                 pair if needed, then run the bridge
remote-device pair            pair (again)
remote-device devices         saved pairings
remote-device unpair <udid>
remote-device import          import pymobiledevice3 remote_<udid>.plist pairings
remote-device status
remote-device screenshot -o shot.png
remote-device apps | launch <bundleId> | tap <x> <y> | type <text>
remote-device elements        accessibility elements on screen
remote-device mcp | argent | agent-device

Options: --host (any routable address, such as a tailnet IP), --port, --device, --bridge-port, --token, --name, --json, --quiet.

Worth knowing

• Needs iOS 17+ with Developer Mode on, and an IP path to the phone: same Wi-Fi, or --host.
• Elements come with labels, traits and identifiers but no frames, so tap by reading a screenshot.
• Typing registers a virtual keyboard, which hides the phone's own. It is released after five seconds idle, or immediately with release_keyboard.
• iOS ignores injected keystrokes in secure fields, so passcodes and the pairing code have to be typed by a person. That is what makes pairing the trust anchor for everything else.
• Installing an IPA is not implemented.