droidrun/mobilerun
AI EngineeringAn LLM-agnostic framework that lets AI agents inspect, tap, swipe, and type on real Android and iOS devices via CLI or Python.
What it does
Mobilerun is an open-source framework for mobile app testing, QA, and running AI agents on real Android and iOS devices. It exposes mobile-native tools to an LLM: reading the accessibility (UI) tree, interpreting screenshots, tapping, swiping, typing, launching apps, and planning multi-step workflows. Results come back through a CLI or a Python API.
The framework is model-agnostic and accepts OpenAI, Anthropic, Gemini, xAI, Ollama, DeepSeek, OpenRouter, and OpenAI-compatible endpoints. A reasoning mode switches to manager-executor planning for longer tasks, and a vision mode sends screenshots alongside the accessibility tree for apps that expose little UI metadata.
Quickstart
Prerequisites: Python >=3.11,<3.14, uv, and for Android an ADB-enabled device with Developer options and USB debugging turned on. iOS setup differs (USB through mobilerun-ios, or the iOS Portal for the Simulator) — see the device setup guide.
Install and run from the CLI:
uv tool install mobilerun
mobilerun setup # installs the Portal app and enables its accessibility service
mobilerun ping # verifies the device connection
mobilerun configure # picks LLM provider, auth method, and model
mobilerun run "Open the settings app and tell me the Android version"
For Anthropic, install the optional extra: uv tool install "mobilerun[anthropic]". Instead of the configure wizard you can set provider keys as environment variables such as GOOGLE_API_KEY, OPENAI_API_KEY, or ANTHROPIC_API_KEY.
Useful run flags: --vision (send screenshots), --vision-only (screenshot-only control), --reasoning (planner-executor), --ios, and --steps N --debug. To build custom workflows, install with uv pip install mobilerun and use the Python API; the SDK reference and custom tools guide cover extension points.
Constraints and scope
- Python 3.14 is not supported yet.
- Android control relies on the Mobilerun Portal app and its accessibility service; iOS control needs the separate
mobilerun-ioscomponent or the iOS Portal app. - An LLM provider account and credentials are required; the agent's behavior depends on the chosen model.
- The framework runs on your own machine. Managed phones, fleet workflows, and REST/SDK access are a separate cloud product; the README distinguishes local framework use from that hosted offering.
- Tracing can be wired to Arize Phoenix or Langfuse for debugging saved trajectories.
- Licensed under MIT.
HotRepo's take
No HotRepo ranking or growth history is recorded for this repository, so there is no trend to cite from the site. What the material does support is a concrete, installable framework: a real install path, layered device support (ADB, Portal, iOS, Simulator), multiple model backends, and documented extension points for custom tools and structured output. It sits at the intersection of LLM-agent tooling and mobile QA, and the README's own benchmark claim (91.4%) comes from the project's site, so treat it as a self-reported figure rather than an independent measurement.
Written by AI from the project's README, updated . The project's own docs are the source of truth.
You might also like
- phone-harness/mcpA hosted MCP server that lets AI agents control real iPhones and Android emulators in the cloud.
- KnifeLemon/DroidlineAutomate and test real Android phones from Python, Node.js, C#, CLI, HTTP or Appium without ADB, USB or root.
- ZSeven-W/dsh-androidDeepSeek Harness plugin that streams a live Android emulator or USB device into the conversation and drives it through adb.
- mylea1/phongentControls multiple Android device agents from an iOS or Android master device with natural-language tasks and live screens.
- mobile-next/mobile-mcpAn MCP server that lets AI agents inspect and control iOS and Android apps on simulators, emulators and real devices.