mobilerun

Mobilerun is an open-source framework that enables LLM agents to control Android and iOS devices using natural language commands. It is model-agnostic, supporting providers such as OpenAI, Anthropic, Gemini, xAI, Ollama, DeepSeek, OpenRouter, and any OpenAI-compatible API. The framework bridges the gap between large language models and physical or virtual mobile devices, allowing users to describe tasks in plain English and have an agent execute them on a phone. The core runtime is called the Portal, which is installed on the target device. It exposes UI trees, screenshots, text input, gestures, app launching, and device state to the agent. The agent can operate in two modes: a direct mode for straightforward tasks and a reasoning mode (enabled with --reasoning) that uses a manager-executor architecture for complex, multi-step workflows. A vision mode (--vision or --vision-only) sends screenshots to the LLM for visual understanding, which is especially useful for apps that lack accessibility tree information. Users can interact with Mobilerun through several interfaces: a command-line tool (CLI) for one-off tasks, device inspection, macro replay, and debugging; a Python API for building custom automation workflows and integrating custom tools; and Docker for repeatable containerized environments. The CLI quickstart involves installing via uv, running mobilerun setup to install the Portal app on the device, configuring an LLM provider with mobilerun configure, and then executing commands like mobilerun run "Open settings and turn on dark mode". The framework supports structured output for returning machine-readable data from mobile workflows, custom tools for extending agent capabilities, and app cards that provide app-specific guidance to improve agent performance on particular use cases. Tracing and telemetry are built in, with support for Arize Phoenix, Langfuse, saved trajectories, and detailed logs to debug agent execution. Mobilerun also offers a cloud service (Mobilerun Cloud) that provides managed infrastructure, hosted real or virtual devices, REST APIs, SDKs, and dashboard-driven workflows. Cloud device types include personal devices connected to the cloud, cloud-hosted phones for scalable automation, and physical hosted phones for workflows requiring high device authenticity. Example cloud use cases include automating WhatsApp on a cloud phone and generating leads from Google Maps. Typical use cases include 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 running automations across multiple devices simultaneously. The project also provides a mobile-harness skill that can be integrated into coding agents like Claude Code or Codex to give them direct control of mobile devices. The project is licensed under the MIT License and welcomes contributions. Security checks can be run with bandit and safety scan. Python 3.11 through 3.13 are supported; Python 3.14 is not currently supported.