📕 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
📦 Installation
Note: Python 3.14 is not currently supported. Please use Python >=3.11,<3.14.
Install Mobilerun with uv:
# CLI usage
uv tool install mobilerun
# CLI + Python integration
uv pip install mobilerun
Most LLM providers are included by default. For Anthropic support, install the optional extra:
uv tool install "mobilerun[anthropic]"
🚀 Quickstart
uv tool install mobilerun
mobilerun setup
mobilerun configure
mobilerun run "Open settings and turn on dark mode"
Before starting, make sure you have ADB installed and an Android device with Developer options and USB debugging enabled. For iOS, set up mobilerun-ios for an iPhone or the iOS Portal app for the simulator.
1. Install the Portal on your device
mobilerun setup
This installs the Mobilerun Portal app, enables its accessibility service, and prepares the device for local control.
2. Verify the connection
mobilerun ping
You should see confirmation that the Portal is installed and accessible.
3. Configure your LLM provider
mobilerun configure
The wizard walks you through choosing a provider, auth method, and model. You can also use provider environment variables such as GOOGLE_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, XAI_API_KEY, or MINIMAX_API_KEY.
4. Run your first command
mobilerun run "Open the settings app and tell me the Android version"
Useful run options:
mobilerun run "Open settings and turn on dark mode"
mobilerun run "What app is currently open?" --vision
mobilerun run "Find a contact named John and send him an email" --reasoning
mobilerun run "Take a screenshot" --ios
mobilerun run "Open Settings" --steps 30 --debug
Read the full framework documentation.
⚙️ Features
- CLI: Run one-off natural language tasks, inspect devices, replay macros, and debug from the terminal.
- Python API: Build custom mobile automation workflows with Python and use custom tools.
- Android and iOS support: Control Android through the Portal app, iPhones through
mobilerun-ios, or the iOS Simulator through the iOS Portal app.
- Portal-based control: Use UI trees, screenshots, text input, gestures, app launching, and device state from the Portal runtime.
- Vision mode: Send screenshots to the LLM with
--vision, or use screenshot-only control with --vision-only (useful for the apps that do not have a11y tree information).
- Reasoning mode: Use
--reasoning for manager-executor planning on longer or more complex tasks.
- Tracing and telemetry: Debug execution with Arize Phoenix, Langfuse, saved trajectories, and detailed logs.
- Structured output: Return structured data from mobile workflows.
- App cards and custom tools: Add app-specific guidance to make agent perform better on your use-cases.
- Docker: Run Mobilerun in a container for repeatable local environments.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
