README

Mobilerun is an open-source framework for mobile app testing, QA, and running AI agents on real Android and iOS devices.
  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.




📕 Documentation
·
☁️ Mobilerun Cloud
·
🛡️ Mobile Harness











  
  
  



Deutsch | 
Español | 
français | 
日本語 | 
한국어 | 
Português | 
Русский | 
中文





  


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

 🎯 Platform Support

| Target | Supported | Setup |
| --- | :---: | --- |
| Android Real Device | ✅ | adb or the Portal app |
| Android Emulator | ✅ | Running emulator (adb) |
| iOS Real Device | ✅ | mobilerun-ios over USB |
| iOS Simulator | ✅ | iOS Portal app |
| Android on Mobilerun Cloud | ✅ | Hosted phones or your own |
| iOS on Mobilerun Cloud | ✅ | Hosted iPhones or your own |

 📦 Installation

 Note: Python 3.14 is not currently supported. Please use Python =3.11,
  


 🧩 Agent Skill

Give Claude Code, Codex, or another coding agent direct control of Android and iOS devices with the 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, iPhones, 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.


  


 Find trending content

Shows browsing, app navigation, and result extraction from a natural-language task.


  


 💡 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
- Testing the same flow across many devices and OS versions in parallel

 🌐 Part of Mobilerun

Mobilerun is one piece of a toolkit for driving real phones with AI agents:

- Mobilerun Portal: the Android app that lets you control and auto