Open source · Mobile Harness
One prompt. Your coding agent runs real phones.
Portable operating instructions plus the mobilerun-core
Python API. Point Claude Code, Cursor, Codex or OpenClaw at any Android
or iPhone, local or cloud, and let it drive. Not another agent to run,
just the control surface yours was missing.
setup one prompt
control mobilerun-core (Python)
devices local + cloud
editors Claude Code · Cursor · Codex
The prompt
Paste this into your agent.
It clones the repo, reads install.md, installs the package,
and is ready to operate phones. No glue code to write.
prompt
Set up https://github.com/droidrun/mobile-harness for me. Read `install.md` and follow the steps to install `mobile-harness`.
Prefer to do it by hand? A venv and one install is the whole setup:
install
cd mobile-harness python -m venv .venv # Python 3.11, 3.12 or 3.13 .venv/bin/pip install "mobilerun-core[local]"
Where it fits
Three ways in. Pick the one that fits.
| Path | What it is | Use it when |
|---|---|---|
| Mobile Harness | Your coding agent drives any phone through the mobilerun-core Python API. | Drive a local or hosted phone from your editor |
| MCP server | A hosted HTTP endpoint that plugs cloud devices into your editor, zero install. | Hosted phones, nothing to set up |
| Framework | The open-source mobilerun agent that runs a full mobile agent locally. | You want the autonomous agent itself |
The API
One facade, every backend.
The same connect() call reaches a hosted phone or a local
one. Then real helpers: tap_text, scroll_until,
find_nodes, screenshot, start_app.
drive.py
from mobilerun_core import Mobilerun
m = Mobilerun(base_url="https://api.mobilerun.ai/v1") # key: MOBILERUN_CLOUD_API_KEY
device = m.connect("dev_...", backend="cloud") # or a local phone
device.start_app("com.android.settings")
device.tap_text("Battery")
device.screenshot() Backends
Any phone, same code.
| Backend | What it reaches | In connect() |
|---|---|---|
| Cloud | A hosted phone at api.mobilerun.ai, reached with your API key. | backend="cloud" |
| Local Android (ADB) | A phone plugged into your machine, driven over ADB. | backend="local-android-adb" |
| Local Android (Portal) | An Android device over an HTTP Portal when there is no ADB. | backend="local-android-http" |
| Local iOS (Portal) | A local iPhone reached through ios-portal. | backend="local-ios-http" |
Registers with your editor
- Claude Code: import
@AGENTS.mdinto your CLAUDE.md - Codex: symlink the repo into your skills folder
- OpenClaw: package it as a skill with SKILL.md as the entrypoint
- The harness routes the agent to the smallest file it needs, so it stays token-light
Safe by default
- Screen and app content is treated as untrusted data, never instructions
- Stops on credentials, payment or destructive consent
- Never prints tokens or API keys to logs, chat or screenshots
- Local, agent-owned memory and credentials stay out of git
FAQ
Mobile Harness, common questions.
Is Mobile Harness an agent?+
No. It is a compact set of operating instructions plus the mobilerun-core Python API that you hand to a coding agent you already use: Claude Code, Cursor, Codex or OpenClaw. Your agent is the brain, the harness is how it drives the phone. One connect() call reaches a hosted phone, a local Android over ADB or Portal, or a local iPhone.
What do I need, and how do I set it up?+
A coding agent that can read files and run shell, Python 3.11 to 3.13, and a device: a local phone over ADB or a Portal, or a cloud API key from cloud.mobilerun.ai. Paste the setup prompt into your coding agent. It clones the repo, reads install.md and installs mobilerun-core[local], or you install by hand with a venv and pip.
How is this different from the MCP server?+
The hosted MCP server is the zero-install HTTP path to hosted phones. Mobile Harness is local-first and code-native: a real Python control API that also reaches the cloud. The framework (pip install mobilerun, Python 3.11 to 3.13) is different again: a full autonomous agent that runs locally.
Related: the MCP server · the framework · mobilerun-core · devices
Point your agent at a phone.
One prompt sets it up. Drive a local device or a hosted phone from the editor you already use.