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

# Mobilerun SDK

> Control cloud devices and run agent tasks from your code with the Mobilerun SDK for TypeScript and Python.

> [!NOTE]
>
> The SDK needs `@mobilerun/sdk` (TypeScript) or `mobilerun-sdk` (Python) 6.2.0 or later.
> It reads your key from the `MOBILERUN_API_KEY` environment variable.

## What the SDK can do

* Create a device and get it ready in one call. [Details](https://docs.mobilerun.ai/sdk/helpers.md#create-and-wait-until-ready)
* Stop and resume devices. [Details](https://docs.mobilerun.ai/sdk/helpers.md#stop-and-resume)
* Tap, type, swipe and open apps. [Details](https://docs.mobilerun.ai/sdk/helpers.md#actions)
* Take screenshots. [Details](https://docs.mobilerun.ai/sdk/helpers.md#screenshots)
* Record the screen. [Details](https://docs.mobilerun.ai/sdk/helpers.md#recordings)
* Run agent tasks and wait for the result. [Details](https://docs.mobilerun.ai/sdk/helpers.md#wait-for-a-task)
* Get typed results. [Details](https://docs.mobilerun.ai/sdk/helpers.md#typed-output)
* Upload apps and files. [Details](https://docs.mobilerun.ai/sdk/helpers.md#upload-an-app)
* Verify webhook signatures. [Details](https://docs.mobilerun.ai/sdk/helpers.md#webhooks)
* Stream a device into your web app. [Details](https://docs.mobilerun.ai/sdk/helpers.md#stream-an-android-or-ios-device)

## Official SDKs

> [card] [TypeScript](https://www.npmjs.com/package/@mobilerun/sdk)
>
> `npm install @mobilerun/sdk`
>
> [Source on GitHub](https://github.com/droidrun/mobilerun-sdk-typescript)

> [card] [Python](https://pypi.org/project/mobilerun-sdk/)
>
> `pip install mobilerun-sdk`
>
> [Source on GitHub](https://github.com/droidrun/mobilerun-sdk-python)

> [!TIP]
>
> Need the SDK in another language? Write to [contact@mobilerun.ai](mailto:contact@mobilerun.ai) — we'd love to help.

## Plug-and-play components

> [card] [React](https://www.npmjs.com/package/@mobilerun/react)
>
> `npm install @mobilerun/react`
>
> Stream and control a device in your React app with `<DeviceStream />`.

To show a device in your app, see [Stream a device in a web app](#stream-a-device-in-a-web-app) and the
[`@mobilerun/react` README](https://github.com/droidrun/mobilerun-react#readme).

## Devices

`devices.create` returns once the device is ready. Always pass `deviceType`, and set `billing` to
`'minute'` to pay with device minutes. The device uses [device minutes](https://docs.mobilerun.ai/credits.md#device-minutes) until
you stop or terminate it. Pass `{ waitReady: false }` (Python `wait_ready=False`) to return right away
and call `device.waitReady()` (Python `wait_ready()`) later.

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

const mobilerun = new MobilerunSDK();

const device = await mobilerun.devices.create({
  deviceType: 'android_cloud_phone',
  billing: 'minute',
});
```

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

mobilerun = MobilerunSDK()

device = mobilerun.devices.create(device_type="android_cloud_phone", billing="minute")
```

To work with a device you already have, load it with `get`, or use `fromId` (Python `from_id`). `fromId`
gives you an object without a network call. Every collection, such as `mobilerun.tasks`, has it.

```typescript TypeScript theme={null}
const loaded = await mobilerun.devices.get('DEVICE_ID'); // one request
console.log(loaded.name, loaded.state);

const ref = mobilerun.devices.fromId('DEVICE_ID'); // no request
await ref.home();

for await (const d of mobilerun.devices.list()) {
  console.log(d.id, d.name, d.state);
}
```

```python Python theme={null}
loaded = mobilerun.devices.get("DEVICE_ID")  # one request
print(loaded.name, loaded.state)

ref = mobilerun.devices.from_id("DEVICE_ID")  # no request
ref.home()

for d in mobilerun.devices.list():
    print(d.id, d.name, d.state)
```

`device.name` and `device.state` show the values from the last response. Call `device.refresh()` to
load fresh values.

Control the device with these methods:

```typescript TypeScript theme={null}
await device.home();
await device.openApp('com.android.settings');
await device.tap(540, 1200);
await device.type('hello');
await device.swipe(300, 800, 300, 200, 400); // last argument: duration in milliseconds
await device.back();
```

```python Python theme={null}
device.home()
device.open_app("com.android.settings")
device.tap(540, 1200)
device.type("hello")
device.swipe(300, 800, 300, 200, 400)  # last argument: duration in milliseconds
device.back()
```

`device.screenshot()` returns an object with `save()`. See [Screenshots](https://docs.mobilerun.ai/sdk/helpers.md#screenshots).

## Stop and resume

`device.stop()` returns once the device is stopped. A later `device.resume()` returns once it is
ready again. Both return the device. A stopped device keeps its data and apps and stops using device
minutes. Cloud iOS devices cannot be stopped yet; call `device.terminate()` instead. For the options and
errors, see [Stop and resume](https://docs.mobilerun.ai/sdk/helpers.md#stop-and-resume).

```typescript TypeScript theme={null}
await device.stop();
// later
await device.resume();
```

```python Python theme={null}
device.stop()
# later
device.resume()
```

## Tasks

`device.run()` returns a `Task`. `task.wait()` returns the final status and throws `WaitFailureError`
if the task failed or was cancelled.

```typescript TypeScript theme={null}
const task = await device.run({ task: 'Open Settings and tell me the Android version' });
const status = await task.wait();
console.log(status.message);
```

```python Python theme={null}
task = device.run(task="Open Settings and tell me the Android version")
status = task.wait()
print(status.message)
```

For typed results with Zod or Pydantic, see [Typed output](https://docs.mobilerun.ai/sdk/helpers.md#typed-output). For wait errors
and time limits, see [Wait for a task](https://docs.mobilerun.ai/sdk/helpers.md#wait-for-a-task).

## Automatic cleanup

`await using` (TypeScript 5.2+) and `with` (Python; `async with await` for the async client) terminate a
device from `devices.create` when the block ends; a recording from `device.recordings.start()` is
stopped at the same point. Devices you load with `get`, `fromId` or `list` are never terminated for you.

```typescript TypeScript theme={null}
await using device = await mobilerun.devices.create({
  deviceType: 'android_cloud_phone',
  billing: 'minute',
});
const task = await device.run({ task: 'Open Settings' });
await task.wait();
// the device is terminated here
```

```python Python theme={null}
with mobilerun.devices.create(device_type="android_cloud_phone", billing="minute") as device:
    task = device.run(task="Open Settings")
    task.wait()
# the device is terminated here
```

If a device does not become ready during `create`, it is terminated and the call throws
`ObjectReadyError`. Pass `disposeOnReadyFailure: false` (Python `dispose_on_ready_failure=False`) to keep
it. For recordings, see [Recordings](https://docs.mobilerun.ai/sdk/helpers.md#recordings).

## Async Python

The async client has the same methods with `await`.

```python Python theme={null}
import asyncio
from mobilerun_sdk import AsyncMobilerunSDK


async def main() -> None:
    mobilerun = AsyncMobilerunSDK()
    async with await mobilerun.devices.create(device_type="android_cloud_phone", billing="minute") as device:
        task = await device.run(task="Open Settings")
        await task.wait()


asyncio.run(main())
```

## Stream a device in a web app

Get the stream details on your server and send only those to the browser. Never send your API key
to the browser. `device.info` holds the device record from the last response.

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

const mobilerun = new MobilerunSDK();

export async function getStream(deviceId: string) {
  const { info } = await mobilerun.devices.get(deviceId);
  return info ? { streamUrl: info.streamUrl, streamToken: info.streamToken } : null;
}
```

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

mobilerun = MobilerunSDK()


def get_stream(device_id: str):
    info = mobilerun.devices.get(device_id).info
    return {"streamUrl": info.stream_url, "streamToken": info.stream_token} if info else None
```

In your React app, install `@mobilerun/react` and render the stream.

```tsx theme={null}
import { DeviceStream } from '@mobilerun/react';

export function StreamView({ streamUrl, streamToken }: { streamUrl: string; streamToken?: string }) {
  return <DeviceStream streamUrl={streamUrl} streamToken={streamToken} hasControl />;
}
```

## All objects

These calls cost money: `numbers.create` rents a number and `connect.proxies.buy` buys a proxy.
`devices.create` uses device minutes.

| Object | Collection | Main methods |
| - | - | - |
| `Device` | `devices` | `get`, `list`, `create`, `run`, `screenshot`, `recordings` |
| `Recording` | `device.recordings` | `get`, `list`, `start`, `stop`, `delete`, `trajectory`, `video`, `screenshots` |
| `SavedScreenshot` | `device.screenshots` | `list`, `image`, `delete` |
| `TrafficSession` | `device.trafficSessions` | `create`, `get`, `list`, `delete` |
| `Task` | `tasks`, `device.run()` | `run`, `get`, `list`, `wait`, `waitOutput` |
| `App` | `apps` | `get`, `list`, `delete`, `listVersions` |
| `AgentFile` | `files`, `agent.files.list()` | `list`, `update`, `delete`, `confirm`, `cancelPending`, `download` |
| `Agent` | `agents` | `create`, `list`, `profile.update`, `files.list`, `conversations`, `routines` |
| `AgentRequest` | `agents.requests` | `get`, `list`, `retrieveBySession` |
| `Trigger` | `workflows.triggers` | `get`, `list`, `create`, `update`, `delete`, `fire` |
| `WorkflowAction` | `workflows.actions` | `get`, `list`, `create`, `update`, `delete` |
| `CatalogEntry` | `workflows.actionCatalog` | `get`, `list` |
| `Flow` | `workflows.flows` | `get`, `list`, `create`, `clone`, `run`, `verify` |
| `Execution` | `workflows.executions` | `get`, `list` |
| `ConnectUser` | `connect.users` | `get`, `list`, `create`, `update`, `delete`, `listConnections` |
| `ConnectProxy` | `connect.proxies` | `get`, `list`, `buy`, `update`, `ping`, `ensureHealthy`, `checkout`, `cancel` |
| `CredentialPackage` | `credentials.packages` | `get`, `list`, `create`, `credentials` |
| `Credential` | `package.credentials` | `create`, `list`, `delete`, `fields` |
| `PhoneNumber` | `numbers` | `get`, `list`, `create`, `send`, `waitUntilActive` |
| `NumberMessage` | `messages` | `get`, `list` |
| `Mailbox` | `mailboxes` | `get`, `list`, `create`, `waitForOtp`, `messages` |
| `MailboxMessage` | `mailbox.messages` | `get`, `list` |
| `MailboxConnection` | `mailboxes.connections` | `create`, `get` |
| `Webhook` | `webhooks` | `get`, `list`, `create`, `update`, `delete`, `test`, `rotateSecret` |
| `WebhookDelivery` | `webhook.deliveries` | `get`, `list` |
| `ProxyConfiguration` | `proxies` | `get`, `list`, `create`, `update`, `delete` |

`ProxyConfiguration` is a proxy setup you bring yourself. `ConnectProxy` is a proxy you buy from
Mobilerun. Method names are `snake_case` in Python, for example `wait_output` and `wait_until_active`.

## Coming from the `Mobilerun` client

Your existing `Mobilerun` code keeps working. `MobilerunSDK` adds objects on top, and the `Mobilerun`
client stays available as `mobilerun.api`.

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

const client = new Mobilerun();
const task = await client.tasks.run({ deviceId: 'DEVICE_ID', task: 'Open Settings' });

let status = await client.tasks.getStatus(task.id);
while (!['completed', 'failed', 'cancelled'].includes(status.status)) {
  await new Promise((r) => setTimeout(r, 3000));
  status = await client.tasks.getStatus(task.id);
}
```

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

const mobilerun = new MobilerunSDK();
const task = await mobilerun.devices.fromId('DEVICE_ID').run({ task: 'Open Settings' });
const status = await task.wait();
```

```python Python before theme={null}
import time

from mobilerun_sdk import Mobilerun

client = Mobilerun()
task = client.tasks.run(device_id="DEVICE_ID", task="Open Settings")

status = client.tasks.get_status(task.id)
while status.status not in ("completed", "failed", "cancelled"):
    time.sleep(3)
    status = client.tasks.get_status(task.id)
```

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

mobilerun = MobilerunSDK()
task = mobilerun.devices.from_id("DEVICE_ID").run(task="Open Settings")
status = task.wait()
```

## Use the `Mobilerun` client with `.api`

`mobilerun.api` is the `Mobilerun` client. Use it for anything the objects do not cover, such as
streaming task events.

## Next steps

> [card] [Cloud Quickstart](https://docs.mobilerun.ai/cloud/quickstart.md)
>
> Run your first task end to end.

> [card] [SDK helpers](https://docs.mobilerun.ai/sdk/helpers.md)
>
> Waiting, typed output, downloads, uploads, webhook checks and cleanup.

> [card] [Agent configuration](https://docs.mobilerun.ai/agent.md)
>
> All task parameters, including models, vision, reasoning, and structured output.


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