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

# Drive the device step by step

> Inspect the screen and choose each device action in your own code.

Read the screen and control a device from your own code. The screen needs a moment after opening an app or tapping; these examples retry UI reads because the SDK has no element-wait helper yet.

> [accordion] Setup (once)
>
> ```bash Python theme={null}
> pip install mobilerun-sdk
> export MOBILERUN_API_KEY=dr_sk_...   # API Keys page
> export DEVICE_ID=...                 # a ready device from the dashboard
> python example.py
> ```
>
> ```bash TypeScript theme={null}
> npm init -y && npm pkg set type=module
> npm install @mobilerun/sdk && npm install -D tsx
> export MOBILERUN_API_KEY=dr_sk_...   # API Keys page
> export DEVICE_ID=...                 # a ready device from the dashboard
> npx tsx example.ts
> ```

## Read the screen

Read the filtered UI tree and capture a screenshot.

**Needs:** Cloud Android · API key and `DEVICE_ID` · no app or device account · device minutes, no task credits or add-ons · one-shot, under 1 min.

> Use `get_device_ui_state` to read the filtered UI state and `get_device_screenshot` to capture the screen. List the foreground app and each clickable element with its text and bounds.

> [accordion] Show the code (Python and TypeScript)
>
> ```python Python theme={null}
> import os
> from mobilerun_sdk import MobilerunSDK
>
> mobilerun = MobilerunSDK()
> device = mobilerun.devices.from_id(os.environ["DEVICE_ID"])
> state = device.ui(filter=True)
> print("Foreground:", state.phone_state.current_app or state.phone_state.package_name)
>
>
> def show(node):
>     if node.is_clickable:
>         print(node.text or node.content_description, node.bounds_in_screen)
>     for child in node.children or []:
>         show(child)
>
>
> show(state.a11y_tree)
> device.screenshot().save("screen.png")
> print("Screenshot: screen.png")
> ```
>
> ```typescript TypeScript theme={null}
> import { MobilerunSDK } from '@mobilerun/sdk';
> import type { A11YNode } from '@mobilerun/sdk/resources/devices/state';
>
> const mobilerun = new MobilerunSDK();
> const device = mobilerun.devices.fromId(process.env.DEVICE_ID!);
> const state = await device.ui({ filter: true });
> console.log('Foreground:', state.phone_state.currentApp || state.phone_state.packageName);
>
> function show(node: A11YNode): void {
>   if (node.isClickable) console.log(node.text || node.contentDescription, node.boundsInScreen);
>   for (const child of node.children || []) show(child);
> }
> show(state.a11y_tree);
> await (await device.screenshot()).save('screen.png');
> console.log('Screenshot: screen.png');
> ```

![Android launcher](https://docs.mobilerun.ai/images/examples/drive-the-phone/launcher.png)

Result

```text theme={null}
Foreground: com.android.mxLauncher3
Settings { left: 36, top: 2076, right: 288, bottom: 2312 }
Screenshot: screen.png
```

## Tap and type an alarm

Start Clock, create and verify a 07:00 alarm, then delete it.

**Needs:** Cloud Android · standard Clock app · no device account · API key and `DEVICE_ID` · device minutes, no task credits or add-ons · one-shot, \~1 min · dedicated test device without 07:00 or earlier alarms; remove the test alarm if interrupted.

> [accordion] Show the code (Python and TypeScript)
>
> ```python Python theme={null}
> import os
> import time
> from mobilerun_sdk import MobilerunSDK
>
> mobilerun = MobilerunSDK()
> device = mobilerun.devices.from_id(os.environ["DEVICE_ID"])
>
>
> def nodes(node):
>     yield node
>     for child in node.children or []:
>         yield from nodes(child)
>
>
> def state():
>     return device.ui(filter=True).a11y_tree
>
>
> def find(needle):
>     deadline = time.monotonic() + 10
>     while True:
>         for node in nodes(state()):
>             b = node.bounds_in_screen
>             if needle in (node.text, node.content_description, node.resource_id) and b.right > b.left and b.bottom > b.top:
>                 return node
>         if time.monotonic() >= deadline:
>             raise RuntimeError(f"Not found: {needle}")
>         time.sleep(0.5)
>
>
> def tap(needle):
>     b = find(needle).bounds_in_screen
>     device.tap((b.left + b.right) // 2, (b.top + b.bottom) // 2)
>
>
> device.open_app("com.android.deskclock")
> tap("Alarm")
> b = state().bounds_in_screen
> device.swipe((b.left + b.right) // 2, b.top + (b.bottom - b.top) // 2, (b.left + b.right) // 2, b.top + (b.bottom - b.top) * 3 // 4, 400)
> if any(n.content_description in ("07:00 Alarm", "7:00 Alarm") for n in nodes(state())):
>     raise RuntimeError("Remove the existing 07:00 alarm before running")
> tap("Add alarm")
> tap("android:id/toggle_mode")
> tap("android:id/input_hour")
> device.type("07", clear=True, completion_mode="committed")
> tap("android:id/input_minute")
> device.type("00", clear=True, completion_mode="committed")
> tap("OK")
> # A fresh phone asks for notification permission shortly after the alarm is saved.
> deadline = time.monotonic() + 10
> while time.monotonic() < deadline:
>     if any(n.resource_id.endswith(":id/permission_allow_button") for n in nodes(state())):
>         tap("com.android.permissioncontroller:id/permission_allow_button")
>         break
>     time.sleep(0.5)
> root = state()
> alarm = next((n for n in nodes(root) if n.content_description in ("07:00 Alarm", "7:00 Alarm")), None)
> if not alarm or not any(n.resource_id.endswith(":id/onoff") and n.is_checked for n in nodes(alarm)):
>     raise RuntimeError("07:00 alarm is missing or off")
> print("07:00 alarm is on")
> device.screenshot().save("alarm.png")
> tap("Expand alarm")
> tap("Delete")
> print("Alarm deleted")
> ```
>
> ```typescript TypeScript theme={null}
> import { MobilerunSDK } from '@mobilerun/sdk';
> import type { A11YNode } from '@mobilerun/sdk/resources/devices/state';
>
> const mobilerun = new MobilerunSDK();
> const device = mobilerun.devices.fromId(process.env.DEVICE_ID!);
>
> function* nodes(node: A11YNode): Generator<A11YNode> {
>   yield node;
>   for (const child of node.children || []) yield* nodes(child);
> }
> async function state() { return (await device.ui({ filter: true })).a11y_tree; }
> async function find(needle: string) {
>   const deadline = performance.now() + 10_000;
>   while (true) {
>     for (const node of nodes(await state())) {
>       const b = node.boundsInScreen;
>       if ([node.text, node.contentDescription, node.resourceId].includes(needle) && b.right > b.left && b.bottom > b.top) return node;
>     }
>     if (performance.now() >= deadline) throw new Error(`Not found: ${needle}`);
>     await new Promise(resolve => setTimeout(resolve, 500));
>   }
> }
> async function tap(needle: string) {
>   const b = (await find(needle)).boundsInScreen;
>   await device.tap(Math.floor((b.left + b.right) / 2), Math.floor((b.top + b.bottom) / 2));
> }
>
> await device.openApp('com.android.deskclock');
> await tap('Alarm');
> const b = (await state()).boundsInScreen;
> await device.swipe(Math.floor((b.left + b.right) / 2), b.top + Math.floor((b.bottom - b.top) / 2), Math.floor((b.left + b.right) / 2), b.top + Math.floor((b.bottom - b.top) * 3 / 4), 400);
> if ([...nodes(await state())].some(n => ['07:00 Alarm', '7:00 Alarm'].includes(n.contentDescription))) throw new Error('Remove the existing 07:00 alarm before running');
> await tap('Add alarm');
> await tap('android:id/toggle_mode');
> await tap('android:id/input_hour');
> await device.type('07', { clear: true, completionMode: 'committed' });
> await tap('android:id/input_minute');
> await device.type('00', { clear: true, completionMode: 'committed' });
> await tap('OK');
> // A fresh phone asks for notification permission shortly after the alarm is saved.
> const deadline = performance.now() + 10_000;
> while (performance.now() < deadline) {
>   if ([...nodes(await state())].some(n => n.resourceId.endsWith(':id/permission_allow_button'))) {
>     await tap('com.android.permissioncontroller:id/permission_allow_button');
>     break;
>   }
>   await new Promise(resolve => setTimeout(resolve, 500));
> }
> const root = await state();
> const alarm = [...nodes(root)].find(n => ['07:00 Alarm', '7:00 Alarm'].includes(n.contentDescription));
> if (!alarm || ![...nodes(alarm)].some(n => n.resourceId.endsWith(':id/onoff') && n.isChecked)) throw new Error('07:00 alarm is missing or off');
> console.log('07:00 alarm is on');
> await (await device.screenshot()).save('alarm.png');
> await tap('Expand alarm');
> await tap('Delete');
> console.log('Alarm deleted');
> ```

![Clock with the 07:00 alarm switched on](https://docs.mobilerun.ai/images/examples/drive-the-phone/alarm.png)

Result

```text theme={null}
07:00 alarm is on
Alarm deleted
```

## Run your own loop

Run an observe–decide–act loop to enable Dark theme, verify it survives [stop and resume](https://docs.mobilerun.ai/sdk/helpers.md#stop-and-resume), and turn it off.

**Needs:** Cloud Android · Settings · no device account · API key and `DEVICE_ID` · device minutes, no task credits or add-ons · one-shot, up to 20 steps.

> [accordion] Show the code (Python and TypeScript)
>
> ```python Python theme={null}
> import os
> import time
> from mobilerun_sdk import MobilerunSDK
>
> mobilerun = MobilerunSDK()
> device = mobilerun.devices.from_id(os.environ["DEVICE_ID"])
>
>
> def nodes(node):
>     yield node
>     for child in node.children or []:
>         yield from nodes(child)
>
>
> def observe():
>     deadline = time.monotonic() + 10
>     while True:
>         tree = device.ui(filter=True).a11y_tree
>         if any((n.content_description == "Dark theme" and n.is_checkable)
>                or (n.text == "Display" and n.resource_id == "android:id/title")
>                or n.text == "Settings" for n in nodes(tree)):
>             return tree
>         if time.monotonic() >= deadline:
>             raise RuntimeError("Display or Dark theme not visible")
>         time.sleep(0.5)
>
>
> # To replace the rules with your own model (pseudocode, not executed):
> # def decide_with_model(tree, phase):
> #     prompt = {"goal": phase, "ui": tree}
> #     reply = your_llm.generate(prompt)
> #     return validate_action(reply)  # Allow only supported actions and bounds.
>
> def decide(tree, phase):
>     items = list(nodes(tree))
>     toggle = next((n for n in items if n.content_description == "Dark theme" and n.is_checkable), None)
>     if toggle:
>         if phase == "enable" and toggle.is_checked:
>             return "restart", None
>         if phase == "verify" and toggle.is_checked:
>             return "persisted", None
>         if phase == "verify":
>             raise RuntimeError("Dark theme did not persist")
>         if phase == "disable" and not toggle.is_checked:
>             return "done", None
>         return "tap", toggle
>     display = next((n for n in items if n.text == "Display" and n.resource_id == "android:id/title"), None)
>     if display:
>         return "tap", display
>     if any(n.text == "Settings" for n in items):
>         return "open settings", None
>     raise RuntimeError("Display or Dark theme not visible")
>
>
> device.open_app("com.android.settings")
> phase = "enable"
> for step in range(1, 21):
>     tree = observe()
>     action, target = decide(tree, phase)
>     print(f"Step {step}: {phase} → {action}", flush=True)
>     if action == "done":
>         print("Dark theme is off")
>         break
>     if action == "restart":
>         device.screenshot().save("dark-theme.png")
>         device.stop()  # waits until stopped
>         device.resume()  # waits until ready
>         device.open_app("com.android.settings")
>         phase = "verify"
>     elif action == "persisted":
>         print("Dark theme persisted after resume")
>         phase = "disable"
>     elif action == "open settings":
>         device.open_app("com.android.settings")
>     elif action == "tap" and target:
>         b = target.bounds_in_screen
>         device.tap((b.left + b.right) // 2, (b.top + b.bottom) // 2)
>     elif action == "type":
>         device.type("example", completion_mode="committed")
>     elif action == "swipe":
>         b = tree.bounds_in_screen
>         device.swipe((b.left + b.right) // 2, b.bottom * 3 // 4, (b.left + b.right) // 2, b.bottom // 4, 400)
>     elif action == "back":
>         device.back()
> else:
>     raise RuntimeError("Step limit reached")
> ```
>
> ```typescript TypeScript theme={null}
> import { MobilerunSDK } from '@mobilerun/sdk';
> import type { A11YNode } from '@mobilerun/sdk/resources/devices/state';
>
> const mobilerun = new MobilerunSDK();
> const device = mobilerun.devices.fromId(process.env.DEVICE_ID!);
>
> function* nodes(node: A11YNode): Generator<A11YNode> {
>   yield node;
>   for (const child of node.children || []) yield* nodes(child);
> }
> async function observe() {
>   const deadline = performance.now() + 10_000;
>   while (true) {
>     const tree = (await device.ui({ filter: true })).a11y_tree;
>     if ([...nodes(tree)].some(n => (n.contentDescription === 'Dark theme' && n.isCheckable)
>       || (n.text === 'Display' && n.resourceId === 'android:id/title')
>       || n.text === 'Settings')) return tree;
>     if (performance.now() >= deadline) throw new Error('Display or Dark theme not visible');
>     await new Promise(resolve => setTimeout(resolve, 500));
>   }
> }
> // To replace the rules with your own model (pseudocode, not executed):
> // async function decideWithModel(tree, phase) {
> //   const prompt = { goal: phase, ui: tree };
> //   const reply = await yourLlm.generate(prompt);
> //   return validateAction(reply); // Allow only supported actions and bounds.
> // }
> function decide(tree: A11YNode, phase: string): [string, A11YNode | undefined] {
>   const items = [...nodes(tree)];
>   const toggle = items.find(n => n.contentDescription === 'Dark theme' && n.isCheckable);
>   if (toggle) {
>     if (phase === 'enable' && toggle.isChecked) return ['restart', undefined];
>     if (phase === 'verify' && toggle.isChecked) return ['persisted', undefined];
>     if (phase === 'verify') throw new Error('Dark theme did not persist');
>     if (phase === 'disable' && !toggle.isChecked) return ['done', undefined];
>     return ['tap', toggle];
>   }
>   const display = items.find(n => n.text === 'Display' && n.resourceId === 'android:id/title');
>   if (display) return ['tap', display];
>   if (items.some(n => n.text === 'Settings')) return ['open settings', undefined];
>   throw new Error('Display or Dark theme not visible');
> }
>
> await device.openApp('com.android.settings');
> let phase = 'enable';
> for (let step = 1; step <= 20; step++) {
>   const tree = await observe();
>   const [action, target] = decide(tree, phase);
>   console.log(`Step ${step}: ${phase} → ${action}`);
>   if (action === 'done') { console.log('Dark theme is off'); process.exit(0); }
>   if (action === 'restart') {
>     await (await device.screenshot()).save('dark-theme.png');
>     await device.stop(); // waits until stopped
>     await device.resume(); // waits until ready
>     await device.openApp('com.android.settings');
>     phase = 'verify';
>   } else if (action === 'persisted') {
>     console.log('Dark theme persisted after resume');
>     phase = 'disable';
>   } else if (action === 'open settings') {
>     await device.openApp('com.android.settings');
>   } else if (action === 'tap' && target) {
>     const b = target.boundsInScreen;
>     await device.tap(Math.floor((b.left + b.right) / 2), Math.floor((b.top + b.bottom) / 2));
>   } else if (action === 'type') {
>     await device.type('example', { completionMode: 'committed' });
>   } else if (action === 'swipe') {
>     const b = tree.boundsInScreen;
>     await device.swipe(Math.floor((b.left + b.right) / 2), Math.floor(b.bottom * 3 / 4), Math.floor((b.left + b.right) / 2), Math.floor(b.bottom / 4), 400);
>   } else if (action === 'back') {
>     await device.back();
>   }
> }
> throw new Error('Step limit reached');
> ```

![Display settings showing Dark theme enabled](https://docs.mobilerun.ai/images/examples/drive-the-phone/dark-theme.png)

Result

```text theme={null}
Dark theme persisted after resume
Dark theme is off
```

## Run it on many devices

> [!TIP]
>
> This runs on as many devices as you need: each device is read in parallel.

Read each device's filtered UI tree and save its screenshot in parallel.

**Needs:** 2+ ready devices · `DEVICE_IDS` or all ready devices · one-shot

> [accordion] Show the code (Python and TypeScript)
>
> ```python Python theme={null}
> import asyncio
> import os
> from pathlib import Path
> from mobilerun_sdk import AsyncMobilerunSDK, AsyncDevice
>
> mobilerun = AsyncMobilerunSDK()
>
>
> def show(node, lines):
>     if node.is_clickable:
>         lines.append(f"{node.text or node.content_description} {node.bounds_in_screen}")
>     for child in node.children or []:
>         show(child, lines)
>
>
> async def read_screen(device: AsyncDevice) -> tuple[str, str, bool]:
>     name = device.name or device.id
>     try:
>         if device.state != "ready":
>             raise RuntimeError("Device is not ready")
>         state = await device.ui(filter=True)
>         lines = [f"Foreground: {state.phone_state.current_app or state.phone_state.package_name}"]
>         show(state.a11y_tree, lines)
>         Path(f"{device.id}.txt").write_text("\n".join(lines) + "\n")
>         (await device.screenshot()).save(f"{device.id}.png")
>         return name, f"{len(lines) - 1} clickable elements; screenshot saved", False
>     except Exception as error:
>         return name, f"ERROR: {error}", True
>
>
> async def main() -> None:
>     ids = [i.strip() for i in os.getenv("DEVICE_IDS", "").split(",") if i.strip()]
>     if ids:
>         devices = [await mobilerun.devices.get(i) for i in ids]
>     else:
>         devices = [d async for d in mobilerun.devices.list(state=["ready"], platform="android")]
>     if not devices:
>         raise SystemExit("No ready devices found")
>     rows = await asyncio.gather(*(read_screen(d) for d in devices))
>     print("Device | Result")
>     for name, result, _ in rows:
>         print(f"{name} | {result}")
>     if any(failed for _, _, failed in rows):
>         raise SystemExit(1)
>
>
> asyncio.run(main())
> ```
>
> ```typescript TypeScript theme={null}
> import { writeFile } from 'node:fs/promises';
> import { MobilerunSDK, type Device } from '@mobilerun/sdk';
> import type { A11YNode } from '@mobilerun/sdk/resources/devices/state';
>
> const mobilerun = new MobilerunSDK();
> const ids = (process.env.DEVICE_IDS ?? '').split(',').map(id => id.trim()).filter(Boolean);
> const devices: Device[] = [];
> if (ids.length) {
>   for (const id of ids) devices.push(await mobilerun.devices.get(id));
> } else {
>   for await (const device of mobilerun.devices.list({ state: ['ready'], platform: 'android' })) devices.push(device);
> }
> if (!devices.length) throw new Error('No ready devices found');
>
> function show(node: A11YNode, lines: string[]): void {
>   if (node.isClickable) lines.push(`${node.text || node.contentDescription} ${JSON.stringify(node.boundsInScreen)}`);
>   for (const child of node.children || []) show(child, lines);
> }
>
> const rows = await Promise.all(devices.map(async (device) => {
>   const name = device.name ?? device.id;
>   try {
>     if (device.state !== 'ready') throw new Error('Device is not ready');
>     const state = await device.ui({ filter: true });
>     const lines = [`Foreground: ${state.phone_state.currentApp || state.phone_state.packageName}`];
>     show(state.a11y_tree, lines);
>     await writeFile(`${device.id}.txt`, lines.join('\n') + '\n');
>     await (await device.screenshot()).save(`${device.id}.png`);
>     return { name, result: `${lines.length - 1} clickable elements; screenshot saved`, failed: false };
>   } catch (error) {
>     return { name, result: `ERROR: ${error instanceof Error ? error.message : String(error)}`, failed: true };
>   }
> }));
> console.log('Device | Result');
> for (const row of rows) console.log(`${row.name} | ${row.result}`);
> if (rows.some(row => row.failed)) process.exitCode = 1;
> ```

![Android launcher from Docs scale J](https://docs.mobilerun.ai/images/examples/drive-the-phone/many-phones.png)

Result

```text theme={null}
Device | Result
Docs scale J | 6 clickable elements; screenshot saved
Docs test A | 13 clickable elements; screenshot saved
```

## Next steps

Explore [device controls](https://docs.mobilerun.ai/devices.md) to build your own actions.

> [accordion] For AI agents
>
> Start with the first example on a ready device the user names. Uses device UI state, screenshots, app launch, tap, swipe, and keyboard calls. Ask before changing device settings or creating an alarm; never purchase anything or use real accounts. Report the result and any failed step.


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