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

# Partners

> Build Mobilerun phones into your platform: run tasks for your users and show their phone live in your app.

If you run a platform, you can give each of your users their own Mobilerun phone. An AI agent works on that phone, and your user can watch it live in your app and take over at any time.

This guide shows the steps in order. Your backend does the work with one API key. Your app only shows the phone.

> [!NOTE]
>
> Your API key is a backend secret. Anyone who holds a phone's stream token can see and control that phone. Your backend must check which user owns which phone before it hands out the token.

## What your users see

> [tab] Android
>
> <video autoPlay muted loop playsInline preload="metadata" poster="/images/sdk/sdk-stream-android.jpg" src="https://mintcdn.com/mobilerun/oZ0TQelrSnTN0Cjq/images/sdk/sdk-stream-android.mp4?fit=max&auto=format&n=oZ0TQelrSnTN0Cjq&q=85&s=25894340b3dcdc6948da65bd69e7dc6c" />

> [tab] iPhone
>
> <video autoPlay muted loop playsInline preload="metadata" poster="/images/sdk/sdk-stream-ios.jpg" src="https://mintcdn.com/mobilerun/oZ0TQelrSnTN0Cjq/images/sdk/sdk-stream-ios.mp4?fit=max&auto=format&n=oZ0TQelrSnTN0Cjq&q=85&s=5a2e9474b15d94b1c81fd9c06bd3703c" />

*Illustration — in your app, `DeviceStream` shows the user's phone live, on Android and iPhone.*

> [card] [@mobilerun/react on GitHub](https://github.com/droidrun/mobilerun-react)
>
> The preview shows the component from this repository. It has the source, a local playground, and the [npm package](https://www.npmjs.com/package/@mobilerun/react).

> [card] Kotlin
>
> Coming soon

> [card] Swift
>
> Coming soon

> [card] Flutter
>
> Coming soon

## Build it step by step

**1. Create an API key**

Create an API key in [API keys](https://docs.mobilerun.ai/api-keys.md). Store it as a secret in your backend, for example as `MOBILERUN_API_KEY`. Never put it in browser code.

**2. Optional: add your own LLM key**

By default the agent uses Mobilerun's models and you pay with [credits](https://docs.mobilerun.ai/credits.md). If you prefer, you can use your own LLM key (BYOK).

1. Open [Billing → LLM keys](https://cloud.mobilerun.ai/billing?tab=llm). Only owners and admins can add keys.
2. Add a key from OpenAI, Anthropic or Google.
3. The **Routing** card now lists the models that run on your key. Use one of them as `llmModel` when you run a task.

The token cost goes to your provider. Mobilerun charges a small platform fee in credits instead. See [Credits](https://docs.mobilerun.ai/credits.md).

If your key is rejected or your provider is down, the run continues on Mobilerun's models and uses normal credits. Keep some credits in your account.

**3. Create a phone for each user**

Create a [phone](https://docs.mobilerun.ai/devices.md) when a user signs up, or the first time they need one. Save its ID with your user record. See [device types](https://docs.mobilerun.ai/device-types.md) for the options.

```typescript TypeScript theme={null}
import { MobilerunSDK } from '@mobilerun/sdk';

// Reads MOBILERUN_API_KEY from the environment
const mobilerun = new MobilerunSDK();

// create() returns once the phone is ready
const device = await mobilerun.devices.create({
  deviceType: 'android_cloud_phone',
  billing: 'minute',
});

// Save device.id with your user
```

```python Python theme={null}
from mobilerun_sdk import MobilerunSDK

# Reads MOBILERUN_API_KEY from the environment
mobilerun = MobilerunSDK()

# create() returns once the phone is ready
device = mobilerun.devices.create(device_type="android_cloud_phone", billing="minute")

# Save device.id with your user
```

```bash cURL theme={null}
# Use the "id" in the response as <DEVICE_ID>
curl -s -X POST "https://api.mobilerun.ai/v1/devices?deviceType=android_cloud_phone&billing=minute" \
  -H "Authorization: Bearer $MOBILERUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

# Wait until the phone is ready
curl -s https://api.mobilerun.ai/v1/devices/<DEVICE_ID>/wait \
  -H "Authorization: Bearer $MOBILERUN_API_KEY"
```

**4. Run a task**

Describe what the agent should do in plain language and give it the phone ID. To get the answer back in a fixed shape, add an `outputSchema`.

```typescript TypeScript theme={null}
const task = await device.run({
  task: 'Open Settings and tell me the Android version',
  llmModel: 'mobilerun/mobile-agent-fast',
  maxSteps: 50,
});
```

```python Python theme={null}
task = device.run(
    task="Open Settings and tell me the Android version",
    llm_model="mobilerun/mobile-agent-fast",
    max_steps=50,
)
```

```bash cURL theme={null}
# Use the "id" in the response as <TASK_ID>
curl -s -X POST https://api.mobilerun.ai/v1/tasks \
  -H "Authorization: Bearer $MOBILERUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deviceId": "<DEVICE_ID>",
    "task": "Open Settings and tell me the Android version",
    "llmModel": "mobilerun/mobile-agent-fast",
    "maxSteps": 50
  }'
```

If you use your own LLM key, set `llmModel` to a model from the Routing card. See [Agent](https://docs.mobilerun.ai/agent.md) for all request fields and [Run Task](https://docs.mobilerun.ai/api-reference/tasks/run-task.md) in the API reference.

**5. Follow the task and get the result**

Pick the way that fits your product:

| You want to | Use |
| - | - |
| Wait for the result in your backend | `task.wait()` or `GET /v1/tasks/{id}/status` |
| Show live updates while the task runs | `GET /v1/tasks/{id}/attach` ([API reference](https://docs.mobilerun.ai/api-reference/tasks/attach-task.md)) |
| Be notified when the task is done | [Webhooks](https://docs.mobilerun.ai/webhooks.md) |

```typescript TypeScript theme={null}
const status = await task.wait();
console.log(status.message); // the agent's answer
console.log(status.output);  // your data, if you set an outputSchema
```

```python Python theme={null}
status = task.wait()
print(status.message)  # the agent's answer
print(status.output)   # your data, if you set an output_schema
```

```bash cURL theme={null}
# Check until "status" is "completed". The answer is in "message".
curl -s https://api.mobilerun.ai/v1/tasks/<TASK_ID>/status \
  -H "Authorization: Bearer $MOBILERUN_API_KEY"
```

While a task is running, you can also send a follow-up message or stop it:

```typescript TypeScript theme={null}
// Send a follow-up message to the agent
await task.sendMessage({ message: 'Use the cheaper option instead' });

// Stop the task
await task.stop();
```

```python Python theme={null}
# Send a follow-up message to the agent
task.send_message(message="Use the cheaper option instead")

# Stop the task
task.stop()
```

```bash cURL theme={null}
# Send a follow-up message to the agent
curl -s -X POST https://api.mobilerun.ai/v1/tasks/<TASK_ID>/message \
  -H "Authorization: Bearer $MOBILERUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Use the cheaper option instead"}'

# Stop the task
curl -s -X POST https://api.mobilerun.ai/v1/tasks/<TASK_ID>/cancel \
  -H "Authorization: Bearer $MOBILERUN_API_KEY"
```

With an `outputSchema`, the result is in `output`, in the shape you defined. See [Tasks](https://docs.mobilerun.ai/tasks.md).

**6. Show the phone in your app**

Your backend checks that the user owns the phone, then returns its `streamUrl` and `streamToken`. Your app shows the phone with `@mobilerun/react`:

```tsx theme={null}
<DeviceStream
  streamUrl={streamUrl}
  streamToken={streamToken}
  hasControl
  muted
/>
```

The [embed guide](https://docs.mobilerun.ai/guides/embed-device-stream.md) has the full backend route and the checks to make. The component is on [GitHub](https://github.com/droidrun/mobilerun-react) and [npm](https://www.npmjs.com/package/@mobilerun/react).

**7. Let the user take over**

Some steps should be done by the user, for example a payment. Tell the agent where to stop in the task text:

```text theme={null}
Find the black sneakers in size 42 and add them to the cart.
Stop at the payment screen. Do not pay.
```

The task ends at that point. Your app already shows the live phone, so the user finishes the payment there. With `hasControl` set, the user can tap and type on the phone.

For native iOS or Android apps, [contact us](mailto:contact@mobilerun.ai).

**8. Stop the phone between sessions**

Stop a phone when the user is away. It keeps its apps and logins and uses no phone minutes. Resume it when the user comes back. Terminate it when the user leaves for good.

See [Stop and resume a device](https://docs.mobilerun.ai/devices.md#stop-and-resume-a-device).

## What it costs

* Phone minutes, while a phone is running.
* Credits for the agent's model use. With your own LLM key, you pay your provider and Mobilerun charges a small platform fee in credits.
* Proxies, Cloud Numbers, mailboxes and cards, if you use them. See the [identity stack](https://docs.mobilerun.ai/identity/overview.md).

See [Credits](https://docs.mobilerun.ai/credits.md) for details. To talk about a partnership, write to [contact@mobilerun.ai](mailto:contact@mobilerun.ai).


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