Mobilerun: LLM-driven control of Android and iOS devices through a Portal app
Automate your mobile devices with natural language commands - an LLM agnostic mobile Agent 🤖
At a glance
- What is it?
- Mobilerun is an MIT-licensed Python framework that turns natural language into taps, swipes and text input on real phones by pairing accessibility trees with screenshots. It is a reasonable fit for engineers who already have ADB and a device on the desk, and a poor fit for anyone expecting a managed fleet.
- Who is it for?
- Adopt Mobilerun if you already have ADB, a spare Android device with USB debugging enabled, and a Python 3.11 to 3.13 environment, and you want the agent loop running on your own machine where you can read the logs and swap models. Do not adopt it if you need to drive a fleet of phones, if you are pinned to Python 3.14, or if you want someone else to own device connectivity.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 1 day ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap Mobilerun fills between ADB and a real UI agent
Scripting a phone with ADB is deterministic and brittle in the same breath. You can send input taps at fixed coordinates, dump the view hierarchy, and parse it, but the moment a dialog appears or the layout shifts the script breaks. Mobilerun takes the other position: instead of you writing the coordinates, an LLM reads the device state and decides where to act. The README describes it as an open-source framework for controlling Android and iOS devices with LLM agents, exposing mobile-native tools for inspecting UI state, reading screenshots, tapping, swiping, typing and planning multi-step workflows. The intended user is an engineer who wants that loop running locally, not a QA team buying a device farm. The README is explicit about the split: use the framework when you want to run the agent on your own machine, and use Mobilerun Cloud when you want managed infrastructure and API-driven device workflows without hosting the agent yourself.
Portal, accessibility trees and screenshots as the control surface
The mechanism is a companion app on the device. mobilerun setup installs the Mobilerun Portal app, enables its accessibility service, and prepares the device for local control. Everything the agent does flows through that runtime. According to the README, the Portal provides UI trees, screenshots, text input, gestures, app launching and device state. The agent therefore has two information channels rather than one: the accessibility tree gives structured, addressable elements, and screenshots give visual context for anything the tree does not describe well. That dual channel is why vision mode exists as a flag rather than a default. mobilerun run "What app is currently open?" --vision sends screenshots to the model alongside the tree. There is also --vision-only for what the README calls screenshot-only control, aimed at apps that do not expose accessibility tree information. For longer tasks, --reasoning switches the agent into manager-executor planning, which is a different loop from direct execution: one component plans, another carries out steps. The model itself is swappable. OpenAI, Anthropic, Gemini, xAI, Ollama, DeepSeek, OpenRouter and OpenAI-compatible endpoints are listed, so the same task can be pointed at a hosted frontier model or a local Ollama instance without changing the automation code.
Getting from install to a first command
The install path assumes uv. For CLI-only use it is uv tool install mobilerun; for CLI plus Python integration it is uv pip install mobilerun. Anthropic support sits behind an optional extra, so that install becomes uv tool install "mobilerun[anthropic]". Python compatibility is bounded: the README states that Python 3.14 is not currently supported and asks for >=3.11,<3.14. That is a real constraint on a modern toolchain, and it is worth checking before you build a virtualenv around the project. Android prerequisites are ADB plus a device with Developer options and USB debugging enabled; iOS is described as supported separately through the iOS Portal flow, with a --ios flag on run commands. The sequence the README gives is mobilerun setup, then mobilerun ping to confirm the Portal is installed and accessible, then mobilerun configure, a wizard that walks through provider, auth method and model. Provider keys can instead come from environment variables such as GOOGLE_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, XAI_API_KEY or MINIMAX_API_KEY. A first task looks like mobilerun run "Open the settings app and tell me the Android version". Run options include --steps 30 to bound the loop and --debug for verbose output, which is the pair you want when a task stalls rather than fails.
Where the framework model breaks down
Running the agent locally means owning the device connection, and that is the weakest link. The Portal is an app with an accessibility service, so anything that disables or kills that service takes the agent offline mid-task, and mobilerun ping is the only diagnostic the README names for checking it. There is no described retry or reconnect policy. The vision-only path is a concession rather than a feature: it exists because some apps do not expose accessibility tree information, and screenshot-only control is slower and less precise than addressing elements directly. Reasoning mode is likewise a trade, since manager-executor planning adds model calls per task; the README presents it for longer or more complex work, not as a default. Cost scales with steps, and --steps 30 exists precisely because a loop can run away. The wrong tool case is fleet automation. If you need many physical or virtual phones behind an API without running agents on your own hardware, the README points at Mobilerun Cloud instead, and that is a different product with different operational assumptions.
Appium and the scripting-first alternative
Appium is the established alternative for mobile automation, and the difference in approach is not cosmetic. Appium drivers act on element locators that you write: an ID, an accessibility label, an XPath. The test is deterministic, it fails loudly when a locator stops matching, and it does not call a model at runtime. Mobilerun inverts that. You describe the outcome ("Open settings and turn on dark mode") and the agent chooses the locators and gestures itself. That buys resilience to layout changes at the cost of determinism, latency and per-step token spend. A useful way to frame it: Appium scripts encode what to do, Mobilerun encodes what you want. For a regression suite that must produce the same result on every run, Appium remains the better fit. For exploratory flows, one-off device chores, or apps whose element structure is unstable, the agent approach is the one that does not need rewriting after a redesign. Mobilerun does not replace a test runner; it sits in the space where writing a locator-based script is not worth the effort.
Extending the agent and watching what it did
Two extension points matter for anyone past the demo stage. Custom tools let you add capabilities the Portal does not provide, and app cards add app-specific guidance so the agent performs better on your particular use case. Structured output means a mobile workflow can return data rather than just a success flag, which is what makes it usable as a step inside a larger pipeline. Observability is handled by tracing: the README names Arize Phoenix and Langfuse, alongside saved trajectories and detailed logs. That matters more here than in a conventional script, because a failed run does not throw a stack trace at the line that broke. You get a trajectory of decisions to read. The honest caveat is that the README does not describe the trajectory format or what a saved run contains, so the practical value of tracing depends on how much detail those integrations actually capture. That is something to confirm on a real task rather than assume.
Licence, release cadence and what upgrading costs you
Mobilerun is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is a permissive arrangement, but it is not legal advice and the obligations should be read against your own distribution model. The release history shows a fast cadence: v0.6.16 and v0.6.17 landed a day apart in August 2026, with v0.6.18 following in early September. Pre-1.0 version numbers at that frequency mean the public surface can move, so pinning a version in your dependency file is the sensible default, and any upgrade deserves a re-read of the changelog rather than a blind bump. The Python constraint (>=3.11,<3.14) is the kind of thing that changes between minor releases, so re-check it when you upgrade rather than treating the current bound as permanent. Because the agent loop depends on a device-side app, an upgrade is not purely a Python concern: the Portal app and the framework version need to stay compatible, and the README does not document a version negotiation between the two.
Editorial conclusion
Adopt Mobilerun if you already have ADB, a spare Android device with USB debugging enabled, and a Python 3.11 to 3.13 environment, and you want the agent loop running on your own machine where you can read the logs and swap models. Do not adopt it if you need to drive a fleet of phones, if you are pinned to Python 3.14, or if you want someone else to own device connectivity. Before committing, verify three things in this order: that mobilerun ping confirms the Portal app and its accessibility service are live on your target device, that your chosen provider key works through mobilerun configure, and that a single mobilerun run with --vision produces a screenshot the model can actually read on the app you care about.
Community notes