Skip to main content
Each helper replaces code you would otherwise write yourself, such as polling loops or signature checks.
Needs SDK 6.2.0 or later. Start with the Mobilerun SDK guide.

Devices

Create and wait until ready

Replaces creating a device and polling until it is ready. Creating a device uses device minutes until you stop or terminate it. params must include deviceType.
If the device does not become ready, create throws ObjectReadyError.

Stop and resume

A stopped device keeps its data and apps and stops using device minutes. Cloud iOS devices cannot be stopped yet; call device.terminate() instead.
stop throws WaitFailureError or WaitTimeoutError. resume throws ObjectReadyError. The device is not terminated when they happen.

Actions

The device ID is already known to the object.
duration is in milliseconds. ui() returns the current accessibility tree of the screen.

Screenshots

device.screenshot() returns a result with bytes, save(), base64() and dataUrl() (Python data_url()). TypeScript also has blob().

Stream an Android or iOS device

Show a live device in your web app with <DeviceStream /> from @mobilerun/react. Never send your API key to the browser. The Mobilerun SDK guide shows the server and React parts.

Tasks

Wait for a task

Replaces a status polling loop with setTimeout or time.sleep. task.wait() returns the final status once the task completed.
All wait errors extend WaitError.

Typed output

Pass an output schema to device.run() and call waitOutput() (Python wait_output()) to get the result as typed data. TypeScript uses Zod 4 through output() from @mobilerun/sdk/zod. Python uses a Pydantic model.
result.response is the raw status response. Options are the same as for wait(). It throws OutputValidationError when the output does not match your schema, plus the errors of wait().

Recordings and files

Recordings

recording.wait() returns once the video is uploaded. Then video() and trajectory() return the files as bytes.
Options and errors are the same as for task.wait().

Saved screenshots

Save a screenshot with device.screenshot({ save: true }) (Python save=True). savedScreenshot.image() returns the PNG as bytes. device.screenshots.list() returns one page; read its saved screenshots from .items.

Agent files

agentFile.download() returns the file as bytes.

Uploads

Upload an app

Uploads the files and returns an App. A string is a local file path, and the file streams from disk. Uploads use storage quota and may incur storage charges.

Upload a file

Uploads the file and returns an AgentFile. A string is a local file path.

Webhooks

Replaces writing the signature check yourself. verifyWebhook (Python verify_webhook) is a standalone import and needs no API key. Pass the raw request body, exactly as received. If a framework parses the JSON first, the signature no longer matches. The check also rejects requests that are too old or too far in the future, so replays fail. Deduplicate replays with an ID inside the signed body, not the unsigned X-Mobilerun-Event-Id header.
If it throws WebhookVerificationError (wrong signature or too old), respond with 400. See Webhooks for events and secrets.

Common to all objects

  • Pagination. Lists are iterated directly: for await (const device of mobilerun.devices.list()) in TypeScript, for device in mobilerun.devices.list() in Python. Next pages load as needed.
  • fromId(). mobilerun.devices.fromId(id) (Python from_id) gives you an object without a network call. Every collection, such as mobilerun.tasks, has it.
  • Automatic cleanup. await using (TypeScript 5.2 or later) and with (Python) terminate a device from devices.create() when the block ends. Devices from get, fromId or a list are never cleaned up for you.
  • Safe logging. Objects never print the API key. console.log(device) and print(device) are safe.

Mobilerun SDK

Create devices, run tasks, stream, and the list of all objects.

Cloud Quickstart

Run your first task end to end.