> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appeeky.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Phones

> Let your agents use the real phones plugged into your Mac, with every post, send or payment waiting for your approval.

**Phones** lets your Co-founder and MCP agents use the real Android phones and iPhones plugged into your Mac. They can look at the screen, tap, type, scroll, open apps and copy media into the gallery, for example to post a video to TikTok or Instagram from your own account. Anything that would post, send, pay or delete waits for you to approve it.

> [!NOTE]
>
> Phones are free and work on every plan. They need **Appeeky Desktop** running on a Mac with at least one phone connected.

***

## How it works

```
Agent (MCP or REST)  →  Appeeky  →  Appeeky Desktop on your Mac  →  your phone
                                              │
                    tap on "Post", "Send", "Buy"…  →  waits for you in /dashboard/phones
```

* Actions run through Appeeky Desktop on your own Mac, on phones that are signed in to your own accounts.
* Before a tap on a button like **Post**, **Share**, **Send**, **Publish**, **Submit**, **Buy**, **Pay**, **Subscribe** or **Delete**, the action pauses. You get an email and a card on the **Phones** page with a screenshot of what the agent sees.
* If you don't decide within 10 minutes, the request expires and counts as a no.

***

## Set up

1. Open **Appeeky Desktop** on your Mac and turn on **Settings → Phones → Share phones with Appeeky**.
2. Connect a phone:
   * **Android:** turn on USB debugging, plug it in and accept the prompt on the phone. Emulators work too.
   * **iPhone:** turn on Developer Mode, plug it in and start WebDriverAgent.
3. Keep the phone unlocked while agents use it.
4. Open **`/dashboard/phones`** to check that your Mac shows as **online** with its phones listed. Setup problems show under the Mac.

***

## Dashboard

Route: **`/dashboard/phones`**

| Section | Purpose |
| - | - |
| **Waiting for you** | Pending approvals with the screenshot, the button the agent wants to tap and why. **Approve** or **Deny** |
| **Connected** | Your Macs and the phones on each |
| **Recent decisions** | Approved, denied and expired requests |

***

## API

| Method | Endpoint | Description |
| - | - | - |
| GET | `/v1/phones` | Connected Macs and their phones |
| POST | `/v1/phones/invoke` | Run one action on a phone |
| POST | `/v1/phones/agent` | Give a task to the phone agent and stream its steps |
| GET | `/v1/phones/approvals` | Approvals (`?status=pending` default, `approved`, `denied`, `expired`, `all`) |
| POST | `/v1/phones/approvals/:id/decision` | Approve or deny: `{ "approve": true }`. Signed-in dashboard session only |

These endpoints use 0 API credits.

> [!NOTE]
>
> An API key can't approve an action. Approvals are decided by a person in the dashboard, so an agent can never approve its own tap.

### List phones

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "connectors": [
      {
        "id": "connector-id",
        "name": "Studio MacBook",
        "version": "0.3.1",
        "platform": "darwin",
        "problems": [],
        "connectedAt": "2026-11-01T09:12:00.000Z",
        "devices": [
          { "id": "DEVICE_ID", "name": "Pixel 8", "platform": "android", "driver": "adb" }
        ]
      }
    ]
  }
}
```

### Run an action

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://api.appeeky.com/v1/phones/invoke \
  -H "X-API-Key: $APPEEKY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "invocation": { "method": "tap", "device": "DEVICE_ID", "target": { "element": 12 } } }'
```

`device` is optional when only one phone is connected. Take an `observe` first: it returns a screenshot with numbered boxes over tappable elements, plus the element list. Target an element by its number, or a point with `{ "x": 540, "y": 1200 }` in screenshot pixels.

| `method` | Parameters |
| - | - |
| `devices` | None |
| `observe` | None |
| `tap` | `target` |
| `long_press` | `target`, `durationMs` |
| `swipe` | `from`, `to`, `durationMs` |
| `scroll` | `direction` (`up`, `down`, `left`, `right`), `amount` |
| `type` | `text`. Tap the field first |
| `key` | `key`, e.g. `home`, `back`, `enter`, `delete` |
| `open_app` | `appId`: package name on Android, bundle id on iPhone (see `list_apps`) |
| `list_apps` | None |
| `push_media` | `url`: an `https` image or video to copy into the phone's gallery |

A tap that needs approval holds the request open until you decide, for up to 10 minutes.

### Run the phone agent

Give the agent a task in plain words. It looks at the screen, takes one action at a time and stops when the screen shows the task is done.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
POST /v1/phones/agent
{ "task": "Open TikTok and post the newest video in the gallery with the caption 'Week 3 and still going'", "device": "DEVICE_ID" }
```

| Field | Type | Description |
| - | - | - |
| `task` | string | Required. Up to 2,000 characters |
| `device` | string | Optional device id |

The response streams newline-delimited JSON, one event per line:

| `type` | Fields |
| - | - |
| `screen` | `step`, `image` (base64), `mimeType` |
| `step` | `step`, `action`, `text`, `detail` |
| `done` | `summary`, `steps` |
| `error` | `message`, `code` |

The agent stops after 30 steps. If you deny an approval, it stops and explains. It never enters passwords, codes or payment details that you didn't include in the task.

### Errors

| Status | Code | When |
| - | - | - |
| 400 | `INVALID_REQUEST` | Malformed body or unknown `method` |
| 422 | `APPROVAL_DENIED` | You denied the action, or the request expired |
| 422 | `RATE_LIMITED` | Too many actions in a short time |
| 422 | `PHONE_ACTION_FAILED` | The phone couldn't run the action |
| 404 | `NOT_FOUND` | The approval is gone or already decided |
| 503 | `PHONES_UNAVAILABLE` | Phones aren't available right now |

***

## MCP

The Appeeky MCP server includes the phone tools, so any MCP client can drive your phones. Taps that need approval wait for you in the dashboard.

| Tool | Description |
| - | - |
| `phone_devices` | List connected phones with their ids, platform and screen size |
| `phone_observe` | Screenshot with numbered tappable elements, plus the element list |
| `phone_tap` | Tap an element or a point |
| `phone_long_press` | Press and hold an element or point |
| `phone_swipe` | Drag from one element or point to another |
| `phone_scroll` | Scroll the screen |
| `phone_type` | Type into the focused text field |
| `phone_key` | Press a system key |
| `phone_open_app` | Launch an app |
| `phone_list_apps` | List installed apps |
| `phone_push_media` | Copy an image or video into the phone's gallery |

Example prompt: *"Copy my latest approved UGC clip to my Pixel and post it on TikTok with its caption."*

***

## Tips

* Plug the phone in and unlock it before you start a task. A locked screen stops the agent.
* Sign in to the apps you want agents to use (TikTok, Instagram) on the phone yourself first.
* Keep tasks specific: name the app, the media and the exact caption.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.