Mobilerun is an open-source Python framework that enables LLM agents to control Android and iOS devices through natural language commands. The framework provides agents with mobile-native tools to inspect UI state, understand screenshots, perform gestures like tapping and swiping, type text, plan multi-step workflows, and return results via CLI or Python API. It is LLM agnostic, supporting OpenAI, Anthropic, Gemini, Ollama, DeepSeek, OpenRouter, and OpenAI-compatible models.
The framework operates through a Portal app installed on target devices that enables accessibility service integration and prepares devices for local control. For Android, control is achieved through the Portal app with ADB connectivity, while iOS support is handled through a separate iOS Portal flow. Users can interact with Mobilerun through multiple interfaces including a command-line interface, terminal UI, Docker containers, or direct Python code. The framework combines accessibility trees with screenshots for comprehensive visual understanding of mobile app interfaces.
Key features include a vision mode for sending screenshots to LLMs and a vision-only mode for apps lacking accessibility tree information. A reasoning mode enables manager-executor planning for complex multi-step tasks. The framework supports tracing and telemetry through Arize Phoenix and Langfuse integration, allowing users to debug execution with saved trajectories and detailed logs. Users can return structured data from mobile workflows, add app-specific guidance through app cards, and extend agents with custom tools and credentials.
The repository maintains active development with a median issue and pull request response latency of 1.5 hours across 168 tracked items, though the mean latency extends to 44.2 hours. The most active issue labels are bounty-official with 16 items, followed by enhancement and bug categories with 10 items each. Top contributors tracked by GitGenius include johnmalek312 with 174 events, Timo972 with 115 events, and sleynsol with 102 events. The project shares overlapping contributors with significant-gravitas/autogpt, activepieces/activepieces, and droidrun/droidrun repositories.
Mobilerun offers both a local framework and a cloud-based service. The framework is designed for users wanting full local control of agent runtime and code-level customization, while Mobilerun Cloud provides managed infrastructure, ready-to-go device control, API-driven workflows, and hosted virtual or physical phones without requiring local agent execution. Cloud device types include personal devices connected to Mobilerun Cloud, instantly available cloud-hosted phones, and real hardware with stronger identity characteristics for high-authenticity workflows.
Use cases span mobile app QA and regression testing, guided workflows for non-technical users, repetitive task automation, event-driven automation from schedules or notifications, data extraction from native mobile apps, and multi-device automation. The framework requires Python 3.11 or higher but does not currently support Python 3.14. Installation is handled through the uv package manager, with most LLM providers included by default and Anthropic support available as an optional extra. The project is licensed under the MIT License and welcomes community contributions.
