Skip to content
Back to search

mobilerun-docs

Mobilerun documentation reference. Use when users ask about Mobilerun setup, configuration, SDK usage, CLI commands, device setup, agents, architecture, app cards, credentials, tracing, Docker, migration, structured output, or any Mobilerun "how do I..." questions.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/droidrun/mobilerun with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/droidrun/mobilerun'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/droidrun--mobilerun/badge.svg)](/listings/droidrun--mobilerun)

HTML

<a href="/listings/droidrun--mobilerun"><img src="/api/listings/droidrun--mobilerun/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

> **Note:** Python 3.14 is not currently supported. Please use Python `>=3.11,<3.14`.

Install Mobilerun with [`uv`](https://docs.astral.sh/uv/):

# CLI usage
uv tool install mobilerun
# CLI + Python integration
uv pip install mobilerun

Most LLM providers are included by default. For Anthropic support, install the optional extra:

uv tool install "mobilerun[anthropic]"

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 84 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: mobilerun-docs
  3. description: Mobilerun documentation reference. Use when users ask about Mobilerun setup, configuration, SDK usage, CLI commands, device setup, agents, architecture, app cards, credentials, tracing, Docker, migration, structured output, or any Mobilerun "how do I..." questions.
  4. ---
  5. # Mobilerun
  6. Mobilerun is an open-source (MIT) framework for controlling Android and iOS devices through LLM agents.
  7. It enables mobile automation using natural language commands.
  8. - **GitHub**: https://github.com/droidrun/mobilerun
  9. - **Docs site**: https://docs.mobilerun.ai
  10. - **License**: MIT
  11. - **Install**: `uv tool install mobilerun` (Google Gemini, OpenAI, DeepSeek, Ollama, OpenRouter included by default)
  12. - **Optional extras**: `anthropic`, `langfuse`
  13. - **Requires**: Python 3.11+, ADB, Portal APK on device
  14. ## Architecture
  15. Mobilerun uses a multi-agent architecture coordinated by `MobileAgent`:
  16. - **Reasoning mode** (`reasoning=True`): Manager plans → Executor acts → loop until done
  17. - **Direct mode** (`reasoning=False`): CodeActAgent generates and executes Python code directly
  18. Key agents: ManagerAgent (planning), ExecutorAgent (actions), CodeActAgent (direct execution),
  19. ScripterAgent (off-device computation), StructuredOutputAgent (typed data extraction).
  20. Atomic actions available to agents: `click`, `long_press`, `type`, `system_button`, `swipe`,
  21. `open_app`, `get_state`, `take_screenshot`, `complete`.
  22. ## Repository Structure
  23. Source code is at `mobilerun/` (Python package). Key locations:
  24. | Path | Description |
  25. |------|-------------|
  26. | `mobilerun/agent/droid/` | MobileAgent orchestrator |
  27. | `mobilerun/agent/codeact/` | CodeActAgent (direct mode) |
  28. | `mobilerun/agent/scripter/` | ScripterAgent (off-device scripts) |
  29. | `mobilerun/agent/oneflows/` | StructuredOutputAgent |
  30. | `mobilerun/agent/utils/` | Tools, executor, tracing, async utils |
  31. | `mobilerun/tools/` | Device tools (ADB, iOS, portal client) |
  32. | `mobilerun/cli/` | CLI entry point (click-based) |
  33. | `mobilerun/config/prompts/` | Jinja2 prompt templates per agent |
  34. | `mobilerun/config/app_cards/` | App-specific instruction cards |
  35. | `mobilerun/credential_manager/` | YAML-based credential storage |
  36. | `mobilerun/telemetry/` | Phoenix tracing integration |
  37. ## Documentation
  38. Fetch the relevant page(s) from the docs site based on the user's question. Do not guess — always
  39. read the doc before answering.
  40. | Topic | Page |
  41. |-------|------|
  42. | Overview | https://docs.mobilerun.ai/framework/overview.md |
  43. | Quickstart | https://docs.mobilerun.ai/framework/quickstart.md |
  44. | **Concepts** | |
  45. | Architecture & agents | https://docs.mobilerun.ai/framework/concepts/architecture.md |
  46. | Events & workflows | https://docs.mobilerun.ai/framework/concepts/events-and-workflows.md |
  47. | Prompts | https://docs.mobilerun.ai/framework/concepts/prompts.md |
  48. | Shared state | https://docs.mobilerun.ai/framework/concepts/shared-state.md |
  49. | **Features** | |
  50. | App cards | https://docs.mobilerun.ai/framework/features/app-cards.md |
  51. | Credentials | https://docs.mobilerun.ai/framework/features/credentials.md |
  52. | Custom tools | https://docs.mobilerun.ai/framework/features/custom-tools.md |
  53. | Custom variables | https://docs.mobilerun.ai/framework/features/custom-variables.md |
  54. | Structured output | https://docs.mobilerun.ai/framework/features/structured-output.md |
  55. | Telemetry | https://docs.mobilerun.ai/framework/features/telemetry.md |
  56. | Tracing | https://docs.mobilerun.ai/framework/features/tracing.md |
  57. | Vision | https://docs.mobilerun.ai/framework/features/vision.md |
  58. | **Guides** | |
  59. | CLI usage | https://docs.mobilerun.ai/framework/guides/cli.md |
  60. | Device setup | https://docs.mobilerun.ai/framework/guides/device-setup.md |
  61. | Docker | https://docs.mobilerun.ai/framework/guides/docker.md |
  62. | **SDK** | |
  63. | MobileAgent | https://docs.mobilerun.ai/framework/sdk/droid-agent.md |
  64. | ADB tools | https://docs.mobilerun.ai/framework/sdk/adb-tools.md |
  65. | iOS tools | https://docs.mobilerun.ai/framework/sdk/ios-tools.md |
  66. | Base tools | https://docs.mobilerun.ai/framework/sdk/base-tools.md |
  67. | Configuration | https://docs.mobilerun.ai/framework/sdk/configuration.md |
  68. | API reference | https://docs.mobilerun.ai/framework/sdk/reference.md |
  69. For deeper implementation details, check the source code directly in `mobilerun/`.
README.md · README · 270 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <picture align="center">
  2. <source media="(prefers-color-scheme: dark)" srcset="./static/mobilerun-dark.png">
  3. <source media="(prefers-color-scheme: light)" srcset="./static/mobilerun.png">
  4. <img src="./static/mobilerun.png" width="full">
  5. </picture>
  6. <p align="center">
  7. <strong>Mobilerun is an open-source framework for mobile app testing, QA, and running AI agents on real Android and iOS devices.</strong><br>
  8. It gives agents mobile-native tools to inspect UI state, understand screenshots, tap, swipe, type, plan multi-step workflows, and return results through a CLI or Python API.
  9. </p>
  10. <div align="center">
  11. <a href="https://docs.mobilerun.ai">📕 Documentation</a>
  12. ·
  13. <a href="https://cloud.mobilerun.ai">☁️ Mobilerun Cloud</a>
  14. ·
  15. <a href="https://github.com/droidrun/mobile-harness">🛡️ Mobile Harness</a>
  16. [![GitHub stars](https://img.shields.io/github/stars/droidrun/mobilerun?style=social)](https://github.com/droidrun/mobilerun/stargazers)
  17. [![mobilerun.ai](https://img.shields.io/badge/mobilerun.ai-white)](https://mobilerun.ai)
  18. [![Twitter Follow](https://img.shields.io/twitter/follow/mobilerun_ai?style=social)](https://x.com/mobilerun_ai)
  19. [![Discord](https://img.shields.io/discord/1360219330318696488?color=white&label=Discord&logo=discord&logoColor=white)](https://discord.gg/ZZbKEZZkwK)
  20. [![Telegram Support](https://img.shields.io/badge/Telegram-Support-26A5E4?logo=telegram&logoColor=white)](https://t.me/+_r43WkbbyiA1OGUy)
  21. [![Benchmark](https://img.shields.io/badge/Benchmark-91.4﹪-white)](https://mobilerun.ai/benchmark)
  22. <picture>
  23. <source media="(prefers-color-scheme: dark)" srcset="https://api.producthunt.com/widgets/embed-image/v1/top-post-badge.svg?post_id=983810&theme=dark&period=daily&t=1753948032207">
  24. <source media="(prefers-color-scheme: light)" srcset="https://api.producthunt.com/widgets/embed-image/v1/top-post-badge.svg?post_id=983810&theme=neutral&period=daily&t=1753948125523">
  25. <a href="https://www.producthunt.com/products/droidrun-framework-for-mobile-agent?embed=true&utm_source=badge-top-post-badge&utm_medium=badge&utm_source=badge-droidrun" target="_blank"><img src="https://api.producthunt.com/widgets/embed-image/v1/top-post-badge.svg?post_id=983810&theme=neutral&period=daily&t=1753948125523" alt="Droidrun - Give&#0032;AI&#0032;native&#0032;control&#0032;of&#0032;physical&#0032;&#0038;&#0032;virtual&#0032;phones&#0046; | Product Hunt" style="width: 200px; height: 54px;" width="200" height="54" /></a>
  26. </picture>
  27. [Deutsch](https://zdoc.app/de/droidrun/mobilerun) |
  28. [Español](https://zdoc.app/es/droidrun/mobilerun) |
  29. [français](https://zdoc.app/fr/droidrun/mobilerun) |
  30. [日本語](https://zdoc.app/ja/droidrun/mobilerun) |
  31. [한국어](https://zdoc.app/ko/droidrun/mobilerun) |
  32. [Português](https://zdoc.app/pt/droidrun/mobilerun) |
  33. [Русский](https://zdoc.app/ru/droidrun/mobilerun) |
  34. [中文](https://zdoc.app/zh/droidrun/mobilerun)
  35. </div>
  36. <p align="center">
  37. <img src="./static/mobilerun-demo.gif" alt="Mobilerun automating a phone with natural language" width="320">
  38. </p>
  39. - 🤖 Control Android and iOS devices with natural language commands
  40. - 🔀 Use OpenAI, Anthropic, Gemini, xAI, Ollama, DeepSeek, OpenRouter, and OpenAI-compatible models
  41. - 🧠 Run direct tasks or enable reasoning mode for complex multi-step automation
  42. - 💻 Automate from the CLI, a terminal UI, Docker, or Python code
  43. - 🐍 Extend agents with custom tools, structured output, app cards, and credentials
  44. - 📸 Combine accessibility trees with screenshots for visual understanding
  45. - 🫆 Trace execution with Arize Phoenix or Langfuse
  46. Use the framework when you want to run the agent on your machine. Use [Mobilerun Cloud](https://cloud.mobilerun.ai) when you want a ready-to-go solution for your local phones or cloud-hosted virtual/physical phones, managed infrastructure, and API-driven device workflows without running the agent on your local machine. [Check out our benchmark results](https://mobilerun.ai/benchmark).
  47. ## 🎯 Platform Support
  48. | Target | Supported | Setup |
  49. | --- | :---: | --- |
  50. | Android Real Device | ✅ | `adb` or the [Portal](https://github.com/droidrun/mobilerun-portal) app |
  51. | Android Emulator | ✅ | Running emulator (`adb`) |
  52. | iOS Real Device | ✅ | [`mobilerun-ios`](https://docs.mobilerun.ai/framework/guides/device-setup) over USB |
  53. | iOS Simulator | ✅ | [iOS Portal](https://github.com/droidrun/ios-portal) app |
  54. | Android on [Mobilerun Cloud](https://mobilerun.ai) | ✅ | Hosted phones or your own |
  55. | iOS on [Mobilerun Cloud](https://mobilerun.ai) | ✅ | Hosted iPhones or your own |
  56. ## 📦 Installation
  57. > **Note:** Python 3.14 is not currently supported. Please use Python `>=3.11,<3.14`.
  58. Install Mobilerun with [`uv`](https://docs.astral.sh/uv/):
  59. ```bash
  60. # CLI usage
  61. uv tool install mobilerun
  62. ```
  63. ```bash
  64. # CLI + Python integration
  65. uv pip install mobilerun
  66. ```
  67. Most LLM providers are included by default. For Anthropic support, install the optional extra:
  68. ```bash
  69. uv tool install "mobilerun[anthropic]"
  70. ```
  71. ## 🚀 Quickstart
  72. ```bash
  73. uv tool install mobilerun
  74. mobilerun setup
  75. mobilerun configure
  76. mobilerun run "Open settings and turn on dark mode"
  77. ```
  78. Before starting, make sure you have [ADB](https://developer.android.com/studio/releases/platform-tools) installed and an Android device with Developer options and USB debugging enabled. For iOS, set up [`mobilerun-ios`](https://docs.mobilerun.ai/framework/guides/device-setup) for an iPhone or the [iOS Portal](https://github.com/droidrun/ios-portal) app for the simulator.
  79. ### 1. Install the Portal on your device
  80. ```bash
  81. mobilerun setup
  82. ```
  83. This installs the Mobilerun Portal app, enables its accessibility service, and prepares the device for local control.
  84. ### 2. Verify the connection
  85. ```bash
  86. mobilerun ping
  87. ```
  88. You should see confirmation that the Portal is installed and accessible.
  89. ### 3. Configure your LLM provider
  90. ```bash
  91. mobilerun configure
  92. ```
  93. The wizard walks you through choosing a provider, auth method, and model. You can also use provider environment variables such as `GOOGLE_API_KEY`, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `XAI_API_KEY`, or `MINIMAX_API_KEY`.
  94. ### 4. Run your first command
  95. ```bash
  96. mobilerun run "Open the settings app and tell me the Android version"
  97. ```
  98. Useful run options:
  99. ```bash
  100. mobilerun run "Open settings and turn on dark mode"
  101. mobilerun run "What app is currently open?" --vision
  102. mobilerun run "Find a contact named John and send him an email" --reasoning
  103. mobilerun run "Take a screenshot" --ios
  104. mobilerun run "Open Settings" --steps 30 --debug
  105. ```
  106. Read the full [framework documentation](https://docs.mobilerun.ai/framework/quickstart).
  107. ## ⚙️ Features
  108. - **CLI:** Run one-off natural language tasks, inspect devices, replay macros, and debug from the terminal.
  109. - **Python API:** Build custom mobile automation workflows with Python and use custom tools.
  110. - **Android and iOS support:** Control Android through the Portal app, iPhones through `mobilerun-ios`, or the iOS Simulator through the iOS Portal app.
  111. - **Portal-based control:** Use UI trees, screenshots, text input, gestures, app launching, and device state from the Portal runtime.
  112. - **Vision mode:** Send screenshots to the LLM with `--vision`, or use screenshot-only control with `--vision-only` (useful for the apps that do not have a11y tree information).
  113. - **Reasoning mode:** Use `--reasoning` for manager-executor planning on longer or more complex tasks.
  114. - **Tracing and telemetry:** Debug execution with Arize Phoenix, Langfuse, saved trajectories, and detailed logs.
  115. - **Structured output:** Return structured data from mobile workflows.
  116. - **App cards and custom tools:** Add app-specific guidance to make agent perform better on your use-cases.
  117. - **Docker:** Run Mobilerun in a container for repeatable local environments.
  118. ## ☁️ Framework vs Cloud
  119. | | Mobilerun Framework | Mobilerun Cloud |
  120. | --- | --- | --- |
  121. | Best for | Running agents locally on your own machine and devices | Ready-to-go local phone control, hosted real or virtual devices, API workflows, and managed device operations |
  122. | Runtime | Your machine | Mobilerun-managed infrastructure |
  123. | Interface | CLI, Docker, and Python API | Dashboard, REST API, SDKs, and hosted devices |
  124. Use the framework when you want full local control of the agent runtime. Use [Mobilerun Cloud](https://cloud.mobilerun.ai) when you want managed devices, fleet workflows, or cloud APIs without running the agent locally. Learn more in the [framework overview](https://docs.mobilerun.ai/framework/overview) and the [cloud docs](https://docs.mobilerun.ai).
  125. ### Which should I choose?
  126. - Choose **Mobilerun Framework** for local agent execution and code-level control.
  127. - Choose **Mobilerun Cloud** for managed phones, APIs, and scale without running agents locally.
  128. ### Cloud Device Types
  129. | Device type | What it is | Best for |
  130. | --- | --- | --- |
  131. | Personal | Your own hardware connected to Mobilerun Cloud | Quick automation on devices you own |
  132. | Cloud Phone (Hosted) | Instantly available cloud-hosted phone | Scalable hosted automation |
  133. | Physical Phone (Hosted) | Real hardware, not emulated | QA and workflows that need real device behavior (sensors, camera, push, payments) |
  134. ### Run an agent on a Cloud Phone
  135. Ask an agent to test the onboarding flow in your app: open the app, complete the welcome screens, sign in with a test account, and confirm that the home screen loads. Watch each step live and inspect the results to diagnose failures.
  136. ### Generate leads with Google Maps on a Cloud Phone
  137. <a href="https://www.youtube.com/watch?v=CaL71WorysA">
  138. <img src="./static/google-maps.gif" alt="Mobilerun generating business leads with Google Maps on a cloud device" width="800">
  139. </a>
  140. ## 🧩 Agent Skill
  141. Give Claude Code, Codex, or another coding agent direct control of Android and iOS devices with the [mobile-harness](https://github.com/droidrun/mobile-harness) skill. Copy paste it into your agent:
  142. ```text
  143. Set up https://github.com/droidrun/mobile-harness for me.
  144. Read `install.md` and follow the steps to install `mobile-harness`.
  145. ```
  146. The skill teaches the agent to drive local devices (ADB, Portal, iPhones, iOS Simulator) and Mobilerun Cloud phones.
  147. ## 🎬 Demo Videos
  148. ### Book accommodation from a prompt
  149. Shows multi-step navigation, text input, and app-state reasoning while Mobilerun searches for accommodation.
  150. <a href="https://youtu.be/VUpCyq1PSXw">
  151. <img src="./static/demo-apartment-search.gif" alt="Mobilerun booking accommodation from a prompt" width="800">
  152. </a>
  153. ### Find trending content
  154. Shows browsing, app navigation, and result extraction from a natural-language task.
  155. <a href="https://youtu.be/7V8S2f8PnkQ">
  156. <img src="./static/demo-reddit-trends.gif" alt="Mobilerun finding trending content from a prompt" width="800">
  157. </a>
  158. ## 💡 Example Use Cases
  159. - Mobile app QA and regression testing
  160. - Guided workflows for non-technical users
  161. - Repetitive task automation on mobile devices
  162. - Event-driven automation from schedules, notifications, or custom triggers
  163. - Data extraction from native mobile apps
  164. - Testing the same flow across many devices and OS versions in parallel
  165. ## 🌐 Part of Mobilerun
  166. Mobilerun is one piece of a toolkit for driving real phones with AI agents:
  167. - **[Mobilerun Portal](https://github.com/droidrun/mobilerun-portal)**: the Android app that lets you control and automate your phone.
  168. - **[mobilerun-ios](https://github.com/droidrun/mobilerun-ios-releases)**: connects an iPhone over USB, either to this framework (`--local`) or to Mobilerun Cloud.
  169. - **[iOS Portal](https://github.com/droidrun/ios-portal)**: the iOS app that lets the framework drive the iOS Simulator.
  170. - **[mobile-harness](https://github.com/droidrun/mobile-harness)**: an agent skill that lets Claude Code, Codex, and OpenClaw control Android, iOS, and cloud phones. App cards teach the agent how each app works, and shared memory keeps what it learns across tasks. It scores 100% on AndroidWorld and 98.34% on iOSWorld ([benchmark results](https://mobilerun.ai/benchmark/)).
  171. - **[Mobilerun Cloud](https://mobilerun.ai)**: cloud phones for AI agents. Hosted Android phones and dedicated iPhones for testing and running your agents on real devices, with phone numbers and inboxes so end to end flows like sign in and verification work in your own apps, devices in multiple regions for localized testing, and scheduled and event triggers. Drive it through the REST API, [Python](https://github.com/droidrun/mobilerun-sdk-python) and [TypeScript](https://github.com/droidrun/mobilerun-sdk-typescript) SDKs, or MCP, and watch every step live.
  172. ## 📚 Documentation
  173. - [Framework quickstart](https://docs.mobilerun.ai/framework/quickstart)
  174. - [Mobilerun cloud quickstart](https://docs.mobilerun.ai/quickstart)
  175. - [Device setup](https://docs.mobilerun.ai/framework/guides/device-setup)
  176. - [CLI guide](https://docs.mobilerun.ai/framework/guides/cli)
  177. - [SDK reference](https://docs.mobilerun.ai/framework/sdk/reference)
  178. - [Custom tools](https://docs.mobilerun.ai/framework/features/custom-tools)
  179. - [Agent architecture](https://docs.mobilerun.ai/framework/concepts/architecture)
  180. - [Structured output](https://docs.mobilerun.ai/framework/features/structured-output)
  181. - [Tracing](https://docs.mobilerun.ai/framework/features/tracing)
  182. ## 👥 Contributing
  183. Contributions are welcome. Please feel free to submit a pull request or open an issue.
  184. ## 📄 License
  185. This project is licensed under the MIT License. See [LICENSE](./LICENSE) for details.
  186. ## Security Checks
  187. To help catch security issues before submitting changes, run:
  188. ```bash
  189. bandit -r mobilerun
  190. safety scan
  191. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.