Quickstart

This guide will help you get Mobilerun installed and running quickly, controlling your Android device through natural language in minutes.

This is the open source Framework. It runs locally on your machine against your own Android device over adb, and it uses your own LLM provider key such as GOOGLE_API_KEY or OPENAI_API_KEY. If you would rather use hosted devices and a managed agent with no local setup, use the Cloud Quickstart instead.

Prerequisites

Python 3.14 is not yet supported. Installing Mobilerun on Python 3.14 will silently fall back to an older version (e.g. 0.3.9) due to a dependency that does not yet support Python 3.14. Use Python 3.11, 3.12, or 3.13.

Before installing Mobilerun, ensure you have:

Python 3.11, 3.12, or 3.13 installed on your system
Android Debug Bridge (adb) installed and configured
Android device with:
- Developer options enabled
- USB debugging enabled
- Connected via USB or on the same network (for wireless debugging)

Installation

Mobilerun is installed using uv, a fast Python package installer and resolver. Install uv (if not already installed):

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Choose your installation method: For CLI usage only:

uv tool install mobilerun

For CLI + Python code integration:

uv pip install mobilerun

Google Gemini, OpenAI, xAI, DeepSeek, MiniMax, ZAI, Ollama, and OpenRouter support is included by default. Anthropic requires the optional extra: use uv tool install 'mobilerun[anthropic]' for CLI-only use or uv pip install 'mobilerun[anthropic]' in a Python project.

Set Up the Portal APK (Recommended)

Portal is the recommended way to control Android devices. It improves text entry and helps Mobilerun read the screen reliably. To use Android through ADB without Portal, see Device Setup.

mobilerun setup

This command automatically:

Downloads the Portal APK compatible with this Mobilerun version
Installs it on your connected device and grants the Android permissions allowed during installation
Attempts to enable the accessibility service, opening Settings if manual action is required

Use mobilerun setup --latest to opt into the newest Portal release, or mobilerun setup --portal-version <version> to pin a specific release.

Test Connection

Verify that Portal is available:

mobilerun ping

If successful, you’ll see:

Portal is installed and accessible. You're good to go!

mobilerun ping checks Portal. For an ADB-only setup, run adb devices -l instead.

Configure Your LLM

Run the configure wizard to choose your provider, auth method (API key or OAuth), and model:

mobilerun configure

The wizard saves your provider and model settings. See the CLI guide for OAuth sign-in commands and configuration file locations. Alternatively, you can set an API key as an environment variable:

# For Google Gemini (default)
export GOOGLE_API_KEY=your-api-key-here

# For OpenAI
export OPENAI_API_KEY=your-api-key-here

# For xAI Grok
export XAI_API_KEY=your-api-key-here

# For Anthropic Claude
export ANTHROPIC_API_KEY=your-api-key-here

Run Your First Command via CLI

Now you’re ready to control your device with natural language:

# Using default configuration (Google Gemini)
mobilerun run "Open the settings app and tell me the Android version"

# Override provider and model
mobilerun run "Check the battery level" --provider OpenAI --model gpt-5.5

# Enable vision mode (sends screenshots to LLM)
mobilerun run "What app is currently open?" --vision

# Enable reasoning mode (uses Manager-Executor workflow for complex tasks)
mobilerun run "Find a contact named John and send him an email" --reasoning

Common CLI flags:

--provider - LLM provider (GoogleGenAI, OpenAI, XAI, Anthropic, etc.)
--model - Model name (gemini-3.7-flash, gpt-5.5, etc.); pass it together with --provider
--vision - Enable screenshot processing
--vision-only - Use screenshots without an accessibility tree
--reasoning - Enable multi-agent planning mode
--steps N - Maximum execution steps (default: 15)
--debug - Enable detailed logging

Create a Simple Agent via Script

For complex automation or integration into your Python projects, create a script:

import asyncio
from mobilerun import MobileAgent, MobileConfig

async def main():
    # Use default configuration with built-in LLM profiles
    config = MobileConfig()

    # Create agent
    # LLMs are automatically loaded from config.llm_profiles
    agent = MobileAgent(
        goal="Open Settings and check battery level",
        config=config,
    )

    # Run agent
    result = await agent.run()

    # Check results (result is a ResultEvent object)
    print(f"Success: {result.success}")
    print(f"Reason: {result.reason}")
    print(f"Steps: {result.steps}")

if __name__ == "__main__":
    asyncio.run(main())

Next Steps

Now that you’ve got Mobilerun running, explore these topics:

Walk through a Guide
Learn about Agent Architecture
Customize the Agent Configuration System
Guide the agent with App Cards

Introduction

Features

Guides

Concepts

SDK Reference

Prerequisites

Installation

Set Up the Portal APK (Recommended)

Test Connection

Configure Your LLM

Run Your First Command via CLI

Create a Simple Agent via Script

Next Steps

​Prerequisites

​Installation

​Set Up the Portal APK (Recommended)

​Test Connection

​Configure Your LLM

​Run Your First Command via CLI

​Create a Simple Agent via Script

​Next Steps

Prerequisites

Installation

Set Up the Portal APK (Recommended)

Test Connection

Configure Your LLM

Run Your First Command via CLI

Create a Simple Agent via Script

Next Steps