droidrun/mobile-harness

Mobile Harness – Portable control instructions for AI agents on Android & iOS

What it is – A lightweight, Markdown‑driven harness that lets a language‑model‑based AI agent talk to real Android or iOS devices. It is not an agent runtime; it provides the Python API (mobilerun_core) that the agent calls to perform UI actions, take screenshots, launch apps, etc. The harness works with local devices (via ADB or a Portal HTTP server) and with cloud‑hosted devices through the Mobilerun cloud service.

Key capabilities

• Connect to a device with a single call:

  from mobilerun_core import Mobilerun
  m = Mobilerun()
  dev = m.connect("<id>", backend="cloud")
  

• Unified API for Android and iOS: ui(), screenshot(), start_app(), tap_node(), type(), scroll(), etc.
• Helper methods that work on the accessibility tree (find_nodes, tap_text, scroll_until).
• Automatic capability detection (device.capabilities, device.supports(...)).
• Optional cloud backend (requires MOBILERUN_CLOUD_API_KEY).
• Local back‑ends:
  • Android via ADB (with optional Portal HTTP for richer features).
  • Android Portal HTTP‑only.
  • iOS via the open‑source ios‑portal HTTP server.
• All state that an agent creates (memory, credentials, custom app cards) lives under a git‑ignored local/ folder, keeping user data separate from the repository.

Benchmarks – Evaluated on the public AndroidWorld (116 tasks) and iOSWorld (133 tasks) suites using a standard coding agent with a GPT‑6‑style model. Results: 100 % mean score on Android, 98.24 % mean score on iOS, with binary pass rates of 100 % and 93.23 % respectively. Detailed task replays and methodology are linked in the README.

Installation

1. Clone the repo.
2. Create a Python virtual environment (Python 3.11‑3.13) and install the core library:

   python -m venv .venv
   .venv/bin/pip install "mobilerun-core[local]"
   .venv/bin/python -c "from mobilerun_core import Mobilerun"
   

3. Follow install.md for platform‑specific setup (ADB, Portal servers, cloud API key, etc.).

How an AI agent uses it – The README provides a ready‑to‑paste Agent Setup Prompt that tells the agent to clone the repo and run the install steps. Once the environment is ready, the agent can import Mobilerun, connect to a device, query capabilities, and invoke UI actions directly from its generated code.

Distribution – The harness can be added to an agent as a skill via the skills.sh CLI (npx skills add droidrun/mobile-harness) or as a Claude Code plugin (/plugin marketplace add droidrun/mobile-harness). Both methods install the same Python package and keep the local/ data directory in the appropriate runtime location.

Who it’s for – Researchers and developers building LLM‑driven mobile‑automation agents, especially those who need a consistent, language‑model‑friendly API for both Android and iOS, whether the devices run locally or in the cloud.