Skip to main content
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
  • Stop and resume devices. Details
  • Tap, type, swipe and open apps. Details
  • Take screenshots. Details
  • Record the screen. Details
  • Run agent tasks and wait for the result. Details
  • Get typed results. Details
  • Upload apps and files. Details
  • Verify webhook signatures. Details
  • Stream a device into your web app. Details

Official SDKs

TypeScript

npm install @mobilerun/sdkSource on GitHub

Python

pip install mobilerun-sdkSource on GitHub
Need the SDK in another language? Write to contact@mobilerun.ai — we’d love to help.

Plug-and-play components

React

npm install @mobilerun/reactStream 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 and the @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 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.
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.
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:
device.screenshot() returns an object with save(). See 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.

Tasks

device.run() returns a Task. task.wait() returns the final status and throws WaitFailureError if the task failed or was cancelled.
For typed results with Zod or Pydantic, see Typed output. For wait errors and time limits, see 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.
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.

Async Python

The async client has the same methods with await.
Python

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.
In your React app, install @mobilerun/react and render the stream.

All objects

These calls cost money: numbers.create rents a number and connect.proxies.buy buys a proxy. devices.create uses device minutes. 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.

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

Cloud Quickstart

Run your first task end to end.

SDK helpers

Waiting, typed output, downloads, uploads, webhook checks and cleanup.

Agent configuration

All task parameters, including models, vision, reasoning, and structured output.