Droidrun Agent

PyPI version Python License: MIT

中文快速指南

Async Python client for the DroidRun Portal local API. Provides both HTTP and WebSocket clients to control Android devices through Portal's accessibility service.

Features

• HTTP Client (PortalHTTPClient) - Communicates with Portal's HTTP server (default port 8080)
• WebSocket Client (PortalWSClient) - Communicates with Portal's WebSocket server (default port 8081) using JSON-RPC style messages
• MCP Server - Exposes all Portal operations as MCP tools for AI agent integration (e.g. openclaw)
• Bearer token authentication
• Async context manager support (async with)
• Automatic reconnection for WebSocket client
• Full type hints

Installation

pip install droidrun-agent

To use the MCP server for AI agent integration:

pip install droidrun-agent[mcp]

Or install from source using uv:

git clone https://github.com/hanxi/droidrun-agent.git
cd droidrun-agent
uv sync              # core only
uv sync --extra mcp  # with MCP server support

Quick Start

HTTP Client

import asyncio
from droidrun_agent import PortalHTTPClient

async def main():
    async with PortalHTTPClient("http://192.168.1.100:8080", token="YOUR_TOKEN") as client:
        # Health check (no auth required)
        await client.ping()

        # Get device UI state
        state = await client.get_state_full()
        print(state)

        # Tap on screen coordinates
        await client.tap(200, 400)

        # Take a screenshot (returns PNG bytes)
        png_data = await client.take_screenshot()
        with open("screenshot.png", "wb") as f:
            f.write(png_data)

asyncio.run(main())

WebSocket Client

import asyncio
from droidrun_agent import PortalWSClient

async def main():
    async with PortalWSClient("ws://192.168.1.100:8081", token="YOUR_TOKEN") as ws:
        # Tap on screen coordinates
        await ws.tap(200, 400)

        # Get device state
        state = await ws.get_state()
        print(state)

        # Take a screenshot (returns PNG bytes)
        png_data = await ws.take_screenshot()
        with open("screenshot.png", "wb") as f:
            f.write(png_data)

        # Install APK from URL (WebSocket only)
        await ws.install(["https://example.com/app.apk"])

asyncio.run(main())

Documentation

For detailed API documentation of the DroidRun Portal local API, see:

• Local API Documentation

API Reference

PortalHTTPClient

Method	Description
ping()	Health check (no auth required)
get_a11y_tree()	Get simplified accessibility tree
get_a11y_tree_full(filter=True)	Get full accessibility tree
get_state()	Get simplified UI state
get_state_full(filter=True)	Get full UI state (a11y tree + phone state)
get_phone_state()	Get phone state info
get_version()	Get Portal app version string
get_packages()	Get list of launchable packages
take_screenshot(hide_overlay=True)	Take device screenshot, returns PNG bytes
tap(x, y)	Tap screen coordinates
swipe(start_x, start_y, end_x, end_y, duration=None)	Swipe gesture
global_action(action)	Execute accessibility global action
start_app(package, activity=None, stop_before_launch=False)	Launch an app
stop_app(package)	Stop an app
input_text(text, clear=True)	Input text via Portal keyboard
clear_input()	Clear focused input field
press_key(key_code)	Send an Android key code
set_overlay_offset(offset)	Set overlay vertical offset in pixels
set_socket_port(port)	Update the HTTP server port

PortalWSClient

Supports all methods from HTTP client, plus:

Method	Description
get_time()	Get device Unix timestamp in milliseconds
install(urls, hide_overlay=True)	Install APK(s) from URL(s), supports split APKs

Exceptions

Exception	Description
PortalError	Base exception for all Portal client errors
PortalConnectionError	Failed to connect to Portal server
PortalAuthError	Authentication failed (invalid or missing token)
PortalTimeoutError	Request timed out
PortalResponseError	Server returned an unexpected or error response

PortalConfig

Helper dataclass for managing connection settings. Supports loading from environment variables.

from droidrun_agent import PortalConfig

# Direct construction
config = PortalConfig(base_url="http://192.168.1.100:8080", token="YOUR_TOKEN")
client = config.create_client()

# Load from environment variables
config = PortalConfig.from_env()
client = config.create_client()

Environment variables:

Variable	Required	Default	Description
PORTAL_BASE_URL	Yes	-	Portal HTTP or WebSocket base URL
PORTAL_TOKEN	Yes	-	Bearer authentication token
PORTAL_TIMEOUT	No	10.0	Request timeout in seconds
PORTAL_TRANSPORT	No	http	Transport type: http or ws

MCP Server

droidrun-agent includes a built-in MCP (Model Context Protocol) server that exposes all Portal operations as tools. This enables AI agents like openclaw to control Android devices.

Start the MCP Server

# Via CLI entry point
droidrun-agent --mcp

# Or as a Python module
python -m droidrun_agent --mcp

The server reads connection settings from environment variables (PORTAL_BASE_URL, PORTAL_TOKEN, etc.) and communicates over stdio.

Available MCP Tools

Tool	Description
portal_ping	Health check (HTTP only)
portal_tap	Tap screen coordinates
portal_swipe	Swipe gesture
portal_screenshot	Take screenshot, returns PNG image
portal_get_state	Get simplified UI state
portal_get_state_full	Get full UI state (a11y tree + phone state)
portal_get_a11y_tree	Get simplified accessibility tree (HTTP only)
portal_get_a11y_tree_full	Get full accessibility tree (HTTP only)
portal_get_phone_state	Get phone state info (HTTP only)
portal_get_version	Get Portal app version
portal_get_packages	List launchable packages
portal_global_action	Execute accessibility global action
portal_start_app	Launch an app
portal_stop_app	Stop an app
portal_input_text	Input text
portal_clear_input	Clear focused input field
portal_press_key	Send Android key code
portal_set_overlay_offset	Set overlay vertical offset
portal_get_time	Get device timestamp (WebSocket only)
portal_install	Install APK(s) from URL(s) (WebSocket only)

openclaw Integration

To register droidrun-agent as an openclaw skill, add it to your openclaw MCP configuration:

{
  "mcpServers": {
    "droidrun-agent": {
      "command": "uvx",
      "args": ["--with", "mcp", "droidrun-agent", "--mcp"],
      "env": {
        "PORTAL_BASE_URL": "http://192.168.1.100:8080",
        "PORTAL_TOKEN": "YOUR_TOKEN"
      }
    }
  }
}

A ready-to-use skill manifest is also provided at openclaw.skill.json in the project root.

Requirements

• Python >= 3.11
• httpx >= 0.28.1
• websockets >= 12.0
• mcp >= 1.26.0 (optional, for MCP server)

Development Workflow

This project uses uv for development. Here are the common development commands:

Code Formatting

# Format all Python code
uv format

# Check formatting without making changes
uv format --check

Code Quality

# Run code quality checks
uv run ruff check .

# Automatically fix fixable issues
uv run ruff check --fix .

Testing

# Run all tests
uv run pytest

# Run tests with verbose output
uv run pytest -v

# Run tests and show coverage
uv run pytest --cov=src

Dependency Management

# Install development dependencies
uv sync --group dev

# Add a new dependency
uv add package_name

# Add a development dependency
uv add --group dev package_name

# Remove a dependency
uv remove package_name

Complete Development Flow

# 1. Format code
uv format

# 2. Check code quality
uv run ruff check .

# 3. Run tests
uv run pytest

License

This project is licensed under the MIT License - see the LICENSE file for details.