Mobilerun: driving Android and iOS with LLM agents from the CLI

What Mobilerun solves, and who is expected to use it

Test automation frameworks assume you can address a widget by ID, resource name or accessibility label. On a phone, that assumption breaks constantly: apps ship opaque custom views, accessibility trees go missing, and the same screen is drawn differently across vendors. Mobilerun's answer is to stop writing selectors and write a sentence instead. The README describes it as "an open-source framework for controlling Android and iOS devices with LLM agents", and the agent gets tools to inspect UI state, read screenshots, tap, swipe, type and plan multi-step workflows.

The intended user is a Python developer comfortable with a terminal. The CLI is the shortest path, the Python API is for embedding the agent in a larger workflow, and the README also lists a terminal UI and Docker as execution surfaces. It is not aimed at someone who wants a no-code phone assistant: there is no mention of a graphical desktop application, and the setup steps assume you can install platform tools and enable developer settings on the device. The project is published under MIT, and pyproject.toml classifies it as Beta, which is the honest signal to weigh when you decide how much of your pipeline to hang on it.

The Portal runtime and how a task actually flows

Mobilerun does not talk to the Android UI directly. A companion app called the Portal runs on the device, and the framework drives it. The README lists what the Portal exposes: UI trees, screenshots, text input, gestures, app launching and device state. That is the whole control surface. The agent never gets a raw shell on the phone; it gets a structured view of what is on screen plus a fixed set of actions.

A run therefore has a recognizable shape. You give a natural language instruction. The agent reads the current UI tree, and optionally a screenshot, decides on an action, executes it through the Portal, then re-reads the screen to see what changed. That loop repeats until the task is done or the step budget runs out. Two flags change the shape of the loop. With --vision, screenshots go to the model alongside the tree, which the README says helps with visual understanding. With --vision-only, control is screenshot-only, which the README recommends for apps that do not expose accessibility tree information. With --reasoning, the project switches to a manager-executor arrangement for longer or more complex tasks, so one model plans and another carries out steps.

The model layer is deliberately not fixed. pyproject.toml pulls in llama-index providers for OpenAI, Google GenAI, Ollama and OpenRouter, and the README adds Anthropic, xAI, DeepSeek and OpenAI-compatible endpoints. Because the provider is a dependency choice rather than a hardcoded client, swapping models is a configuration change, and local inference through Ollama is a supported path rather than a workaround.

Installing Mobilerun and running a first command

Installation goes through uv. The README gives two forms, and the difference matters: uv tool install puts the CLI on your PATH as an isolated tool, while uv pip install brings the package into an environment you can import from Python. Python 3.14 is explicitly not supported; the README asks for >=3.11,<3.14, and pyproject.toml encodes the same range.

uv tool install mobilerun

If you plan to call the agent from your own code, use the pip form instead. Anthropic support is an optional extra rather than a default dependency, so install it with the extra syntax when you need that provider:

uv pip install mobilerun
uv tool install "mobilerun[anthropic]"

Before any of that can work, ADB has to be installed and the device has to have Developer options and USB debugging enabled. The README points at the Android platform-tools page for ADB. iOS is handled separately through what the README calls the iOS Portal flow. Then the device-side setup:

mobilerun setup
mobilerun ping
mobilerun configure

The first command installs the Mobilerun Portal app, enables its accessibility service and prepares the device. The second is a health check: you should see confirmation that the Portal is installed and reachable. The third is an interactive wizard for provider, auth method and model. If you prefer environment variables over the wizard, the README names GOOGLE_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, XAI_API_KEY and MINIMAX_API_KEY as the recognized ones.

With the device confirmed, the first real task is a single command:

mobilerun run "Open the settings app and tell me the Android version"

Run options are passed as flags on the same command. The README shows --vision for screenshot-assisted reading, --reasoning for planner-executor mode, --ios to target iOS, and --steps 30 --debug to cap the run and get verbose output. Expect the agent to take several turns: open the app, read the screen, find the value, report it. The --steps flag is the guardrail you will reach for first, because an agent that misreads a screen will keep trying until the budget stops it.

Where the design gets in your way

The Portal requirement is the largest constraint. Control flows through an app on the device, so anything that blocks accessibility services, kills background apps aggressively, or restricts app installation removes your automation layer entirely. The README also states that iOS setup is supported separately through the iOS Portal flow, which tells you the two platforms are not at parity and that you should not assume an Android recipe transfers.

Model choice is a real dependency, not a detail. A screenshot-only run on a complex app pushes a lot of image tokens through your provider, and the reasoning mode adds a second model role on top. The README does not publish per-run token or cost figures, so budgeting is something you measure yourself against your own provider account. Local inference through Ollama removes the per-token cost but moves the constraint to your hardware.

Version pinning is the other thing to notice before you build on it. pyproject.toml pins llama-index==0.14.23 exactly and llama-index-llms-openai==0.7.10 exactly, while other provider packages use ranges. If your environment already depends on a different llama-index version, you have a conflict to resolve. The Beta classifier plus a 0.6.x version line means the Python API surface can move between releases; the release history shows three patch releases across roughly a month, so treat upgrades as work rather than as a background task. The README does not document a rollback procedure, so pin the version you validate against.

Finally, consider whether a deterministic tool is a better fit. If the app you are testing exposes stable accessibility identifiers, Appium or Espresso will be faster, cheaper and reproducible. Mobilerun earns its place when the screen is the only reliable interface.

Mobilerun Cloud versus running the agent yourself

The README draws a clear line: use the framework when you want the agent running on your machine, and use Mobilerun Cloud when you want managed infrastructure, cloud-hosted virtual or physical phones, and API-driven device workflows without running the agent locally. That is the real alternative within the same project rather than a different product, and the difference is operational. Local means you own ADB, the USB connection, the Portal installation and the model credentials. Cloud means those become someone else's problem, at the cost of sending your device sessions through a hosted service.

The choice usually comes down to where the devices live. A developer with one phone on a desk is well served by the local path. A team that needs several devices running in parallel, or needs to reach phones it cannot physically touch, has a different problem, and the local framework does not solve it. If your requirement is a general-purpose browser or desktop agent, neither option applies: Mobilerun is scoped to Android and iOS devices, and the README does not claim otherwise.

Licence, maintenance and the cost of upgrading

Mobilerun is MIT licensed, and pyproject.toml carries the matching classifier. MIT is permissive: you can use it commercially, modify it and redistribute it, provided the copyright notice and permission notice travel with the code. That covers the framework. It does not automatically cover the Portal app, the hosted Cloud service, or the model providers you connect, each of which has its own terms, and the README does not spell those out. If you are shipping a product on top of this, read the licence files for each component you actually depend on rather than assuming MIT applies across the stack.

On activity: the repository is not archived, and the last push was on 2026-09-10. The most recent release listed is v0.6.18 on 2026-09-06, with v0.6.17 and v0.6.16 in the weeks before. That is a project still moving.

The upgrade cost is concentrated in the pinned dependencies. Because llama-index is pinned to an exact version, a Mobilerun upgrade can force a coordinated change in the rest of your environment, and the Beta status means the API you call today may be reshaped in a minor release. The practical approach is to pin the Mobilerun version in your own lockfile, run the CLI smoke test after each bump, and keep the model configuration in environment variables so a provider swap does not require a code change.

Editorial conclusion

Adopt Mobilerun if you are a Python developer who wants an LLM agent to drive a real Android or iOS device and you are willing to install the Portal app and keep ADB working. Do not adopt it if you need a stable API, since the package is marked Beta and pinned to an exact llama-index release. Verify first that your Python version is in the 3.11 to 3.13 range, that mobilerun ping confirms the Portal, and that your chosen provider is actually listed in the configure wizard.

Frequently asked questions

Official sources

1. droidrun/mobilerun on GitHub
2. License: MIT
3. Project website
4. README
5. Releases