Skip to main content
Start with /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, or GET /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 adb is installed on the Mac. Appeeky Desktop looks in the Android SDK (~/Library/Android/sdk/platform-tools, or ANDROID_HOME / ANDROID_SDK_ROOT) and then on your PATH. Without adb, 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 with brew install libimobiledevice.
  • could not start ... Is Xcode installed? Install Xcode on the Mac.

An action fails

Failed actions return status 422. 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 observe again 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/phones within 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 expired and the agent gets APPROVAL_DENIED.
  • Approve does nothing or returns an error. The request was already decided or has expired. The API answers 404 with NOT_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.