io.github.droidrun/mobilerun
Control real Android and iOS devices with LLM agents — tap, swipe, type, automate flows.
Open source Repository Open in the app JSON README (API)
About
Control real Android and iOS devices with LLM agents — tap, swipe, type, automate flows.
Details
- Kind
- MCP servers
- Topic
- AI, RAG & memory
- Publisher
- droidrun
- Origin
- official
- Category
- ferramentas
- Transport
- http
- Version
- 1.0.0
- Stars
- 9,342
- Forks
- 999
- Open pull requests
- 12
- Last push
- 2026-09-10T18:08:49Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-29 03:02:43
- Updated
- 2026-08-29 03:02:43
- Origin id
io.github.droidrun/mobilerun
README
<picture align="center"> <source media="(prefers-color-scheme: dark)" srcset="./static/mobilerun-dark.png"> <source media="(prefers-color-scheme: light)" srcset="./static/mobilerun.png"> <img src="./static/mobilerun.png" width="full"> </picture> <p align="center"> <strong>Mobilerun is an open-source framework for controlling Android and iOS devices with LLM agents.</strong><br> 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. </p> <div align="center"> <a href="https://docs.mobilerun.ai">📕 Documentation</a> · <a href="https://cloud.mobilerun.ai">☁️ Mobilerun Cloud</a> · <a href="https://github.com/droidrun/mobile-harness">🛡️ Mobile Harness</a> [](https://github.com/droidrun/mobilerun/stargazers) [](https://mobilerun.ai) [](https://x.com/mobilerun_ai) [](https://discord.gg/ZZbKEZZkwK) [](https://t.me/+_r43WkbbyiA1OGUy) [](https://mobilerun.ai/benchmark) <picture> <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"> <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"> <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 AI native control of physical & virtual phones. | Product Hunt" style="width: 200px; height: 54px;" width="200" height="54" /></a> </picture> [Deutsch](https://zdoc.app/de/droidrun/mobilerun) | [Español](https://zdoc.app/es/droidrun/mobilerun) | [français](https://zdoc.app/fr/droidrun/mobilerun) | [日本語](https://zdoc.app/ja/droidrun/mobilerun) | [한국어](https://zdoc.app/ko/droidrun/mobilerun) | [Português](https://zdoc.app/pt/droidrun/mobilerun) | [Русский](https://zdoc.app/ru/droidrun/mobilerun) | [中文](https://zdoc.app/zh/droidrun/mobilerun) </div> <p align="center"> <img src="./static/mobilerun-demo.gif" alt="Mobilerun automating a phone with natural language" width="320"> </p> - 🤖 Control Android and iOS devices with natural language commands - 🔀 Use OpenAI, Anthropic, Gemini, xAI, Ollama, DeepSeek, OpenRouter, and OpenAI-compatible models - 🧠 Run direct tasks or enable reasoning mode for complex multi-step automation - 💻 Automate from the CLI, a terminal UI, Docker, or Python code - 🐍 Extend agents with custom tools, structured output, app cards, and credentials - 📸 Combine accessibility trees with screenshots for visual understanding - Trace execution with Arize Phoenix or Langfuse 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). ## 📦 Installation > **Note:** Python 3.14 is not currently supported. Please use Python `>=3.11,<3.14`. Install Mobilerun with [`uv`](https://docs.astral.sh/uv/): ```bash # CLI usage uv tool install mobilerun ``` ```bash # CLI + Python integration uv pip install mobilerun ``` Most LLM providers are included by default. For Anthropic support, install the optional extra: ```bash uv tool install "mobilerun[anthropic]" ``` ## 🚀 Quickstart ```bash uv tool install mobilerun mobilerun setup mobilerun configure mobilerun run "Open settings and turn on dark mode" ``` 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. iOS setup is supported separately through the iOS Portal flow. ### 1. Install the Portal on your device ```bash mobilerun setup ``` This installs the Mobilerun Portal app, enables its accessibility service, and prepares the device for local control. ### 2. Verify the connection ```bash mobilerun ping ``` You should see confirmation that the Portal is installed and accessible. ### 3. Configure your LLM provider ```bash mobilerun configure ``` 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`. ### 4. Run your first command ```bash mobilerun run "Open the settings app and tell me the Android version" ``` Useful run options: ```bash mobilerun run "Open settings and turn on dark mode" mobilerun run "What app is currently open?" --vision mobilerun run "Find a contact named John and send him an email" --reasoning mobilerun run "Take a screenshot" --ios mobilerun run "Open Settings" --steps 30 --debug ``` Read the full [framework documentation](https://docs.mobilerun.ai/framework/quickstart). ## ⚙️ Features - **CLI:** Run one-off natural language tasks, inspect devices, replay macros, and debug from the terminal. - **Python API:** Build custom mobile automation workflows with Python and use custom tools. - **Android and iOS support:** Control Android through the Portal app or target iOS through the iOS Portal flow. - **Portal-based control:** Use UI trees, screenshots, text input, gestures, app launching, and device state from the Portal runtime. - **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). - **Reasoning mode:** Use `--reasoning` for manager-executor planning on longer or more complex tasks. - **Tracing and telemetry:** Debug execution with Arize Phoenix, Langfuse, saved trajectories, and detailed logs. - **Structured output:** Return structured data from mobile workflows. - **App cards and custom tools:** Add app-specific guidance to make agent perform better on your use-cases. - **Docker:** Run Mobilerun in a container for repeatable local environments. ## ☁️ Framework vs Cloud | | Mobilerun Framework | Mobilerun Cloud | | --- | --- | --- | | 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 | | Runtime | Your machine | Mobilerun-managed infrastructure | | Interface | CLI, Docker, and Python API | Dashboard, REST API, SDKs, and hosted devices | 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). ### Which should I choose? - Choose **Mobilerun Framework** for local agent execution and code-level control. - Choose **Mobilerun Cloud** for managed phones, APIs, and scale without running agents locally. ### Cloud Device Types | Device type | What it is | Best for | | --- | --- | --- | | Personal | Your own hardware connected to Mobilerun Cloud | Quick automation on devices you own | | Cloud Phone (Hosted) | Instantly available cloud-hosted phone | Scalable hosted automation | | Physical Phone (Hosted) | Real hardware with stronger identity characteristics | Workflows that need high device authenticity and trust | ### Automate WhatsApp on a Cloud Phone <a href="https://www.youtube.com/watch?v=2A8D8NtNfz8"> <img src="./static/whatsapp-automation.gif" alt="Mobilerun automating WhatsApp on a cloud device" width="800"> </a> ### Generate leads with Google Maps on a Cloud Phone <a href="https://www.youtube.com/watch?v=CaL71WorysA"> <img src="./static/google-maps.gif" alt="Mobilerun generating business leads with Google Maps on a cloud device" width="800"> </a> ## 🧩 Agent Skill 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: ```text Set up https://github.com/droidrun/mobile-harness for me. Read `install.md` and follow the steps to install `mobile-harness`. ``` The skill teaches the agent to drive local devices (ADB, Portal, iOS Simulator) and Mobilerun Cloud phones. ## 🎬 Demo Videos ### Book accommodation from a prompt Shows multi-step navigation, text input, and app-state reasoning while Mobilerun searches for accommodation. <a href="https://youtu.be/VUpCyq1PSXw"> <img src="./static/demo-apartment-search.gif" alt="Mobilerun booking accommodation from a prompt" width="800"> </a> ### Find trending content Shows browsing, app navigation, and result extraction from a natural-language task. <a href="https://youtu.be/7V8S2f8PnkQ"> <img src="./static/demo-reddit-trends.gif" alt="Mobilerun finding trending content from a prompt" width="800"> </a> ## 💡 Example Use Cases - Mobile app QA and regression testing - Guided workflows for non-technical users - Repetitive task automation on mobile devices - Event-driven automation from schedules, notifications, or custom triggers - Data extraction from native mobile apps - Running automations on multiple devices at once ## 📚 Documentation - [Framework quickstart](https://docs.mobilerun.ai/framework/quickstart) - [Mobilerun cloud quickstart](https://docs.mobilerun.ai/quickstart) - [Device setup](https://docs.mobilerun.ai/framework/guides/device-setup) - [CLI guide](https://docs.mobilerun.ai/framework/guides/cli) - [SDK reference](https://docs.mobilerun.ai/framework/sdk/reference) - [Custom tools](https://docs.mobilerun.ai/framework/features/custom-tools) - [Agent architecture](https://docs.mobilerun.ai/framework/concepts/architecture) - [Structured output](https://docs.mobilerun.ai/framework/features/structured-output) - [Tracing](https://docs.mobilerun.ai/framework/features/tracing) ## 👥 Contributing Contributions are welcome. Please feel free to submit a pull request or open an issue. ## 📄 License This project is licensed under the MIT License. See [LICENSE](./LICENSE) for details. ## Security Checks To help catch security issues before submitting changes, run: ```bash bandit -r mobilerun safety scan ```