An Android phone
Use Parallax on a physical Android phone over USB, what it does for Metro, and what differs from an emulator.
Parallax works with a physical Android phone as it does with an emulator: the window shows its screen and takes input, and the agent's device tools act on it. A real iPhone is watch only: see A real iPhone.
Connect the phone
- On the phone, open Settings > About phone and tap Build number seven times. Then turn on Settings > Developer options > USB debugging.
- Plug the phone into the Mac with a cable that carries data. A charge-only cable shows nothing in
adb devices. - Accept the Allow USB debugging? prompt on the phone. Parallax never accepts it for you: until you do, the phone is listed as not usable, with this instruction.
The phone then shows in device_list and in the window's device menu under Phones, named by its model (for example SM-S928B), with a Real phone chip.
Wi-Fi debugging: not tried yet
On Android 11 and later you can pair over Wi-Fi instead: Developer options > Wireless debugging > Pair device with pairing code, then adb pair <ip:port> with the code and adb connect <ip:port> with the address the phone shows. The phone appears the same way. This has not been tried on a real phone yet.
Metro
The app on a phone reaches Metro on your Mac through adb reverse tcp:<port> tcp:<port> (React Native's run-android does it for 8081). While the window is open, Parallax does it for the Metro it sees, once per phone and port, and again after the phone is plugged back in. doctor has a row, "Phone: Metro port (adb reverse)", that says whether it is set and gives the command when it is not. An emulator needs none of this.
What differs from an emulator
- Parallax cannot boot or shut down a phone.
device_bootand the window's Boot and Shut down say so. - The window shows the phone's real screen, so its notifications and other apps show there too. A note above the screen says so once.
- Taps, swipes and typing, from the window and from the agent, act on the real phone.
app_data source: storagereads simulators and emulators only, not a phone.
No picture
The picture and the window's input need scrcpy-server, the same file as for emulators. When it is missing or cannot start on the phone, the window shows no picture for it and says why. The agent's tools (device_ui, device_tap, device_swipe, device_type, device_screenshot) and the panels still work through adb.
Phones that block input
Some phones block injected input until a developer setting is on. Without it, both adb shell input and the window's input fail.
- Xiaomi and Poco: "USB debugging (Security settings)". It needs a SIM card and a Mi account.
- Some Oppo and Vivo phones: "Disable permission monitoring".
- Samsung: nothing extra. Tried on a Galaxy S24 Ultra with Android 16.