### Mobilerun Quickstart Setup

Source: https://github.com/droidrun/mobilerun/blob/main/README.md

A sequence of commands to install Mobilerun, set up the portal on a device, configure an LLM provider, and run a basic command.

```bash
uv tool install mobilerun
mobilerun setup
mobilerun configure
mobilerun run "Open settings and turn on dark mode"
```

--------------------------------

### Setup Portal APK with Docker

Source: https://github.com/droidrun/mobilerun/blob/main/docs/guides/docker.mdx

Run the Mobilerun container with the `setup` command to install the Portal APK on your connected Android device.

```bash
docker run \
  --group-add plugdev \
  --device /dev/phone1/phone:/dev/phone \
  --volume /dev/bus/usb:/dev/bus/usb \
  --volume ~/.android:/home/mobilerun/.android \
  ghcr.io/droidrun/mobilerun:latest \
  setup
```

--------------------------------

### Complete MobileRun SDK Configuration and Agent Initialization

Source: https://github.com/droidrun/mobilerun/blob/main/docs/sdk/configuration.mdx

This example demonstrates a comprehensive setup of the MobileRun SDK, including defining a Pydantic model for structured output, registering a custom tool, configuring agent and device parameters, integrating multiple LLMs for different roles, and initializing the MobileAgent with a goal and timeout.

```python
from mobilerun import \
    MobileAgent, MobileConfig, \
    AgentConfig, FastAgentConfig, DeviceConfig, LoggingConfig, TracingConfig
from llama_index.llms.openai import OpenAI
from llama_index.llms.google_genai import GoogleGenAI
from pydantic import BaseModel

# Structured output
class Output(BaseModel):
    name: str
    value: int

# Custom tool
def send_email(to: str, subject: str, **kwargs) -> str:
    """Send email."""
    return f"Sent to {to}"

# Build configuration
config = MobileConfig(
    agent=AgentConfig(
        max_steps=30,
        reasoning=True,
        after_sleep_action=1.5,
        fast_agent=FastAgentConfig(vision=True)
    ),
    device=DeviceConfig(
        serial="emulator-5554",
        platform="android",
        use_tcp=False
    ),
    logging=LoggingConfig(
        debug=True,
        save_trajectory="step",
        trajectory_gifs=True
    ),
    tracing=TracingConfig(enabled=True),
)

agent = MobileAgent(
    goal="Complex task",
    config=config,

    # LLMs
    llms={
        "manager": OpenAI(model="gpt-4o"),                    # Planning
        "executor": GoogleGenAI(model="gemini-3.1-flash-lite"),  # Action selection
        "fast_agent": GoogleGenAI(model="gemini-3.1-flash-lite"),   # Fast Agent: Direct execution (XML tool-calling)
        "app_opener": OpenAI(model="gpt-4o-mini"),            # App launching
        "structured_output": GoogleGenAI(model="gemini-3.1-flash-lite"),  # Output extraction
    },

    # Custom tools
    custom_tools={
        "send_email": {
            "parameters": {
                "to": {"type": "string", "required": True},
                "subject": {"type": "string", "required": True},
            },
            "description": "Send email to recipient with subject",
            "function": send_email
        }
    },

    # Credentials
    credentials={"USERNAME": "alice", "PASSWORD": "secret"},

    # Variables
    variables={"api_url": "https://api.example.com"},

    # Structured output
    output_model=Output,

    # Timeout
    timeout=600
)

result = await agent.run()

```

--------------------------------

### Example Workflow with AndroidDriver

Source: https://github.com/droidrun/mobilerun/blob/main/docs/sdk/adb-tools.mdx

Demonstrates a typical workflow using AndroidDriver to connect to a device, start an app, interact with the UI by tapping and inputting text, and capture a screenshot. Ensure the Mobilerun Portal app is installed and accessibility services are enabled on the device.

```python
import asyncio
from mobilerun.tools import AndroidDriver

async def main():
    # Initialize driver
    driver = AndroidDriver(serial="emulator-5554", use_tcp=True)
    await driver.connect()

    # Start Chrome app
    result = await driver.start_app("com.android.chrome")
    print(result)

    # Get UI tree (raw data)
    tree = await driver.get_ui_tree()

    # Tap at coordinates
    await driver.tap(540, 300)

    # Input text
    await driver.input_text("Mobilerun framework")

    # Press enter
    await driver.press_button("enter")

    # Take screenshot
    png_bytes = await driver.screenshot()
    with open("search_result.png", "wb") as f:
        f.write(png_bytes)

asyncio.run(main())
```

--------------------------------

### Setup Mobilerun Portal APK

Source: https://github.com/droidrun/mobilerun/blob/main/docs/quickstart.mdx

Run the setup command to automatically download, install, and enable the Portal APK on your connected Android device. This is required for Mobilerun to control the device.

```bash
mobilerun setup
```

--------------------------------

### Install Portal APK on Device

Source: https://github.com/droidrun/mobilerun/blob/main/docs/guides/cli.mdx

Use 'mobilerun setup' to install the necessary Portal APK on your device. This includes downloading, installing with permissions, and enabling the accessibility service.

```bash
# Auto-detect device
mobilerun setup

# Specific device
mobilerun setup --device emulator-5554

# Custom APK
mobilerun setup --path /path/to/portal.apk
```

--------------------------------

### Setup and Run Basic Command

Source: https://github.com/droidrun/mobilerun/blob/main/docs/guides/cli.mdx

Use 'setup' to prepare your device and 'run' to execute a natural language command. Mobilerun automatically creates a default config file if none exists.

```bash
# Setup device
mobilerun setup

# Run a command
mobilerun run "Open Spotify and play my Discover Weekly"
```

--------------------------------

### Basic Agent Initialization and Run

Source: https://github.com/droidrun/mobilerun/blob/main/docs/sdk/droid-agent.mdx

Demonstrates the basic setup of a MobileAgent to perform a goal, such as taking a screenshot.

```APIDOC
## MobileAgent Basic Usage

### Description
Initializes and runs a MobileAgent to achieve a specified goal.

### Method
`run()`

### Endpoint
N/A (Local execution)

### Request Body
N/A

### Request Example
```python
from mobilerun import MobileAgent
from mobilerun.config_manager import MobileConfig

llm = OpenAI(model="gpt-4o", temperature=0.2)
config = MobileConfig()

agent = MobileAgent(
    goal="Take a screenshot and save it",
    llms=llm,
    config=config
)

result = await agent.run()
```

### Response
#### Success Response (200)
- `ResultEvent` (object) - Contains the outcome of the agent's run.
  - `success` (bool): True if task completed successfully
  - `reason` (str): Success message or failure reason
  - `steps` (int): Number of steps executed
  - `structured_output` (Any): Parsed Pydantic model (if output_model provided, otherwise None)

#### Response Example
```json
{
  "success": true,
  "reason": "Screenshot taken and saved successfully.",
  "steps": 3,
  "structured_output": null
}
```
```

--------------------------------

### Verify Mobilerun Setup

Source: https://github.com/droidrun/mobilerun/blob/main/docs/guides/device-setup.mdx

Confirms that the Mobilerun Portal is installed and accessible on the device. A successful ping indicates that the setup is complete and the device is ready for automation.

```bash
mobilerun ping
# Output: Portal is installed and accessible. You're good to go!
```

--------------------------------

### Install Arize Phoenix

Source: https://github.com/droidrun/mobilerun/blob/main/docs/features/tracing.mdx

Install the Arize Phoenix library using pip.

```sh
uv pip install arize-phoenix
```

--------------------------------

### Example: Custom Manager Prompt with Conditional Logic

Source: https://github.com/droidrun/mobilerun/blob/main/docs/concepts/prompts.mdx

This example demonstrates a custom `manager_system` prompt that includes conditional rendering based on available context variables like `app_card` and `error_history`. It also shows how to structure the output using XML-like tags.

```python
custom_prompts = {
    "manager_system": """
You are a mobile automation planning agent.

Task: {{ instruction }}
Date: {{ device_date }}

{% if app_card %}
App guidance:
{{ app_card }}
{% endif %}

{% if error_history %}
Recent errors (you may be stuck):
{% for error in error_history %}
- Action: {{ error.action }}
  Error: {{ error.error }}
{% endfor %}
{% endif %}

{% if custom_tools_descriptions %}
Custom tools:
{{ custom_tools_descriptions }}
{% endif %}

{% if variables.domain %}
Domain: {{ variables.domain }}
{% endif %}

Output format:
<thought>Your reasoning</thought>
<plan>
1. First step
2. Second step
3. DONE
</plan>

Or if complete:
<request_accomplished>
Task is done. Answer: ...
</request_accomplished>
"""
}

agent = MobileAgent(
    goal="Send an email",
    config=config,
    prompts=custom_prompts,
    variables={"domain": "finance"}
)
```

--------------------------------

### Install Mobilerun CLI

Source: https://github.com/droidrun/mobilerun/blob/main/SKILL.md

Installs the Mobilerun framework including Google Gemini, OpenAI, DeepSeek, Ollama, and OpenRouter support by default. Optional extras like 'anthropic' or 'langfuse' can be installed separately.

```bash
uv tool install mobilerun
```

```bash
uv tool install mobilerun[anthropic,langfuse]
```

--------------------------------

### Troubleshoot: LLM provider errors

Source: https://github.com/droidrun/mobilerun/blob/main/docs/guides/cli.mdx

Install the necessary provider package, check for the API key environment variable, and set it if missing.

```bash
# Install provider
uv pip install 'mobilerun[anthropic]'

# Check API key
echo $GOOGLE_API_KEY

# Set if missing
export GOOGLE_API_KEY=your-key
```

--------------------------------

### Perform Async Operations with Python

Source: https://github.com/droidrun/mobilerun/blob/main/docs/features/custom-tools.mdx

This example shows how to fetch data from a URL asynchronously using 'aiohttp'. Make sure to install the 'aiohttp' library. This is useful for non-blocking I/O operations.

```python
import aiohttp

async def fetch_async(url: str, **kwargs) -> str:
    """Fetch data asynchronously."""
    try:
        async with aiohttp.ClientSession() as session:
            async with session.get(url, timeout=10) as response:
                data = await response.text()
                return f"Fetched {len(data)} bytes from {url}"
    except Exception as e:
        return f"Error: {str(e)}"

custom_tools = {
    "fetch_async": {
        "parameters": {
            "url": {"type": "string", "required": True},
        },
        "description": "Asynchronously fetch data from a URL",
        "function": fetch_async
    }
}
```

--------------------------------

### DeviceDriver App Management

Source: https://github.com/droidrun/mobilerun/blob/main/docs/sdk/base-tools.mdx

Methods for managing applications on the device, including starting, installing, and listing packages. `start_app` can launch an app with a specific activity, and `install_app` supports additional keyword arguments.

```python
start_app(package: str, activity: str | None = None) -> str
install_app(path: str, **kwargs) -> str
list_packages(include_system: bool = False) -> List[str]
get_apps(include_system: bool = True) -> List[Dict[str, str]]
```

--------------------------------

### Example Usage of IOSDriver

Source: https://github.com/droidrun/mobilerun/blob/main/docs/sdk/ios-tools.mdx

Demonstrates initializing the IOSDriver, connecting to a device, launching an app, interacting with the UI, and capturing a screenshot. Ensure the driver is running and accessible at the specified URL.

```python
import asyncio
from mobilerun.tools.driver import IOSDriver

async def main():
    # Initialize and connect
    driver = IOSDriver(url="http://127.0.0.1:6643")
    await driver.connect()

    # Launch Messages
    result = await driver.start_app("com.apple.MobileSMS")
    print(result)

    # Get UI tree
    tree = await driver.get_ui_tree()
    print(tree["phone_state"]["currentApp"])

    # Tap at coordinates
    await driver.tap(200, 400)

    # Input text
    await driver.input_text("Hello from Mobilerun!")

    # Take screenshot
    png_bytes = await driver.screenshot()
    with open("screenshot.png", "wb") as f:
        f.write(png_bytes)

asyncio.run(main())
```

--------------------------------

### Install uv Package Manager

Source: https://github.com/droidrun/mobilerun/blob/main/docs/quickstart.mdx

Install the uv package manager, a fast Python package installer and resolver, using a script. Choose the appropriate command for macOS/Linux or Windows.

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

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

--------------------------------

### AdbDevice App Management

Source: https://github.com/droidrun/mobilerun/blob/main/mobilerun/agent/external/README.md

Provides methods to start, stop, and list installed packages on the device.

```python
# App management
await device.app_start("com.example.app")
await device.app_stop("com.example.app")
packages = await device.list_packages()
```

--------------------------------

### External Agent Configuration Example

Source: https://github.com/droidrun/mobilerun/blob/main/mobilerun/agent/external/README.md

Shows how to configure an external agent in `config.yaml`, including API keys, model names, and other custom settings.

```yaml
external_agents:
  my_agent:
    api_key: "sk-..."
    model: "model-name"
    base_url: "http://localhost:8000/v1"
    # any other settings your agent needs
```

--------------------------------

### Run iOS Portal on Simulator

Source: https://github.com/droidrun/mobilerun/blob/main/docs/guides/device-setup.mdx

Start the iOS Portal on a specific simulator by providing its name to the `simulator.sh` script. No `iproxy` is needed as it's directly accessible.

```bash
# Run the portal on a simulator by name
./simulator.sh "iPhone 16 Pro"
```

--------------------------------

### Install Development Dependencies

Source: https://github.com/droidrun/mobilerun/blob/main/CONTRIBUTING.md

Install the project's development dependencies using pip. This command installs the package in editable mode.

```bash
pip install -e ".[dev]"
```

--------------------------------

### Basic Agent Usage with Custom Variables

Source: https://github.com/droidrun/mobilerun/blob/main/docs/features/custom-variables.mdx

Demonstrates creating an agent with custom variables and a prompt that iterates through them. This setup allows dynamic data to be incorporated into agent tasks.

```python
from mobilerun import MobileAgent, MobileConfig

# Define variables
variables = {
    "recipient": "alice@example.com",
    "message": "Hello from Mobilerun!"
}

# Custom prompt to render variables
custom_prompts = {
    "fast_agent_system": ""
You are an agent that controls Android devices.

{% if variables %}
Available variables:
{% for key, value in variables.items() %}
- {{ key }}: {{ value }}
{% endfor %}
{% endif %}

Use these variables when executing tasks.
    "
}

# Create agent
config = MobileConfig()

agent = MobileAgent(
    goal="Send message to recipient",
    config=config,
    variables=variables,
    prompts=custom_prompts
)

result = await agent.run()
```

--------------------------------

### Install ADB on macOS and Linux

Source: https://github.com/droidrun/mobilerun/blob/main/docs/guides/device-setup.mdx

Installs the Android Debug Bridge (ADB) tool. Use 'brew install android-platform-tools' for macOS and 'sudo apt install adb' for Linux. Verify installation with 'adb version'.

```bash
brew install android-platform-tools
```

```bash
sudo apt install adb
```

```bash
adb version
```

--------------------------------

### Install Mobilerun CLI

Source: https://github.com/droidrun/mobilerun/blob/main/docs/quickstart.mdx

Install Mobilerun for command-line interface (CLI) usage. This command installs the tool globally.

```bash
uv tool install mobilerun
```

--------------------------------

### MobileAgent Configuration Example

Source: https://github.com/droidrun/mobilerun/blob/main/docs/sdk/droid-agent.mdx

Illustrates key configuration options for MobileAgent, including maximum steps, reasoning mode, vision settings for different agent components, device specifics, and logging/tracing preferences.

```yaml
agent:
  max_steps: 15           # Maximum execution steps
  reasoning: false        # Enable Manager/Executor workflow

  fast_agent:
    vision: false         # Enable screenshot analysis
  manager:
    vision: false         # Enable screenshot analysis

  executor:
    vision: false         # Enable screenshot analysis

device:
  serial: null            # Device serial (null = auto-detect)
  platform: android       # "android" or "ios"
  use_tcp: false          # TCP vs content provider

logging:
  debug: false            # Debug logging
  save_trajectory: none   # Trajectory saving: "none", "step", "action"

tracing:
  enabled: false          # Arize Phoenix tracing

```

--------------------------------

### Install libimobiledevice

Source: https://github.com/droidrun/mobilerun/blob/main/docs/guides/device-setup.mdx

To use Mobilerun with iOS, you need to install `iproxy` from `libimobiledevice`. This command uses Homebrew to install the package.

```bash
brew install libimobiledevice
```

--------------------------------

### AdbDevice Usage Examples

Source: https://github.com/droidrun/mobilerun/blob/main/mobilerun/agent/external/README.md

Illustrates various methods available through the `AdbDevice` object for interacting with an Android device.

```APIDOC
## AdbDevice Methods

`AdbDevice` from `async_adbutils` provides raw ADB access. Every method is a thin wrapper over `adb shell`.

### Common Operations

- **Tap**: `await device.click(x, y)` or `device.shell("input tap x y")`
- **Swipe**: `await device.swipe(x1, y1, x2, y2, duration=seconds)`
- **Screenshot**: `png_bytes = await device.screenshot_bytes()`
- **Dump Hierarchy**: `xml = await device.dump_hierarchy()`
- **Key Events**: `await device.keyevent(keycode)` (e.g., `await device.keyevent(4)` for BACK)
- **Type Text**: `await device.send_keys("text")`
- **Run Shell Command**: `output = await device.shell("command")`
- **Screen Size**: `w, h = await device.window_size()`

### App Management

- **Start App**: `await device.app_start("package.name")`
- **Stop App**: `await device.app_stop("package.name")`
- **List Packages**: `packages = await device.list_packages()`
- **Current App Info**: `info = await device.app_current()` (returns `RunningAppInfo` object with `package`, `activity`, `pid`)
```

--------------------------------

### Install Mobilerun with Anthropic Support

Source: https://github.com/droidrun/mobilerun/blob/main/README.md

Install Mobilerun with the optional 'anthropic' extra to enable support for Anthropic LLM providers.

```bash
uv tool install "mobilerun[anthropic]"
```

--------------------------------

### Run First Mobilerun Command

Source: https://github.com/droidrun/mobilerun/blob/main/README.md

Executes a command on the connected Android device. This example opens the settings app and queries the Android version.

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

--------------------------------

### Verify Mobilerun Setup with Docker

Source: https://github.com/droidrun/mobilerun/blob/main/docs/guides/docker.mdx

Use the `ping` command within the Mobilerun Docker container to verify that the setup was successful and the container can communicate with the device.

```bash
docker run \
  --group-add plugdev \
  --device /dev/phone1/phone:/dev/phone \
  --volume /dev/bus/usb:/dev/bus/usb \
  --volume ~/.android:/home/mobilerun/.android \
  ghcr.io/droidrun/mobilerun:latest \
  ping
```

--------------------------------

### Troubleshoot: Portal not accessible

Source: https://github.com/droidrun/mobilerun/blob/main/docs/guides/cli.mdx

Verify mobilerun installation, reinstall if necessary, and enable accessibility services manually.

```bash
# Verify installation
adb shell pm list packages | grep mobilerun

# Reinstall
mobilerun setup

# Enable accessibility manually
adb shell settings put secure enabled_accessibility_services \
  com.mobilerun.portal/com.mobilerun.portal.service.MobilerunAccessibilityService
```

--------------------------------

### Example Action Function: Click

Source: https://github.com/droidrun/mobilerun/blob/main/docs/sdk/base-tools.mdx

An example of an asynchronous action function that simulates a click on a UI element. It takes an element index and an ActionContext, performs the click, and returns an ActionResult.

```python
from typing import Any

class ActionContext:
    def __init__(self):
        self.ui = None
        self.driver = None

async def click(index: int, *, ctx: ActionContext) -> ActionResult:
    """Click the element with the given index."""
    x, y = ctx.ui.get_element_coords(index)
    await ctx.driver.tap(x, y)
    return ActionResult(success=True, summary=f"Clicked on element at ({x}, {y})")
```

--------------------------------

### Install Portal App using Mobilerun CLI

Source: https://github.com/droidrun/mobilerun/blob/main/docs/guides/device-setup.mdx

Installs the Mobilerun Portal app on the device. This command automatically downloads the compatible APK, installs it with necessary permissions, and enables the accessibility service. You can specify a device using its serial number.

```bash
mobilerun setup
```

```bash
mobilerun setup --device SERIAL_NUMBER
```

--------------------------------

### Basic Custom Tool Example

Source: https://github.com/droidrun/mobilerun/blob/main/docs/features/custom-tools.mdx

Demonstrates a simple custom tool for tax calculation without device access. It defines the tool's parameters, description, and the Python function to execute. The tool is then registered with the MobileAgent.

```python
import asyncio
from mobilerun import MobileAgent, MobileConfig

def calculate_tax(amount: float, rate: float, **kwargs) -> str:
    """Calculate tax for a given amount."""
    tax = amount * rate
    total = amount + tax
    return f"Tax: ${tax:.2f}, Total: ${total:.2f}"

custom_tools = {
    "calculate_tax": {
        "parameters": {
            "amount": {"type": "number", "required": True},
            "rate": {"type": "number", "required": True},
        },
        "description": "Calculate tax for a given amount and rate",
        "function": calculate_tax
    }
}

async def main():
    config = MobileConfig()

    agent = MobileAgent(
        goal="Calculate tax for $100 at 8% rate",
        config=config,
        custom_tools=custom_tools
    )

    result = await agent.run()
    print(result.success, result.reason)

asyncio.run(main())
```

--------------------------------

### Example Debug Log Messages

Source: https://github.com/droidrun/mobilerun/blob/main/docs/features/app-cards.mdx

These are example log messages you might see when debugging app card loading. They indicate the number of entries loaded from `app_cards.json` and the specific app card loaded.

```text
Loaded app_cards.json with 2 entries
Loaded app card for com.google.android.gm from config/app_cards/gmail.md
```

--------------------------------

### Run iOS Portal Server

Source: https://github.com/droidrun/mobilerun/blob/main/docs/guides/device-setup.mdx

Execute the device script with your device's UDID to start the portal server on the iOS device.

```bash
./device.sh YOUR_DEVICE_UDID
```

--------------------------------

### Example: Gmail Login Automation with Credentials

Source: https://github.com/droidrun/mobilerun/blob/main/docs/features/credentials.mdx

Automate Gmail login by providing email and password credentials. The agent will open Gmail, type the email, and securely type the password using `type_secret`.

```python
import asyncio
from mobilerun import MobileAgent, MobileConfig

async def main():
    credentials = {
        "EMAIL_USER": "user@example.com",
        "EMAIL_PASS": "secret_password"
    }

    config = MobileConfig()

    agent = MobileAgent(
        goal="Open Gmail and login with my credentials",
        config=config,
        credentials=credentials
    )

    result = await agent.run()
    print(f"Success: {result.success}")

asyncio.run(main())
```

--------------------------------

### Python Description Examples

Source: https://github.com/droidrun/mobilerun/blob/main/docs/features/custom-tools.mdx

Use descriptive and specific descriptions for your tools. Avoid vague descriptions.

```python
# Good
"description": "Send POST request to webhook URL with JSON data payload"

# Bad
"description": "Send webhook"
```

--------------------------------

### Run Mobilerun with Local LLM (LM Studio)

Source: https://github.com/droidrun/mobilerun/blob/main/docs/guides/docker.mdx

Configure Mobilerun to use a locally running LLM, such as one served by LM Studio. This example uses the host network and specifies the API base URL for the local server.

```bash
docker run --group-add plugdev --device /dev/phone1/phone:/dev/phone --volume /dev/bus/usb:/dev/bus/usb --volume ~/.android:/home/mobilerun/.android --network host ghcr.io/droidrun/mobilerun:latest run "Open a browser and search for mobilerun" -p OpenAILike -m gpt-oss --api_base http://IP-of-LMStudio-server:PORT/v1
```

--------------------------------

### Create a Simple Mobilerun Agent via Python Script

Source: https://github.com/droidrun/mobilerun/blob/main/docs/quickstart.mdx

Integrate Mobilerun into your Python projects by creating an agent script. This example demonstrates initializing the agent with a goal and configuration, then running it.

```python
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())
```

--------------------------------

### E-commerce Automation with MobileAgent (Python)

Source: https://github.com/droidrun/mobilerun/blob/main/docs/concepts/prompts.mdx

Automate e-commerce tasks using the MobileAgent. This example demonstrates setting up an agent with custom prompts, injecting variables, and running the automation to buy a product.

```python
from mobilerun import MobileAgent
from mobilerun.config_manager import MobileConfig

# E-commerce automation with custom prompts
ecommerce_prompts = {
    "manager_system": """
You are an e-commerce automation specialist.

Task: {{ instruction }}
Budget: ${{ variables.budget }}

{% if app_card %}
App info:
{{ app_card }}
{% endif %}

{% if error_history %}
Errors encountered:
{% for error in error_history %}
- {{ error.action }}: {{ error.summary }} - {{ error.error }}
{% endfor %}
Consider changing your approach.
{% endif %}

Rules:
1. Verify product names exactly
2. Check prices before purchasing
3. Store order confirmations in memory
4. Never exceed budget

Output:
<thought>Your reasoning</thought>
<plan>
1. Step
2. DONE
</plan>
"""
}

config = MobileConfig()
agent = MobileAgent(
    goal="Buy iPhone 15 Pro from Amazon",
    config=config,
    prompts=ecommerce_prompts,
    variables={"budget": 1200}
)

result = await agent.run()
```

--------------------------------

### Example: Using Custom Variables in Prompts

Source: https://github.com/droidrun/mobilerun/blob/main/docs/concepts/prompts.mdx

This example shows how to pass custom variables to `MobileAgent` and access them within Jinja2 templates. It illustrates using variables like `budget`, `priority`, and a list of `rules` to dynamically tailor the prompt.

```python
custom_prompts = {
    "manager_system": """
Task: {{ instruction }}

{% if variables.budget %}
Budget limit: ${{ variables.budget }}
{% endif %}

{% if variables.priority %}
Priority: {{ variables.priority }}
{% endif %}

Guidelines:
{% for rule in variables.rules %}
- {{ rule }}
{% endfor %}
"""
}

agent = MobileAgent(
    goal="Buy a phone",
    config=config,
    prompts=custom_prompts,
    variables={
        "budget": 1000,
        "priority": "high",
        "rules": ["Check reviews", "Compare prices", "Use coupons"]
    }
)
```

--------------------------------

### Start App on iOS

Source: https://github.com/droidrun/mobilerun/blob/main/docs/sdk/ios-tools.mdx

Launches an application on an iOS device using its bundle identifier. The activity parameter is ignored on iOS.

```python
async def start_app(package: str, activity: str | None = None) -> str


result = await driver.start_app("com.apple.MobileSMS")
result = await driver.start_app("com.apple.mobilesafari")
```

--------------------------------

### Set Up Virtual Environment

Source: https://github.com/droidrun/mobilerun/blob/main/CONTRIBUTING.md

Create and activate a Python virtual environment for development. Use the appropriate command for your operating system.

```bash
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
```

--------------------------------

### Run Mobilerun Agents with Docker

Source: https://github.com/droidrun/mobilerun/blob/main/docs/guides/docker.mdx

Execute Mobilerun agents using Docker. This example demonstrates running an agent that opens the settings app and reports the Android version. Ensure you provide your Google API key via the environment variable.

```bash
# Using default configuration with Google API key
docker run --group-add plugdev --device /dev/phone1/phone:/dev/phone --volume /dev/bus/usb:/dev/bus/usb --volume ~/.android:/home/mobilerun/.android --env GOOGLE_API_KEY=your-api-key-here ghcr.io/droidrun/mobilerun:latest run "Open the settings app and tell me the Android version"
```

--------------------------------

### Troubleshoot: TCP connection fails

Source: https://github.com/droidrun/mobilerun/blob/main/docs/guides/cli.mdx

Enable TCP mode for ADB, get the device IP address, connect mobilerun via TCP, and verify the connection.

```bash
# Enable TCP mode (USB connected first)

adb tcpip 5555

# Get device IP

adb shell ip route | awk '{print $9}'

# Connect

mobilerun connect <IP>:5555

# Verify

mobilerun ping --tcp
```

--------------------------------

### Create App Card Directory and Files

Source: https://github.com/droidrun/mobilerun/blob/main/docs/features/app-cards.mdx

These commands set up the necessary directory and placeholder files for creating custom app cards.

```bash
mkdir -p config/app_cards
touch config/app_cards/app_cards.json
touch config/app_cards/chrome.md
```

--------------------------------

### Test Mobilerun Connection

Source: https://github.com/droidrun/mobilerun/blob/main/docs/quickstart.mdx

Verify that Mobilerun can successfully communicate with your Android device after setup. A success message indicates the Portal is installed and accessible.

```bash
mobilerun ping
```

--------------------------------

### Get Apps with AndroidDriver

Source: https://github.com/droidrun/mobilerun/blob/main/docs/sdk/adb-tools.mdx

Returns a list of installed applications, including their package name and label. System apps are included by default. Set `include_system` to False to exclude them.

```python
async def get_apps(include_system: bool = True) -> List[Dict[str, str]]
```

--------------------------------

### Initialize MobileAgent with Default Config

Source: https://github.com/droidrun/mobilerun/blob/main/docs/sdk/droid-agent.mdx

Demonstrates the basic initialization pattern for MobileAgent using default configuration. LLMs are loaded from config.llm_profiles.

```python
from mobilerun import MobileAgent
from mobilerun.config_manager import MobileConfig

# Initialize with default config
config = MobileConfig()

# Create agent (LLMs loaded from config.llm_profiles)
agent = MobileAgent(
    goal="Open Chrome and search for Mobilerun",
    config=config
)

# Run agent
result = await agent.run()
```

--------------------------------

### Minimal MobileAgent Initialization

Source: https://github.com/droidrun/mobilerun/blob/main/docs/sdk/configuration.mdx

Demonstrates the quickest way to initialize MobileAgent using default settings. Also shows how to load configuration from a YAML file.

```python
from mobilerun import MobileAgent, MobileConfig

# Minimal (uses defaults)
agent = MobileAgent(goal="Open settings")
result = await agent.run()

# Load from config.yaml
config = MobileConfig.from_yaml("config.yaml")
agent = MobileAgent(goal="Open settings", config=config)
result = await agent.run()
```

--------------------------------

### Mobilerun Agent Configuration

Source: https://github.com/droidrun/mobilerun/blob/main/docs/concepts/architecture.mdx

Example YAML configuration for Mobilerun, specifying LLM profiles for different agents (manager, executor, fast_agent) and global/agent-specific runtime settings like reasoning mode, max steps, and vision capabilities.

```yaml
llm_profiles:
  manager:
    provider: Anthropic
    model: claude-sonnet-4
  executor:
    provider: OpenAI
    model: gpt-4o
  fast_agent:
    provider: GoogleGenAI
    model: gemini-3.1-flash-lite
agent:
  reasoning: true       # Enable Manager/Executor workflow
  max_steps: 15         # Maximum execution steps (global)
  manager:
    vision: true        # Send screenshots to Manager
  executor:
    vision: true        # Send screenshots to Executor
  fast_agent:
    vision: false
    parallel_tools: true
```

--------------------------------

### Install Mobilerun for CLI and Python Integration

Source: https://github.com/droidrun/mobilerun/blob/main/docs/quickstart.mdx

Install Mobilerun for both CLI usage and integration within Python projects. This command installs the package into your current Python environment.

```bash
uv pip install mobilerun
```

--------------------------------

### Execute a Simple Command

Source: https://github.com/droidrun/mobilerun/blob/main/docs/guides/cli.mdx

Use the 'run' command to execute a single, straightforward instruction on the device.

```bash
# Simple command
mobilerun run "Open Settings"
```

--------------------------------

### List Available Simulators

Source: https://github.com/droidrun/mobilerun/blob/main/docs/guides/device-setup.mdx

List all available iOS simulators using `xcrun simctl list devices available` before running the portal on a simulator.

```bash
# List available simulators
xcrun simctl list devices available
```

--------------------------------

### Troubleshoot: No devices found

Source: https://github.com/droidrun/mobilerun/blob/main/docs/guides/cli.mdx

Steps to check ADB connection, authorize devices, and restart the ADB server if no devices are found.

```bash
# Check ADB
adb devices

# If unauthorized: Accept prompt on device
# If not listed: Try different USB port/cable
# Restart ADB
adb kill-server && adb start-server
```

--------------------------------

### MobileAgent Initialization

Source: https://github.com/droidrun/mobilerun/blob/main/docs/sdk/droid-agent.mdx

Demonstrates how to initialize the MobileAgent with various configurations, including default settings, loading from YAML, custom LLMs, and single LLM instances.

```APIDOC
## MobileAgent

### Description
Initializes the MobileAgent wrapper, which coordinates between agents to achieve a user's goal.

### Method
__init__

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
**Basic initialization pattern (recommended):**
```python
from mobilerun import MobileAgent
from mobilerun.config_manager import MobileConfig

# Initialize with default config
config = MobileConfig()

# Create agent (LLMs loaded from config.llm_profiles)
agent = MobileAgent(
    goal="Open Chrome and search for Mobilerun",
    config=config
)

# Run agent
result = await agent.run()
```

**Loading from YAML (optional):**
```python
from mobilerun import MobileAgent
from mobilerun.config_manager import MobileConfig

# Load config from config.yaml
config = MobileConfig.from_yaml("config.yaml")

# Create agent (LLMs loaded from config.llm_profiles)
agent = MobileAgent(
    goal="Open Chrome and search for Mobilerun",
    config=config
)

# Run agent
result = await agent.run()
```

**Custom LLM dictionary pattern:**
```python
from mobilerun import MobileAgent
from mobilerun.config_manager import MobileConfig
from llama_index.llms.openai import OpenAI
from llama_index.llms.anthropic import Anthropic

# Initialize config
config = MobileConfig()

# Create custom LLMs
llms = {
    "manager": Anthropic(model="claude-sonnet-4-5-latest", temperature=0.2),
    "executor": Anthropic(model="claude-sonnet-4-5-latest", temperature=0.1),
    "fast_agent": OpenAI(model="gpt-4o", temperature=0.2),
    "app_opener": OpenAI(model="gpt-4o-mini", temperature=0.0),
    "structured_output": OpenAI(model="gpt-4o-mini", temperature=0.0),
}

# Create agent with custom LLMs
agent = MobileAgent(
    goal="Send a message to John",
    llms=llms,
    config=config
)

result = await agent.run()
```

**Single LLM pattern:**
```python
from mobilerun import MobileAgent
from mobilerun.config_manager import MobileConfig
from llama_index.llms.openai import OpenAI

# Initialize config
config = MobileConfig()

# Create agent with a single LLM instance
agent = MobileAgent(
    goal="Navigate to the nearest coffee shop",
    llms=OpenAI(model="gpt-4o", temperature=0.3),
    config=config
)

result = await agent.run()
```

### Response
#### Success Response (200)
None

#### Response Example
None
```

--------------------------------

### Reinstall Mobilerun Portal

Source: https://github.com/droidrun/mobilerun/blob/main/docs/guides/device-setup.mdx

If the Mobilerun portal is not installed, use this command to reinstall it. Verify the installation by checking the package list.

```bash
mobilerun setup
```

```bash
adb shell pm list packages | grep mobilerun
```

--------------------------------

### Run Safety Scan

Source: https://github.com/droidrun/mobilerun/blob/main/CONTRIBUTING.md

Use Safety to check your installed project dependencies against a database of known security vulnerabilities. Ensure Safety is installed.

```bash
safety scan
```

--------------------------------

### Install App with AndroidDriver

Source: https://github.com/droidrun/mobilerun/blob/main/docs/sdk/adb-tools.mdx

Installs an APK file onto the device. You can choose to reinstall if the app already exists and automatically grant all permissions. The default for granting permissions is True.

```python
async def install_app(path: str, **kwargs) -> str
```

```python
result = await driver.install_app("/path/to/app.apk")
```

```python
result = await driver.install_app("/path/to/app.apk", reinstall=True)
```

--------------------------------

### Initialize MobileAgent with YAML Credentials

Source: https://github.com/droidrun/mobilerun/blob/main/docs/features/credentials.mdx

Load the configuration from a YAML file, which includes credential settings, and then initialize the MobileAgent. Credentials will be automatically loaded.

```python
from mobilerun import MobileAgent, MobileConfig

# Config loads credentials from file
config = MobileConfig.from_yaml("config.yaml")

agent = MobileAgent(
    goal="Login to Gmail",
    config=config  # Credentials loaded automatically
)
```

--------------------------------

### Initialize MobileAgent from YAML Config

Source: https://github.com/droidrun/mobilerun/blob/main/docs/sdk/droid-agent.mdx

Shows how to initialize MobileAgent by loading configuration from a YAML file. LLMs are loaded from config.llm_profiles.

```python
from mobilerun import MobileAgent
from mobilerun.config_manager import MobileConfig

# Load config from config.yaml
config = MobileConfig.from_yaml("config.yaml")

# Create agent (LLMs loaded from config.llm_profiles)
agent = MobileAgent(
    goal="Open Chrome and search for Mobilerun",
    config=config
)

# Run agent
result = await agent.run()
```

--------------------------------

### Configuration Data with Variables

Source: https://github.com/droidrun/mobilerun/blob/main/docs/features/custom-variables.mdx

Demonstrates using variables to pass configuration data, such as API endpoints and timeouts, to an agent. This allows for flexible and dynamic configuration of agent behavior.

```python
variables = {
    "api_endpoint": "https://api.example.com/v2",
    "timeout": 30
}

agent = MobileAgent(
    goal="Call API endpoint",
    config=config,
    variables=variables,
    prompts=custom_prompts
)
```

--------------------------------

### Initialize MobileAgent with Single LLM

Source: https://github.com/droidrun/mobilerun/blob/main/docs/sdk/droid-agent.mdx

Demonstrates initializing MobileAgent using a single LLM instance that will be used across all agents. This is a simpler configuration when specific LLMs for each role are not required.

```python
from mobilerun import MobileAgent
from mobilerun.config_manager import MobileConfig
from llama_index.llms.openai import OpenAI

# Initialize config
config = MobileConfig()

```

--------------------------------

### Get Date on iOS

Source: https://github.com/droidrun/mobilerun/blob/main/docs/sdk/ios-tools.mdx

Fetches the current date and time from the iOS device.

```python
async def get_date() -> str
```

--------------------------------

### AndroidDriver.list_packages

Source: https://github.com/droidrun/mobilerun/blob/main/docs/sdk/adb-tools.mdx

Retrieves a list of installed package names on the device. Optionally includes system applications.

```APIDOC
## AndroidDriver.list_packages

### Description
Return installed package names.

### Method
`async def list_packages(include_system: bool = False) -> List[str]`

### Parameters
#### Query Parameters
- **include_system** (bool) - Optional - Whether to include system apps (default: False)

### Returns
- `List[str]` - List of package names
```

--------------------------------

### Initialize MobileAgent with Custom LLM Dictionary

Source: https://github.com/droidrun/mobilerun/blob/main/docs/sdk/droid-agent.mdx

Illustrates initializing MobileAgent with a custom dictionary of LLMs for different agent roles. This allows fine-grained control over the language models used.

```python
from mobilerun import MobileAgent
from mobilerun.config_manager import MobileConfig
from llama_index.llms.openai import OpenAI
from llama_index.llms.anthropic import Anthropic

# Initialize config
config = MobileConfig()

# Create custom LLMs
llms = {
    "manager": Anthropic(model="claude-sonnet-4-5-latest", temperature=0.2),
    "executor": Anthropic(model="claude-sonnet-4-5-latest", temperature=0.1),
    "fast_agent": OpenAI(model="gpt-4o", temperature=0.2),
    "app_opener": OpenAI(model="gpt-4o-mini", temperature=0.0),
    "structured_output": OpenAI(model="gpt-4o-mini", temperature=0.0),
}

# Create agent with custom LLMs
agent = MobileAgent(
    goal="Send a message to John",
    llms=llms,
    config=config
)

result = await agent.run()
```

--------------------------------

### AdbDevice Get Window Size

Source: https://github.com/droidrun/mobilerun/blob/main/mobilerun/agent/external/README.md

Retrieves the current screen dimensions (width and height) of the device.

```python
# Screen size
w, h = await device.window_size()
```

--------------------------------

### Run Quick Test with GoogleGenAI

Source: https://github.com/droidrun/mobilerun/blob/main/docs/guides/cli.mdx

Execute a quick test command using the GoogleGenAI provider and a specific model.

```bash
mobilerun run "Turn on dark mode" \
  --provider GoogleGenAI \
  --model gemini-3.1-flash-lite
```

--------------------------------

### DeviceDriver Lifecycle Methods

Source: https://github.com/droidrun/mobilerun/blob/main/docs/sdk/base-tools.mdx

Methods for establishing and ensuring a connection to the device. Use `connect()` to initiate the connection and `ensure_connected()` to verify it.

```python
connect() -> None
ensure_connected() -> None
```

--------------------------------

### AndroidDriver.get_apps

Source: https://github.com/droidrun/mobilerun/blob/main/docs/sdk/adb-tools.mdx

Fetches a list of installed applications, including their package names and labels. System apps can be included or excluded.

```APIDOC
## AndroidDriver.get_apps

### Description
Return installed apps as list of dicts with 'package' and 'label' keys.

### Method
`async def get_apps(include_system: bool = True) -> List[Dict[str, str]]`

### Parameters
#### Query Parameters
- **include_system** (bool) - Optional - Whether to include system apps (default: True)

### Returns
- `List[Dict[str, str]]` - List of dictionaries containing 'package' and 'label' keys
```

--------------------------------

### Initialize MobileAgent with Custom Device Configuration

Source: https://github.com/droidrun/mobilerun/blob/main/docs/sdk/droid-agent.mdx

Demonstrates how to initialize MobileAgent with a specific device configuration, including serial number and TCP usage. This is useful for targeting specific emulators or devices.

```python
from mobilerun import MobileAgent, DeviceConfig
from mobilerun.config_manager import MobileConfig

# Initialize config with device settings
device_config = DeviceConfig(serial="emulator-5554", use_tcp=True)
config = MobileConfig(device=device_config)

agent = MobileAgent(
    goal="Open settings",
    config=config,
)

result = await agent.run()

```

--------------------------------

### AndroidDriver.install_app

Source: https://github.com/droidrun/mobilerun/blob/main/docs/sdk/adb-tools.mdx

Installs an APK file onto the Android device. Supports options for reinstallation and automatic permission granting.

```APIDOC
## AndroidDriver.install_app

### Description
Installs an APK on the device.

### Method
`async def install_app(path: str, **kwargs) -> str`

### Parameters
#### Path Parameters
- **path** (str) - Required - Path to the APK file on the local machine

#### Query Parameters
- **reinstall** (bool) - Optional - Whether to reinstall if app already exists (default: False)
- **grant_permissions** (bool) - Optional - Whether to grant all permissions automatically (default: True)

### Returns
- `str` - Result message indicating success or error

### Usage:
```python
result = await driver.install_app("/path/to/app.apk")
result = await driver.install_app("/path/to/app.apk", reinstall=True)
```
```

--------------------------------

### Get Device Date and Time with AndroidDriver

Source: https://github.com/droidrun/mobilerun/blob/main/docs/sdk/adb-tools.mdx

Retrieve the current date and time from the Android device as a formatted string.

```python
async def get_date() -> str:
    # ... implementation details ...
    pass

date = await driver.get_date()
print(f"Device date: {date}")
# Output: "Thu Jan 16 14:30:25 UTC 2025"
```

--------------------------------

### Initialize MobileAgent with Custom Tools and Credentials

Source: https://github.com/droidrun/mobilerun/blob/main/docs/sdk/droid-agent.mdx

Configure MobileAgent with custom tools and direct credentials. The custom_tools dictionary maps tool names to their parameters, descriptions, and functions, while credentials provide necessary authentication details.

```python
from mobilerun import MobileAgent
from mobilerun.config_manager import MobileConfig

# Initialize config
config = MobileConfig()

# Define custom tool
def search_database(query: str) -> str:
    """Search the local database."""
    # Your implementation
    return f"Results for: {query}"

custom_tools = {
    "search_database": {
        "parameters": {
            "query": {"type": "string", "required": True},
        },
        "description": "Search the local database for information",
        "function": search_database
    }
}

# Provide credentials directly
credentials = {
    "GMAIL_USERNAME": "user@gmail.com",
    "GMAIL_PASSWORD": "secret123"
}

agent = MobileAgent(
    goal="Search database and email results",
    config=config,
    custom_tools=custom_tools,
    credentials=credentials
)

result = await agent.run()
```

--------------------------------

### Configure MobileAgent Goal

Source: https://github.com/droidrun/mobilerun/blob/main/docs/features/structured-output.mdx

Set the `goal` for the `MobileAgent` to guide data collection, specifying the desired information to be extracted.

```python
agent = MobileAgent(
    goal="Find contact and get their phone number, email, and full name",
    config=config,
    output_model=ContactInfo,
)
```

--------------------------------

### Clone iOS Portal Repository

Source: https://github.com/droidrun/mobilerun/blob/main/docs/guides/device-setup.mdx

Clone the iOS Portal repository and navigate into the directory. This is the first step to setting up the iOS Portal.

```bash
git clone https://github.com/droidrun/ios-portal.git
cd ios-portal
```

--------------------------------

### AdbDevice Swipe Action

Source: https://github.com/droidrun/mobilerun/blob/main/mobilerun/agent/external/README.md

Shows how to perform a swipe gesture on the device screen. Specify start and end coordinates, and optionally duration.

```python
# Swipe
await device.swipe(100, 500, 100, 200, duration=0.3)
```

--------------------------------

### Configure Credentials with Python

Source: https://github.com/droidrun/mobilerun/blob/main/docs/sdk/configuration.mdx

Use CredentialsConfig to enable the credential manager and specify the path to the credentials file.

```python
from mobilerun import CredentialsConfig

CredentialsConfig(
    enabled=True,                        # Enable credential manager
    file_path="config/credentials.yaml",  # Path to credentials file
)
```

--------------------------------

### Agent Credentials using Config Format

Source: https://github.com/droidrun/mobilerun/blob/main/docs/sdk/configuration.mdx

Set up agent credentials by referencing an external configuration file. This is useful for managing sensitive information separately.

```python
from mobilerun import MobileConfig, CredentialsConfig

config = MobileConfig(
    credentials=CredentialsConfig(
        enabled=True,
        file_path="config/credentials.yaml"
    )
)

agent = MobileAgent(
    goal="...",
    config=config
)
```

--------------------------------

### Initialize MobileAgent with Custom Prompts

Source: https://github.com/droidrun/mobilerun/blob/main/docs/sdk/droid-agent.mdx

Demonstrates overriding default prompts with custom Jinja2 templates for different agent roles like fast_agent and manager. This allows for fine-tuning agent behavior and responses.

```python
from mobilerun import MobileAgent
from mobilerun.config_manager import MobileConfig

# Initialize config
config = MobileConfig()

# Override default prompts with custom Jinja2 templates
custom_prompts = {
    "fast_agent_system": "You are a specialized agent for {{ platform }} devices...",
    "manager_system": "You are a planning agent. Your goal: {{ instruction }}..."
}

agent = MobileAgent(
    goal="Complete specialized task",
    config=config,
    prompts=custom_prompts
)

result = await agent.run()

```

--------------------------------

### Mobilerun CLI Usage for iOS

Source: https://github.com/droidrun/mobilerun/blob/main/docs/guides/device-setup.mdx

Examples of using the Mobilerun CLI for iOS commands, showing both auto-discovery and explicit portal URL specification.

```bash
# Auto-discovers portal on port 6643
mobilerun run "your command" --ios

# Explicit portal URL
mobilerun run "your command" --ios --device http://127.0.0.1:6643
```

--------------------------------

### AdbDevice Get Current App Info

Source: https://github.com/droidrun/mobilerun/blob/main/mobilerun/agent/external/README.md

Retrieves information about the currently running application, including its package name, activity, and process ID.

```python
# Current app
info = await device.app_current()  # -> RunningAppInfo(package, activity, pid)
```

--------------------------------

### List Packages with AndroidDriver

Source: https://github.com/droidrun/mobilerun/blob/main/docs/sdk/adb-tools.mdx

Retrieves a list of installed package names on the device. By default, system apps are excluded. Set `include_system` to True to include them.

```python
async def list_packages(include_system: bool = False) -> List[str]
```