Device Setup

Overview

Portal is recommended for local Android control; ADB-only control is also supported. Local iOS uses mobilerun-ios with WebDriverAgent.

Android Setup
iOS Setup

Prerequisites

Portal requires Android 8.0 (API 26) or newer. ADB-only setup requires ADB and UIAutomator.

Install ADB

macOS: brew install android-platform-toolsLinux: sudo apt install adbWindows: Download from Android Developer SiteVerify: adb version

Enable USB Debugging

Go to Settings > About phone
Tap Build number 7 times (enables Developer options)
Go to Settings > Developer options
Enable USB debugging
Connect device and tap Always allow

Verify: adb devices

Install Portal App (Recommended)

# Automatic setup (downloads compatible Portal APK)
mobilerun setup

# Or specify device
mobilerun setup --device SERIAL_NUMBER

This command:

Downloads the compatible Portal APK
Installs or upgrades the APK and grants the Android permissions allowed during installation
Enables its accessibility service or opens Android Settings for approval

Open Portal once and grant Display over other apps. Grant notification permission, Notification Access, screen-capture consent, and Install unknown apps only when your tasks need those features.To run without Portal, skip this step and set device.portal_mode: disabled in the framework configuration.

Verify Setup

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

mobilerun ping checks Portal. For ADB-only setup, use adb devices -l or adb -s SERIAL get-state.

Portal App

The Mobilerun Portal (com.mobilerun.portal) provides:

Accessibility Tree - Extracts UI elements and their properties
Device State - Tracks current activity, keyboard visibility
Action Execution - Tap, swipe, text input, and other actions
Local Control - HTTP, WebSocket, and ADB interfaces
Cloud Connection - Optional remote control and screen streaming
Events and Triggers - Optional device events and trigger rules

Keep Cloud Connection off for local Framework control. When enabled, Portal connects to the configured server and can send device state, actions, events, and screen-sharing data.For advanced APIs, see the Portal documentation: Local API, Reverse Connection, WebSocket Events, and Triggers and Events.

Communication Modes

ADB-only mode

How it works:

Tap, swipe, buttons, app lifecycle, packages, install/uninstall, screenshots, and date use ADB.
UI state comes from UIAutomator.
Text uses Android’s ADB input command and is limited to printable ASCII; Portal is needed for reliable Unicode input.

Framework configuration:

device:
  platform: android
  portal_mode: disabled

portal_mode: disabled also bypasses the framework’s automatic Portal setup.

Portal over TCP

How it works:

Portal runs HTTP server on device port 8080
ADB forwards local port → device port 8080
Mobilerun sends authenticated HTTP requests to localhost:PORT
In auto mode, Mobilerun uses the ContentProvider or ADB if HTTP is unavailable

Enable:

# CLI
mobilerun run "your command" --tcp

# Python
config = MobileConfig(device=DeviceConfig(serial="DEVICE_SERIAL", use_tcp=True))

Troubleshooting:

# Check port forwarding
adb forward --list

# Test Portal server
adb shell netstat -an | grep 8080

# Remove all forwards and retry
adb forward --remove-all
mobilerun ping --tcp

Portal ContentProvider mode

How it works:

Portal exposes content provider at content://com.mobilerun.portal/
Commands sent via ADB shell: content query --uri ...
JSON responses parsed from shell output
Authentication is handled through ADB

Usage:

# Default mode (no flag needed)
mobilerun ping

# Python
config = MobileConfig(device=DeviceConfig(serial="DEVICE_SERIAL", use_tcp=False))

Troubleshooting:

# Test content provider directly
adb shell content query --uri content://com.mobilerun.portal/state

# Should include: Row: 0 result=... and a successful JSON status

Portal policy (`portal_mode`)

from mobilerun import DeviceConfig, MobileConfig

config = MobileConfig(
    device=DeviceConfig(
        portal_mode="auto",      # auto | required | disabled
        auto_setup=True,
        use_tcp=False,
    )
)

Setting	Meaning
`auto`	Use Portal when available; otherwise use ADB.
`required`	Stop with an error if Portal or its keyboard is unavailable.
`disabled`	Use ADB only and skip Portal setup.

auto_setup=True installs or repairs Portal before connecting. Set it to False to skip that step.

Local HTTP and WebSocket authentication

Portal generates a bearer token for direct local HTTP and WebSocket clients. Copy it from the Portal main screen or retrieve it over ADB:

adb shell content query --uri content://com.mobilerun.portal/auth_token

Mobilerun handles Portal authentication automatically. Direct WebSocket clients and HTTP calls other than GET /ping must use the token shown in Portal or retrieved through ADB.

Advanced Setup

Wireless Debugging (Android 11+)

Setup

Enable Wireless Debugging

Settings > Developer options > Wireless debugging
Note the IP address and debugging port shown on the main Wireless debugging screen (for example, 192.168.1.100:37757)

Pair Device (First Time)

Pairing Code Method:

Tap Pair device with pairing code
Note the pairing code and the pairing-specific IP:port shown in that dialog
Run adb pair IP:PAIRING_PORT
Enter pairing code

Android Studio can alternatively pair by scanning the device’s QR code. The adb pair CLI expects an address/port and pairing code, not the QR payload.

Connect

adb connect IP:PORT
adb -s IP:PORT get-state

# Optional: validate Portal as well
mobilerun ping --device IP:PORT

Common Issues

Connection refused → Check same WiFi network and firewall
Frequent drops → Use 5GHz WiFi or stay near router
Can’t find IP → Run adb shell ip addr show wlan0 | grep "inet " via USB

Wireless Debugging (Android 10 and Below)

Enable TCP/IP Mode (USB Required)

# Connect via USB first
adb tcpip 5555

Find Device IP

adb shell ip addr show wlan0 | grep inet

Connect Wirelessly

# Disconnect USB cable
adb connect DEVICE_IP:5555
adb -s DEVICE_IP:5555 get-state

# Optional: validate Portal as well
mobilerun ping --device DEVICE_IP:5555

Multiple Devices

List Devices

mobilerun devices
# Found 2 connected device(s):
#   • emulator-5554
#   • 192.168.1.100:5555

Target Specific Device

# CLI
mobilerun run "your command" --device emulator-5554

# Python
config = MobileConfig(device=DeviceConfig(serial="emulator-5554"))
agent = MobileAgent(goal="your task", config=config)

Parallel Control

import asyncio
from mobilerun import DeviceConfig, MobileConfig, MobileAgent
from async_adbutils import adb

async def control_device(serial: str, command: str):
    device_config = DeviceConfig(serial=serial)
    config = MobileConfig(device=device_config)
    agent = MobileAgent(goal=command, config=config)
    return await agent.run()

async def main():
    devices = await adb.list()

    tasks = [
        control_device(devices[0].serial, "Open settings"),
        control_device(devices[1].serial, "Check battery"),
    ]

    results = await asyncio.gather(*tasks)
    print(results)

asyncio.run(main())

Troubleshooting

Device not found

Symptoms: adb devices shows no devices or unauthorizedSolutions:

Unplug/replug USB cable, try different port
Revoke USB debugging authorizations (Developer options)
Reconnect and tap “Always allow”
Restart ADB: adb kill-server && adb start-server
Windows: Install Google USB Driver

Portal not installed

Symptoms: mobilerun ping fails with “Portal is not installed”Solutions:

Reinstall: mobilerun setup
Check: adb shell pm list packages | grep mobilerun
Verify APK architecture matches device (arm64-v8a for most devices)
If Portal is intentionally not used, set device.portal_mode: disabled and validate ADB with adb devices -l instead of mobilerun ping

Accessibility service not enabled

Symptoms: mobilerun ping fails with “accessibility service not enabled”Solutions:

Auto-enable:

adb shell settings put secure enabled_accessibility_services \
  com.mobilerun.portal/com.mobilerun.portal.service.MobilerunAccessibilityService
adb shell settings put secure accessibility_enabled 1

Manual: Settings > Accessibility > Mobilerun Portal > Toggle ON

Verify:

adb shell settings get secure enabled_accessibility_services
# Should contain: com.mobilerun.portal/...

Text input not working

Symptoms: input_text() fails or types gibberishSolutions:

When Portal is available, Mobilerun tries to enable the Portal keyboard when it connects:

# Verify
adb shell settings get secure default_input_method
# Should show: com.mobilerun.portal/.input.MobilerunKeyboardIME

Manual switch: Long press space bar → Select “Mobilerun Keyboard”
Focus the element first (tap it), then input text
In ADB-only mode, use printable ASCII; Unicode, control characters, and literal %s are rejected

Empty UI state

Symptoms: get_ui_tree() or the formatted agent state is empty or incompleteSolutions:

With Portal enabled, verify its accessibility path with mobilerun ping
In ADB-only mode, inspect adb shell uiautomator dump /dev/tty
Some apps expose incomplete trees (WebViews, games, and custom-rendered UI)
Wait for the UI to settle after a tap or swipe, then request fresh state
With Portal enabled and overlay permission granted, use its overlay for visual debugging

This guide describes mobilerun-ios --local on ports 8080–8089. See iOS Driver for the driver API.

Prerequisites

macOS with Xcode installed
Apple ID with signing capability (a personal team is sufficient)
iPhone with Developer Mode enabled
USB data cable to connect the iPhone to your Mac
Mobilerun WebDriverAgent installed and signed on the iPhone (see the Connect an iPhone guide)
mobilerun-ios installed on your Mac

Enable Developer Mode on your device

Go to Settings > Privacy & Security > Developer Mode
Toggle Developer Mode on
Restart the device when prompted
After restart, confirm the prompt to enable Developer Mode

For the complete device preparation and WebDriverAgent signing instructions, follow the Connect an iPhone guide. You only need to complete the device, WebDriverAgent, and mobilerun-ios installation steps; logging in is not required for local mode.

Install and Run `mobilerun-ios`

mobilerun-ios --local connects to WebDriverAgent over USB and exposes the device API on your Mac. The framework discovers that API automatically.

Install the CLI

Choose either Homebrew or the installation script:

brew install droidrun/tap/mobilerun-ios

curl -fsSL https://github.com/droidrun/mobilerun-ios-releases/releases/latest/download/install.sh | sh

Verify the installation:

mobilerun-ios --version

Find the iPhone UDID

Connect and unlock the iPhone, accept the Trust This Computer prompt, then run:

mobilerun-ios list

Copy the UDID shown for the iPhone you want to control.

Start local mode

mobilerun-ios --local <udid>

Keep this command running. By default, it serves the device API at http://127.0.0.1:8080.

Verify the connection

curl http://127.0.0.1:8080/ping

The response should contain "result":"pong". Then test the framework:

mobilerun run "Take a screenshot" --ios

To select the server explicitly, pass its URL:

mobilerun run "Take a screenshot" --ios --device http://127.0.0.1:8080

When several iPhones are attached, ports advance per device (8080, 8081, and so on). Each device URL is printed when mobilerun-ios starts. Framework auto-discovery scans ports 8080 through 8089.

Loopback local mode does not require authentication. If you bind to a non-loopback address, mobilerun-ios requires --local-token. Set the same token in MOBILERUN_DEVICE_TOKEN or device.auth_token in the framework configuration.

How iOS Connects

The iOS local driver connects differently from Android:

Feature	Android	iOS
Communication	ADB alone, or ADB + Portal HTTP/ContentProvider	Local HTTP API (port 8080 by default)
Device bridge	ADB; optional Portal APK	`mobilerun-ios` backed by WebDriverAgent
Setup tool	Optional `mobilerun setup`	`mobilerun-ios --local <udid>`
Accessibility	Portal Accessibility API or ADB UIAutomator	WebDriverAgent / XCUITest
Text Input	Portal keyboard or printable-ASCII ADB input	Direct XCUITest text input
Connection	ADB over USB/TCP	USB through `mobilerun-ios`

mobilerun-ios uses WebDriverAgent to read the screen, perform actions, manage apps, and take screenshots. The Framework connects to its local server automatically.

Usage

CLI

# Auto-discovers mobilerun-ios on ports 8080-8089
mobilerun run "your command" --ios

# Explicit local server URL
mobilerun run "your command" --ios --device http://127.0.0.1:8080

Python API

from mobilerun import MobileAgent, MobileConfig, DeviceConfig

config = MobileConfig(
    device=DeviceConfig(
        platform="ios",
        serial="http://127.0.0.1:8080",  # optional, auto-discovered if omitted
    )
)

agent = MobileAgent(
    goal="Open Settings and check WiFi",
    config=config
)

result = await agent.run()

Supported Features

Feature	Status	Notes
`tap()`	✅
`swipe()`	✅
`input_text()`	✅
`screenshot()`	✅
`get_ui_tree()`	✅	Accessibility tree and device state
`start_app()`	✅	By bundle identifier
`stop_app()`	✅	By bundle identifier
`get_apps()`	✅	Includes system-app filtering
`get_date()`	✅
`press_button()`	✅	`home`, `back`, `enter`, `delete`, and `app_switch`
`drag()`	❌
`install_app()`	✅	From a path on the Mac or a URL
`uninstall_app()`	❌	Not supported

Troubleshooting

`mobilerun-ios list` shows no devices

Symptoms: The connected iPhone does not appear in the device listSolutions:

Unlock the iPhone and accept the Trust This Computer prompt
Confirm the USB cable supports data, not only charging
Open Xcode once with the device connected and verify it appears as a run destination

WebDriverAgent does not start

Symptoms: mobilerun-ios --local times out while waiting for WebDriverAgentSolutions:

Re-sign and build WebDriverAgentRunner in Xcode
Trust the developer certificate under Settings > General > VPN & Device Management
Keep the device unlocked and run mobilerun-ios --local <udid> again
Review the Connect an iPhone guide for the complete signing procedure

Local server not reachable

Symptoms: curl http://127.0.0.1:8080/ping times out or is refusedSolutions:

Confirm mobilerun-ios --local <udid> is still running
Check its startup output for the actual server URL
If another process uses port 8080, choose an available high port, for example: mobilerun-ios --local --local-addr 127.0.0.1:18080 <udid>
Test the printed URL with /ping. Because custom ports are not auto-discovered, pass it to the framework explicitly with --device http://127.0.0.1:18080

Framework auto-discovery fails

Symptoms: mobilerun run ... --ios cannot find the iPhoneSolutions:

Confirm the local server is on one of the automatically scanned ports, 8080 through 8089
Pass the URL explicitly: --device http://127.0.0.1:8080
Authenticated servers are not auto-discovered. Set MOBILERUN_DEVICE_TOKEN and pass the printed URL with --device.

Next Steps

Learn about the Agent System
Explore Configuration Options
Try Custom Tools
Implement Structured Output

Introduction

Features

Guides

Concepts

SDK Reference

Overview

Prerequisites

Portal App

Communication Modes

Portal policy (`portal_mode`)

Local HTTP and WebSocket authentication

Advanced Setup

Setup

Common Issues

List Devices

Target Specific Device

Parallel Control

Troubleshooting

Prerequisites

Enable Developer Mode on your device

Install and Run `mobilerun-ios`

How iOS Connects

Usage

CLI

Python API

Supported Features

Troubleshooting

Next Steps

​Overview

​Prerequisites

​Portal App

​Communication Modes

​Portal policy (portal_mode)

​Local HTTP and WebSocket authentication

​Advanced Setup

​Setup

​Common Issues

​List Devices

​Target Specific Device

​Parallel Control

​Troubleshooting

​Prerequisites

​Enable Developer Mode on your device

​Install and Run mobilerun-ios

​How iOS Connects

​Usage

​CLI

​Python API

​Supported Features

​Troubleshooting

​Next Steps

Overview

Prerequisites

Portal App

Communication Modes

Portal policy (`portal_mode`)

Local HTTP and WebSocket authentication

Advanced Setup

Setup

Common Issues

List Devices

Target Specific Device

Parallel Control

Troubleshooting

Prerequisites

Enable Developer Mode on your device

Install and Run `mobilerun-ios`

How iOS Connects

Usage

CLI

Python API

Supported Features

Troubleshooting

Next Steps