> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mobilerun.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Get up and running with Mobilerun quickly and effectively

<iframe className="w-full aspect-video rounded-xl" src="https://www.youtube.com/embed/4WT7FXJah2I" title="YouTube video player" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />

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

<Note>
  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](/cloud/quickstart) instead.
</Note>

### Prerequisites

<Warning>
  **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.
</Warning>

Before installing Mobilerun, ensure you have:

1. **Python 3.11, 3.12, or 3.13** installed on your system
2. [Android Debug Bridge (adb)](https://developer.android.com/studio/releases/platform-tools) installed and configured
3. **Android device** with:
   * [Developer options enabled](https://developer.android.com/studio/debug/dev-options)
   * USB debugging enabled
   * Connected via USB or on the same network (for wireless debugging)

### Installation

Mobilerun is installed using [`uv`](https://docs.astral.sh/uv/), a fast Python package installer and resolver.

**Install uv (if not already installed):**

```bash theme={null}
# 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:**

```bash theme={null}
uv tool install mobilerun
```

**For CLI + Python code integration:**

```bash theme={null}
uv pip install mobilerun
```

<Note>
  Most LLM providers (Google Gemini, OpenAI, Ollama, OpenRouter) are included by default. For additional providers, install extras: `uv tool install 'mobilerun[anthropic,deepseek]'`.
</Note>

### Set Up the Portal APK

Mobilerun requires the Portal app to be installed on your Android device for device control. The Portal app provides accessibility services that expose the UI accessibility tree, enabling the agent to see and interact with UI elements.

```bash theme={null}
mobilerun setup
```

This command automatically:

1. Downloads the latest Portal APK
2. Installs it on your connected device
3. Enables the accessibility service

### Test Connection

Verify that Mobilerun can communicate with your device:

```bash theme={null}
mobilerun ping
```

If successful, you'll see:

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

### Configure Your LLM

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

```bash theme={null}
mobilerun configure
```

Alternatively, you can set an API key as an environment variable:

```bash theme={null}
# For Google Gemini (default)
export GOOGLE_API_KEY=your-api-key-here

# For OpenAI
export OPENAI_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:

```bash theme={null}
# 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-4o

# 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, Anthropic, etc.)
* `--model` - Model name (gemini-3.1-flash-lite-preview, gpt-4o, etc.)
* `--vision` - Enable screenshot processing
* `--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:

```python theme={null}
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](/framework/guides/overview)
* Learn about [Agent Architecture](/framework/concepts/architecture)
* Customize the Agent [Configuration System](/framework/sdk/configuration)
* Guide the agent with [App Cards](/framework/features/app-cards)

***