> ## 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.

# Quickstart

> Connect a phone to your Mac, let an agent look at the screen and approve your first action.

This guide takes you from nothing to a tap that waited for your approval. It uses an Android phone because it needs the least setup. For an iPhone, follow [Connect phones](https://docs.appeeky.com/docs/phones/connect-phones.md) first and come back at step 3.

> [!NOTE]
>
> You need a Mac with **Appeeky Desktop** and an Appeeky account. To call the API you also need an API key. See [Authentication](https://docs.appeeky.com/docs/authentication.md). The API key must belong to the same account you use in Appeeky Desktop.

***

## Set it up

**1. Turn on phone sharing**

Open **Appeeky Desktop** and sign in. Go to **Settings → Phones** and turn on **Share phones with Appeeky**. The badge next to it changes to **Connected**.

**2. Connect the phone**

On the Android phone, turn on **Developer options → USB debugging**. Connect it to the Mac with a USB cable and tap **Allow** on the phone. Keep the phone unlocked.

**3. Check that Appeeky sees it**

Open **`/dashboard/phones`** in the web dashboard. Under **Connected** you see your Mac with an **online** badge and the phone below it.

You can run the same check with the API:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://api.appeeky.com/v1/phones \
  -H "X-API-Key: $APPEEKY_API_KEY"
```

**4. Look at the screen**

Ask for an observation. It returns a screenshot and a numbered list of the elements on screen.

```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": "observe" } }'
```

With one phone connected you can leave out `device`. The `description` field lists each element with its number, for example `[12] "Send" (button, clickable) at 512,1180`.

**5. Trigger an approval**

On the phone, open any screen that has a button labelled **Send**, **Post** or **Share**, for example a draft message to yourself. Run `observe` again, find the number of that button, and tap it:

```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", "target": { "element": 12 } } }'
```

The request stays open. Nothing is tapped yet.

**6. Approve it**

Open **`/dashboard/phones`**. Under **Waiting for you** there is a card with the screenshot, the button the agent wants to tap and the reason. Choose **Approve**. The tap runs on the phone and the `curl` request returns the new screen.

You also get an email with a link to this page.

> [!NOTE]
>
> Element numbers are only valid for the latest observation. After any action, use the numbers from the screenshot that the action returned.

***

## Use it from an AI assistant

If your assistant is connected to the [Appeeky MCP server](https://docs.appeeky.com/docs/mcp.md), it already has the phone tools. Ask in plain words:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Look at my phone and tell me which app is open.
```

The assistant calls `phone_observe` and reads the screen. See [MCP tools](https://docs.appeeky.com/docs/phones/mcp.md).

***

## Give the phone agent a task

Open the **Phone** page in Appeeky Desktop, type a task under **Agent** and choose **Run**. Or call the API:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -N -X POST https://api.appeeky.com/v1/phones/agent \
  -H "X-API-Key: $APPEEKY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "task": "Open Settings and turn on dark mode" }'
```

See [Phone agent](https://docs.appeeky.com/docs/phones/phone-agent.md).

***

## Next steps

* [Actions](https://docs.appeeky.com/docs/phones/actions.md): everything an agent can do on the phone.
* [Approvals and safety](https://docs.appeeky.com/docs/phones/approvals-and-safety.md): what pauses and what does not.
* [Troubleshooting](https://docs.appeeky.com/docs/phones/troubleshooting.md): when the phone does not show up or an action fails.


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