Device Setup

Overview

Mobilerun controls devices through a specialized Portal app that bridges your computer and the device.

Android Setup
iOS Setup (experimental)

Prerequisites

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

# Automatic setup (downloads compatible Portal APK)
mobilerun setup

# Or specify device
mobilerun setup --device SERIAL_NUMBER

This will:

Download the compatible Portal APK for your SDK version
Install with all permissions granted
Enable accessibility service automatically

Verify Setup

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

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
Dual Communication - TCP (faster) or Content Provider (fallback)

The Portal only communicates locally via ADB. No data is sent to external servers.

Communication Modes

TCP Mode (Recommended) - per operation

How it works:

Portal runs HTTP server on device port 8080
ADB forwards local port → device port 8080
Mobilerun sends HTTP requests to localhost:PORT

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

Content Provider (Fallback) - per operation

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

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 show: Row: 0 result={"data": "{...}"}

Advanced Setup

Wireless Debugging (Android 11+)

Setup

Enable Wireless Debugging

Settings > Developer options > Wireless debugging
Note IP address and port (e.g., 192.168.1.100:37757)

Pair Device (First Time)

QR Code Method:

adb pair <QR_CODE_STRING>

Pairing Code Method:

Tap Pair device with pairing code
Note pairing code and IP:port
Run: adb pair IP:PORT
Enter pairing code

Connect

adb connect IP:PORT
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
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)

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:

Keyboard auto-enabled by AndroidDriver initialization:

# 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

Empty UI state

Symptoms: get_state() returns empty or incomplete UI treeSolutions:

Verify accessibility: mobilerun ping
Some apps block accessibility services (WebViews, games, custom UI)
Wait for UI: time.sleep(1) after tap/swipe
Enable Portal overlay to see detected elements

iOS support is currently experimental. Functionality is limited compared to Android.

Prerequisites

macOS with Xcode 15+ installed (iOS Portal must be built from source)
Apple Developer account (free or paid — needed for code signing)
iOS device (iPhone or iPad) with Developer Mode enabled
USB cable to connect the device to your Mac (for initial build and deployment)
iproxy from libimobiledevice (for USB port forwarding)

Install `iproxy`

brew install libimobiledevice

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

Build and Install the iOS Portal

The iOS Portal is an Xcode project that runs as a UI test — it launches an HTTP server on port 6643 that Mobilerun communicates with.

Clone the iOS Portal repository

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

Open the project in Xcode

open mobilerun-ios-portal.xcodeproj

Configure code signing

You must change the signing team and bundle identifier to your own:

In Xcode, select the mobilerun-ios-portal project in the navigator
For each target (mobilerun-ios-portal, mobilerun-ios-portalUITests):
- Select the target
- Go to the Signing & Capabilities tab
- Set Team to your Apple Developer account
- Change the Bundle Identifier to something unique, e.g.:
  - com.yourname.mobilerun-ios-portal
  - com.yourname.mobilerun-ios-portalUITests
Let Xcode automatically manage provisioning profiles

You must change the bundle identifiers — the default ones are tied to the Mobilerun team’s signing certificate and will fail to build on your machine.

Select your device and run the test

Connect your iOS device via USB
In Xcode, select your device from the device dropdown (top bar)
If this is your first time deploying to the device, trust the developer certificate:
- On the device: Settings > General > VPN & Device Management > tap your developer profile > Trust
Run the portal using either method:

Option A — Xcode UI:

Go to Product > Test (or press Cmd + U)
This builds the app, installs it, and starts the “Mobilerun Server” UI test

Option B — Command line:

# Find your device ID
xcrun xctrace list devices

# Run the portal server
./device.sh YOUR_DEVICE_UDID

The HTTP server starts on port 6643 and keeps running until the test session ends.

Set up port forwarding with iproxy

The portal server runs on the device’s localhost. To reach it from your Mac, forward the port over USB:

iproxy 6643 6643

Keep this running in a separate terminal. The portal is now accessible at http://127.0.0.1:6643.

iproxy forwards over USB, so you don’t need WiFi connectivity between your Mac and the device.

Verify the connection

# Quick health check
curl http://127.0.0.1:6643/device/date

# Should return something like: {"date": "2026-03-31 10:30:00"}

Then test with Mobilerun:

mobilerun run "take a screenshot" --ios

Mobilerun will auto-discover the portal on port 6643. If it’s on a different port, pass the URL explicitly:

mobilerun run "take a screenshot" --ios --device http://127.0.0.1:6643

Running on the Simulator

You can also run the portal on the iOS Simulator (no code signing or physical device needed):

# List available simulators
xcrun simctl list devices available

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

The simulator portal is accessible at http://127.0.0.1:6643 directly (no iproxy needed).

Architecture

iOS Portal uses a different architecture than Android:

Feature	Android	iOS
Communication	ADB + TCP/Content Provider	HTTP server (port 6643)
Portal type	APK (auto-installed)	Xcode UI test (built from source)
Setup tool	`mobilerun setup`	Xcode build + `iproxy`
Accessibility	Android Accessibility API	iOS XCUITest framework
Text Input	Custom keyboard IME	Direct XCUITest text input
Connection	ADB over USB/TCP	USB via `iproxy` or WiFi

The iOS Portal leverages XCUITest to extract accessibility trees, perform gestures, and capture screenshots — all exposed through a REST API.

Usage

CLI

# 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

Python API

from mobilerun import MobileAgent, MobileConfig, DeviceConfig

config = MobileConfig(
    device=DeviceConfig(
        platform="ios",
        serial="http://127.0.0.1:6643",  # 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_state()`	✅	Accessibility tree extraction
`start_app()`	✅	By bundle identifier
`get_date()`	✅
`press_button()`	✅	`home` only
`drag()`	❌
`install_app()`	❌

Troubleshooting

Build fails with signing error

Symptoms: Xcode shows “Signing for target requires a development team”Solutions:

Make sure you changed the Team and Bundle Identifier for both targets
If using a free Apple Developer account, you may need to re-trust the certificate on the device every 7 days (Settings > General > VPN & Device Management)

Portal not reachable

Symptoms: curl http://127.0.0.1:6643/device/date times out or connection refusedSolutions:

Verify iproxy 6643 6643 is running
Check the Xcode test is still running (the portal stops when the test ends)
Re-run the test with Cmd + U in Xcode or ./device.sh UDID

Auto-discovery fails

Symptoms: mobilerun run ... --ios says “Could not find iOS portal”Solutions:

Auto-discovery scans ports 6643-6652. Make sure iproxy is forwarding to one of these.
Pass the URL explicitly: --device http://127.0.0.1:6643

Test session keeps stopping

Symptoms: The portal server stops after a few minutesSolutions:

Keep Xcode open and the test running — closing Xcode ends the test session
Disable auto-lock on the device (Settings > Display & Brightness > Auto-Lock > Never)
Keep the device plugged in to prevent sleep

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

Advanced Setup

Setup

Common Issues

List Devices

Target Specific Device

Parallel Control

Troubleshooting

Prerequisites

Install `iproxy`

Enable Developer Mode on your device

Build and Install the iOS Portal

Running on the Simulator

Architecture

Usage

CLI

Python API

Supported Features

Troubleshooting

Next Steps

​Overview

​Prerequisites

​Portal App

​Communication Modes

​Advanced Setup

​Setup

​Common Issues

​List Devices

​Target Specific Device

​Parallel Control

​Troubleshooting

​Prerequisites

​Install iproxy

​Enable Developer Mode on your device

​Build and Install the iOS Portal

​Running on the Simulator

​Architecture

​Usage

​CLI

​Python API

​Supported Features

​Troubleshooting

​Next Steps

Overview

Prerequisites

Portal App

Communication Modes

Advanced Setup

Setup

Common Issues

List Devices

Target Specific Device

Parallel Control

Troubleshooting

Prerequisites

Install `iproxy`

Enable Developer Mode on your device

Build and Install the iOS Portal

Running on the Simulator

Architecture

Usage

CLI

Python API

Supported Features

Troubleshooting

Next Steps