> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mobilerun.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Mobile Harness · Coding Agents

> Connect Claude Code, Codex, or another coding agent to Android and iOS devices with the mobile-harness skill — local ADB, Portal, and Android Phones.

The **mobile-harness skill** connects a coding agent — Claude Code, Codex, or any runtime that can read Markdown and run Python — directly to Android and iOS devices. It is a compact Markdown harness, not an agent runtime: a set of operating instructions that teach the agent to control devices through the `mobilerun_core` Python package.

Once installed, the agent can drive local devices (ADB, [Mobilerun Portal](/guides/connect-android), iOS Simulator via [iOS Portal](/guides/connect-iphone)) and Mobilerun Android Phones from the same API.

<Note>
  This skill is for **coding agents** that can execute Python. For the OpenClaw agent CLI, use the [OpenClaw · Android control](/skills/openclaw) skill. For chat with the virtual assistant, use the [Mobilerun Assistant](/skills/assistant) skill.
</Note>

## Install

The fastest way is to paste this prompt into your agent:

```text theme={null}
Set up https://github.com/droidrun/mobile-harness for me.

Read `install.md` and follow the steps to install `mobile-harness`.
```

The agent clones the repository, creates a Python virtual environment, installs `mobilerun-core[local]`, and registers the harness with its own runtime (Codex skill directory, Claude Code `CLAUDE.md` import, or an OpenClaw skill package).

You can also install it as a skill with the [skills CLI](https://skills.sh):

```bash theme={null}
npx skills add droidrun/mobile-harness
```

First use still requires the Python setup from the repository's `install.md`. Python 3.11, 3.12, or 3.13 is required.

## What it enables

The harness gives the agent one Python facade for every device type:

```python theme={null}
from mobilerun_core import Mobilerun

m = Mobilerun()

# Android Phone
device = m.connect("<cloud-device-id>", backend="cloud")

# Local Android over ADB (uses Portal features when available)
device = m.connect("R5CT123456", backend="local-android-adb")

# Local iOS Portal
device = m.connect(backend="local-ios-http", url="http://127.0.0.1:6643")

device.ui()
device.screenshot()
device.start_app("com.android.settings")
```

After connecting, the agent inspects `device.capabilities` and gates optional operations with `device.supports(...)`.

## Supported backends

| Backend              | Target                             | Requirements                                                            |
| -------------------- | ---------------------------------- | ----------------------------------------------------------------------- |
| `cloud`              | Mobilerun Android Phones           | `MOBILERUN_CLOUD_API_KEY` set to your `dr_sk_...` key                   |
| `local-android-adb`  | Local Android device               | ADB access; Portal features used automatically when available           |
| `local-android-http` | Local Android via Portal HTTP only | Portal base URL and bearer token                                        |
| `local-ios-http`     | Local iOS device or Simulator      | A reachable [iOS Portal](https://github.com/droidrun/ios-portal) server |

## Configuration

Cloud devices need your API key from the [API Keys](/api-keys) page:

```bash theme={null}
export MOBILERUN_CLOUD_API_KEY="dr_sk_your_key_here"
export MOBILERUN_API_BASE_URL="https://api.mobilerun.ai/v1"
```

Local Portal HTTP-only modes take their connection details from environment variables:

```bash theme={null}
# Android Portal HTTP-only
export MOBILERUN_ANDROID_PORTAL_URL="http://127.0.0.1:18080"
export MOBILERUN_ANDROID_PORTAL_TOKEN="..."

# iOS Portal
export MOBILERUN_IOS_PORTAL_URL="http://127.0.0.1:6643"
```

## How the agent uses the harness

The harness routes the agent to the smallest file it needs:

* `AGENTS.md` (or `SKILL.md` in skill-based runtimes) is the entry point.
* Platform guides cover Android and iOS work, with separate recovery guides used only when control fails.
* App cards provide per-app instructions for the foreground app.
* Local `memory/` and `credentials/` folders hold agent-owned state and stay out of version control.

Installed clones keep themselves current: the agent runs `git pull --ff-only` (or `npx skills update`) once per session before device work.

## Next steps

<CardGroup cols={2}>
  <Card title="Agent Skills overview" icon="book" href="/skills/overview">
    Learn what Mobilerun skills are and how agents use them.
  </Card>

  <Card title="API Keys" icon="key" href="/api-keys">
    Create the key cloud devices need.
  </Card>

  <Card title="Connect an Android device" icon="mobile" href="/guides/connect-android">
    Set up the Mobilerun Portal app.
  </Card>

  <Card title="Connect an iPhone" icon="smartphone" href="/guides/connect-iphone">
    Set up iOS device control.
  </Card>
</CardGroup>