/dashboard/phones. The Connected section shows whether your Mac is online, which phones it found, and any setup problem it reported.
The dashboard says “Phones is in private beta”
The Phones page of the web dashboard is in private beta. Ask the Appeeky team for access. The API, the MCP tools and Appeeky Desktop work without it, but you need the page to approve actions.My Mac is not listed
The Connected section shows No phones connected, orGET /v1/phones returns an empty connectors array.
My Mac is online but the phone is missing
The Mac shows No phones on this Mac right now. Any problem it found is listed under it and on the Phone page of Appeeky Desktop.Android
- Turn on Developer options → USB debugging and reconnect the cable.
- Unlock the phone and tap Allow on the USB debugging prompt. Until you allow it, the phone is not listed.
- Make sure
adbis installed on the Mac. Appeeky Desktop looks in the Android SDK (~/Library/Android/sdk/platform-tools, orANDROID_HOME/ANDROID_SDK_ROOT) and then on yourPATH. Withoutadb, Android phones are not found and no problem is reported.
iPhone
The iPhone helper app does not start
The Phone page in Appeeky Desktop shows Preparing your iPhone and the current step.- First run takes a few minutes while Xcode builds the helper app. Setup waits up to 8 minutes for it.
- Trust the developer. When the message mentions
VPN & Device Management, open Settings → General → VPN & Device Management on the iPhone and trust your developer certificate. Then use the refresh button. iproxy failed. Install the missing tool withbrew install libimobiledevice.could not start ... Is Xcode installed?Install Xcode on the Mac.
An action fails
Failed actions return status422. Policy errors have their own code. Everything else has the code PHONE_ACTION_FAILED and a message. Over MCP you see the same message as the tool’s error text.
Other statuses:
The agent taps the wrong place
- Use element numbers, not points, whenever the element is numbered.
- Points are screenshot pixels. The screenshot is scaled down so that its longer edge is at most 1,280 pixels. Use the coordinates from the observation, not the phone’s native resolution.
- The screen was still moving. An action waits for the screen to settle before it takes the new screenshot. On a screen that never stops moving, such as a video feed, call
observeagain before you act. - Nothing happens on a locked phone. Unlock it and keep the screen on.
An approval does not arrive
- Check the dashboard first. Requests appear under Waiting for you on
/dashboard/phoneswithin a few seconds. The email can take longer or land in spam. - The tap may not need approval. Only taps and long presses on elements with a label like Post, Send, Buy or Delete pause. See Approvals and safety.
- It expired. A request is valid for 10 minutes. After that it moves to Recent decisions as
expiredand the agent getsAPPROVAL_DENIED. - Approve does nothing or returns an error. The request was already decided or has expired. The API answers
404withNOT_FOUND.
The phone agent stops early
See Phone agent for how runs end.
Still stuck
Check status.appeeky.com for the Phones relay component. Your Mac also keeps a log of every action in~/.agentthumbs/logs/, one file per day, which shows what ran and when.
