DroidRun

https://docs.droidrun.ai
Admin
DroidRun is a powerful framework that enables control of Android and iOS devices through intelligent...
Tokens:81,090
Snippets:667
Trust Score:7.7
Update:9 months ago
Show doc for...
Tokens:
Raw
### Setup Droidrun Portal APK

Source: https://docs.droidrun.ai/quickstart

Sets up the Droidrun Portal APK on the connected Android device. This command automatically downloads and installs the APK, then enables the necessary accessibility service for device control.

```bash
droidrun setup
```

--------------------------------

### Install Droidrun CLI Tool

Source: https://docs.droidrun.ai/quickstart

Installs the Droidrun command-line interface (CLI) tool using 'uv'. Supports installation for various LLM providers including Google, Anthropic, OpenAI, DeepSeek, Ollama, and OpenRouter.

```bash
uv tool install 'droidrun[google,anthropic,openai,deepseek,ollama,openrouter]'
```

--------------------------------

### Complete Droid Agent Example with LLMs and Tools

Source: https://docs.droidrun.ai/sdk/configuration

A comprehensive example demonstrating the setup of a DroidAgent with detailed configuration, including multiple LLM integrations, custom tool definitions, credentials, variables, and a Pydantic output model.

```python
from droidrun import (
    DroidAgent, DroidrunConfig,
    AgentConfig, CodeActConfig, DeviceConfig, LoggingConfig, TracingConfig
)
from llama_index.llms.openai import OpenAI
from llama_index.llms.gemini import Gemini
from pydantic import BaseModel

# Structured output
class Output(BaseModel):
    name: str
    value: int

# Custom tool
def send_email(to: str, subject: str, **kwargs) -> str:
    """Send email."""
    return f"Sent to {to}"

# Build configuration
config = DroidrunConfig(
    agent=AgentConfig(
        max_steps=30,
        reasoning=True,
        after_sleep_action=1.5,
        codeact=CodeActConfig(vision=True, safe_execution=True)
    ),
    device=DeviceConfig(
        serial="emulator-5554",
        platform="android",
        use_tcp=False
    ),
    logging=LoggingConfig(
        debug=True,
        save_trajectory="action",
        trajectory_gifs=True
    ),
    tracing=TracingConfig(enabled=True),
)

agent = DroidAgent(
    goal="Complex task",
    config=config,

    # LLMs
    llms={
        "manager": OpenAI(model="gpt-4o"),                    # Planning
        "executor": Gemini(model="models/gemini-2.5-flash"),  # Action selection
        "codeact": Gemini(model="models/gemini-2.5-pro"),     # Code generation
        "text_manipulator": Gemini(model="models/gemini-2.5-flash"),  # Text input
        "app_opener": OpenAI(model="gpt-4o-mini"),            # App launching
        "scripter": Gemini(model="models/gemini-2.5-flash"),  # Off-device scripts
        "structured_output": Gemini(model="models/gemini-2.5-flash"),  # Output extraction
    },

    # Custom tools
    custom_tools={
        "send_email": {
            "arguments": ["to", "subject"],
            "description": "Send email to recipient with subject",
            "function": send_email
        }
    },

    # Credentials
    credentials={"USERNAME": "alice", "PASSWORD": "secret"},

    # Variables
    variables={"api_url": "https://api.example.com"},

    # Structured output
    output_model=Output,

    # Timeout
    timeout=600
)

result = await agent.run()
```

--------------------------------

### Create Droidrun Agent with Python Script

Source: https://docs.droidrun.ai/quickstart

Creates and runs a Droidrun agent using a Python script for complex automation or integration. This example initializes the agent with a goal and configuration, then executes it asynchronously.

```python
import asyncio
from droidrun import DroidAgent, DroidrunConfig

async def main():
    # Use default configuration with built-in LLM profiles
    config = DroidrunConfig()

    # Create agent
    # LLMs are automatically loaded from config.llm_profiles
    agent = DroidAgent(
        goal="Open Settings and check battery level",
        config=config,
    )

    # Run agent
    result = await agent.run()

    # Check results (result is a ResultEvent object)
    print(f"Success: {result.success}")
    print(f"Reason: {result.reason}")
    print(f"Steps: {result.steps}")

if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Setup Droidrun Portal APK with Docker

Source: https://docs.droidrun.ai/guides/docker

This command sets up the Droidrun portal APK by running the container with the 'setup' CLI command. It maps necessary devices and volumes for interaction with an Android phone.

```bash
docker run \
  --group-add plugdev \
  --device /dev/phone1/phone:/dev/phone \
  --volume /dev/bus/usb:/dev/bus/usb \
  --volume ~/.android:/home/droidrun/.android \
  ghcr.io/droidrun/droidrun:latest \
  setup
```

--------------------------------

### Verify Droidrun Setup with Docker

Source: https://docs.droidrun.ai/guides/docker

This command verifies the Droidrun setup by running the container with the 'ping' CLI command. Similar to setup, it requires specific device and volume mappings.

```bash
docker run \
  --group-add plugdev \
  --device /dev/phone1/phone:/dev/phone \
  --volume /dev/bus/usb:/dev/bus/usb \
  --volume ~/.android:/home/droidrun/.android \
  ghcr.io/droidrun/droidrun:latest \
  ping
```

--------------------------------

### Quick Start DroidAgent Initialization (Python)

Source: https://docs.droidrun.ai/sdk/configuration

Demonstrates minimal DroidAgent initialization using default settings and loading configuration from a YAML file. It shows how to create a DroidAgent instance with a goal and run it.

```python
from droidrun import DroidAgent, DroidrunConfig

# Minimal (uses defaults)
agent = DroidAgent(goal="Open settings")
result = await agent.run()

# Load from config.yaml
config = DroidrunConfig.from_yaml("config.yaml")
agent = DroidAgent(goal="Open settings", config=config)
result = await agent.run()
```

--------------------------------

### Install Droidrun for CLI and Python Integration

Source: https://docs.droidrun.ai/quickstart

Installs Droidrun as a Python package using 'uv', enabling both CLI usage and integration within Python scripts. Includes support for multiple LLM providers.

```bash
uv pip install 'droidrun[google,anthropic,openai,deepseek,ollama,openrouter]'
```

--------------------------------

### Setup DroidRun Portal and Verify Connection

Source: https://docs.droidrun.ai/v3/guides/cli

Installs the DroidRun Portal APK on your device and verifies that the connection between your computer and the device is established and functioning correctly.

```sh
droidrun setup
```

```sh
droidrun ping
```

--------------------------------

### Install uv Package Manager

Source: https://docs.droidrun.ai/quickstart

Installs the 'uv' package manager, a fast Python package installer and resolver, for macOS, Linux, and Windows systems. This is a prerequisite for installing Droidrun.

```bash
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```

--------------------------------

### Install Portal APK on Device using Droidrun

Source: https://docs.droidrun.ai/guides/cli

The `droidrun setup` command installs the Portal APK on a specified or auto-detected device. It handles downloading the latest APK, installing it with necessary permissions, and enabling the accessibility service, automating much of the setup process.

```bash
# Auto-detect device
droidrun setup

# Specific device
droidrun setup --device emulator-5554

# Custom APK
droidrun setup --path /path/to/portal.apk
```

--------------------------------

### Verify Droidrun Setup

Source: https://docs.droidrun.ai/guides/device-setup

Confirms that the Droidrun Portal app is successfully installed and accessible on the device. This command checks the connection and communication channel.

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

--------------------------------

### Install DroidRun and Dependencies

Source: https://docs.droidrun.ai/v3/guides/cli

Installs DroidRun along with optional dependencies for various LLM providers. Ensure you select the integrations relevant to your chosen provider.

```sh
pip install 'droidrun[google,anthropic,openai,deepseek,ollama,dev]'
```

--------------------------------

### Install Droidrun v4 using uv

Source: https://docs.droidrun.ai/guides/migration-v3-to-v4

Demonstrates the installation of Droidrun v4 using the 'uv' package manager. Two variations are provided: one for CLI usage and another for CLI and Python integration.

```bash
# For CLI usage only:
uv tool install 'droidrun[google,anthropic,openai,deepseek,ollama,openrouter]'

# For CLI + Python integration:
uv pip install 'droidrun[google,anthropic,openai,deepseek,ollama,openrouter]'
```

--------------------------------

### Configure LLM API Keys via Environment Variables

Source: https://docs.droidrun.ai/quickstart

Sets environment variables for API keys required by different Large Language Model (LLM) providers. This example shows how to set keys for Google Gemini, OpenAI, Anthropic, and DeepSeek.

```bash
# For Google Gemini (default)
export GOOGLE_API_KEY=your-api-key-here

# For OpenAI
export OPENAI_API_KEY=your-api-key-here

# For Anthropic Claude
export ANTHROPIC_API_KEY=your-api-key-here

# For DeepSeek
export DEEPSEEK_API_KEY=your-api-key-here
```

--------------------------------

### Install LlamaIndex LLM Integrations

Source: https://docs.droidrun.ai/v3/guides/cli

Installs additional LlamaIndex LLM integrations if you are using a provider not included in DroidRun's default extras. This example shows installation for the OpenRouter LLM.

```sh
pip install llama-index-llms-openrouter
```

--------------------------------

### Install uv and Droidrun v4

Source: https://docs.droidrun.ai/guides/migration-v3-to-v4

Provides shell commands to install the 'uv' package manager and then install Droidrun v4 with optional integrations for various LLM providers.

```bash
# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh  # macOS/Linux

# Upgrade Python if needed
python --version  # Should be 3.11+

# Uninstall v3
pip uninstall droidrun

# For CLI + Python integration
uv pip install 'droidrun[google,anthropic,openai,deepseek,ollama,openrouter]'

# Or for CLI only
uv tool install 'droidrun[google,anthropic,openai,deepseek,ollama,openrouter]'
```

--------------------------------

### Troubleshoot Droidrun Portal Installation

Source: https://docs.droidrun.ai/guides/device-setup

Offers solutions for the 'Portal is not installed' error when using `droidrun ping`. This involves reinstalling the portal, checking package lists, and verifying APK architecture compatibility with the device.

```bash
# Reinstall Droidrun Portal
droidrun setup

# Check installed packages
# adb shell pm list packages | grep droidrun
```

--------------------------------

### Droidrun Command Examples with Different LLM Providers

Source: https://docs.droidrun.ai/guides/cli

These examples demonstrate how to use the `droidrun run` command with various LLM providers like GoogleGenAI, OpenAI, Anthropic, and Ollama. Each example shows the necessary environment variable setup and the command invocation with specific provider and model flags.

```bash
# Google Gemini
export GOOGLE_API_KEY=your-key
droidrun "Archive old emails" \
  --provider GoogleGenAI \
  --model models/gemini-2.5-flash

# OpenAI
export OPENAI_API_KEY=your-key
droidrun "Create shopping list" \
  --provider OpenAI \
  --model gpt-4o

# Anthropic Claude
export ANTHROPIC_API_KEY=your-key
droidrun "Reply to latest email" \
  --provider Anthropic \
  --model claude-sonnet-4-5-latest

# Local Ollama (free)
droidrun "Turn on dark mode" \
  --provider Ollama \
  --model llama3.3:70b \
  --base_url http://localhost:11434
```

--------------------------------

### Droidrun v4 configuration file example

Source: https://docs.droidrun.ai/guides/migration-v3-to-v4

An example of the `config.yaml` file used in Droidrun v4. It defines LLM profiles, default settings, and other parameters for agent configuration.

```yaml
# config.yaml (auto-generated)
llm_profiles:
  - name: "gemini-flash"
    provider: "GoogleGenAI"
    model: "models/gemini-2.5-flash"
    
  - name: "gpt-4o"
    provider: "OpenAI"
    model: "gpt-4o"

default_profile: "gemini-flash"
vision: false
reasoning: false
max_steps: 15
```

--------------------------------

### Generate and Configure config.yaml

Source: https://docs.droidrun.ai/guides/migration-v3-to-v4

Shows how to generate the default `config.yaml` file by running a Droidrun command and provides an example of how to define LLM profiles and other settings within the configuration file.

```bash
# Run any command to auto-generate config.yaml
droidrun ping

# Edit config.yaml to add your LLM profiles:
llm_profiles:
  - name: "my-gemini"
    provider: "GoogleGenAI"
    model: "models/gemini-2.5-flash"
    
  - name: "my-gpt4"
    provider: "OpenAI"
    model: "gpt-4o"

default_profile: "my-gemini"
vision: false
reasoning: false
max_steps: 15
```

--------------------------------

### Get Installed Apps with Labels

Source: https://docs.droidrun.ai/sdk/adb-tools

Fetches a list of installed applications, including their package names and human-readable labels. It can optionally include system applications.

```python
def get_apps(include_system: bool = True) -> List[Dict[str, str]]:
    """Get installed apps with package name and human-readable label."""
    # ... implementation ...

# Usage examples:
# apps = await tools.get_apps(include_system=False)
# for app in apps:
#     print(f"{app['label']}: {app['package']}")
```

--------------------------------

### Manage Android Applications with AdbTools

Source: https://docs.droidrun.ai/v3/concepts/android-tools

Illustrates application management tasks including starting an app, listing installed packages (optionally including system apps), and installing an APK file. The `install_app` function supports reinstallation and automatic permission granting.

```python
# App management examples
await tools.start_app("com.android.settings")
packages = await tools.list_packages()
all_packages = await tools.list_packages(include_system_apps=True)
await tools.install_app("/path/to/app.apk", reinstall=True)
```

--------------------------------

### Manage Multiple Android Devices with Droidrun AI

Source: https://docs.droidrun.ai/guides/device-setup

Demonstrates how to list connected devices, target a specific device for commands using the CLI or Python, and control multiple devices in parallel using asynchronous Python code. Ensure ADB is set up and devices are recognized.

```bash
droidrun devices
# Found 2 connected device(s):
#   • emulator-5554
#   • 192.168.1.100:5555
```

```bash
# CLI
droidrun run "your command" --device emulator-5554

# Python
tools = DeviceConfig(serial="emulator-5554")
agent = DroidAgent(goal="your task", tools=tools)
```

```python
import asyncio
from droidrun import DeviceConfig, DroidrunConfig, DroidAgent
from adbutils import adb

async def control_device(serial: str, command: str):
    device_config = DeviceConfig(serial=serial)
    config = DroidrunConfig(device=device_config)
    agent = DroidAgent(goal=command, config=config)
    return await agent.run()

async def main():
    devices = 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())
```

--------------------------------

### Run Droidrun Command via CLI

Source: https://docs.droidrun.ai/quickstart

Executes commands on an Android device using Droidrun's CLI. Demonstrates basic command execution, overriding the LLM provider and model, and enabling vision or reasoning modes.

```bash
# Using default configuration (Google Gemini)
droidrun run "Open the settings app and tell me the Android version"

# Override provider and model
droidrun run "Check the battery level" --provider OpenAI --model gpt-4o

# Enable vision mode (sends screenshots to LLM)
droidrun run "What app is currently open?" --vision

# Enable reasoning mode (uses Manager-Executor workflow for complex tasks)
droidrun run "Find a contact named John and send him an email" --reasoning
```

--------------------------------

### Test Droidrun v4 Commands

Source: https://docs.droidrun.ai/guides/migration-v3-to-v4

Provides essential bash commands to test the installation and basic functionality of Droidrun v4, including checking device connection, running simple commands, and executing Python scripts.

```bash
# Test device connection
droidrun ping

# Test simple command
droidrun "Open Settings"

# Test your Python script
python your_script.py
```

--------------------------------

### Use Ollama Provider with DroidRun CLI

Source: https://docs.droidrun.ai/v3/guides/cli

Example of using the Ollama provider to run open-source models locally. It requires specifying the model name and optionally the Ollama server URL.

```sh
droidrun run \
  --provider Ollama \
  --model qwen2.5vl:3b \
  --base_url http://localhost:11434 \
  "Open the settings app"
```

--------------------------------

### Setting Droidrun AI API Keys with Environment Variables

Source: https://docs.droidrun.ai/sdk/configuration

This shows how to set API keys for various LLM providers and specify a custom Droidrun configuration file path using environment variables. Setting these variables is crucial for authentication and for using configurations other than the default. Examples are provided for Google, OpenAI, Anthropic, and DeepSeek API keys, as well as the `DROIDRUN_CONFIG` variable.

```bash
export GOOGLE_API_KEY=your-key
export OPENAI_API_KEY=your-key
export ANTHROPIC_API_KEY=your-key
export DEEPSEEK_API_KEY=your-key
export DROIDRUN_CONFIG=/path/to/config.yaml  # Custom config path
```

--------------------------------

### Run Droidrun Agents with Docker

Source: https://docs.droidrun.ai/guides/docker

These commands demonstrate how to run Droidrun agents to control an Android device using natural language. They showcase default configurations, overriding providers/models, and using locally-running LLMs.

```bash
# Using default configuration with Google API key
docker run --group-add plugdev --device /dev/phone1/phone:/dev/phone --volume /dev/bus/usb:/dev/bus/usb --volume ~/.android:/home/droidrun/.android --env GOOGLE_API_KEY=your-api-key-here ghcr.io/droidrun/droidrun:latest run "Open the settings app and tell me the Android version"
```

```bash
# Override provider and model
docker run --group-add plugdev --device /dev/phone1/phone:/dev/phone --volume /dev/bus/usb:/dev/bus/usb --volume ~/.android:/home/droidrun/.android --env OPENAI_API_KEY=your-api-key-here ghcr.io/droidrun/droidrun:latest run "Open a browser and search for droidrun" -p OpenAI -m gpt-4o
```

```bash
# Use a locally-running LLM, example for LM Studio running in the LAN
docker run --group-add plugdev --device /dev/phone1/phone:/dev/phone --volume /dev/bus/usb:/dev/bus/usb --volume ~/.android:/home/droidrun/.android --network host ghcr.io/droidrun/droidrun:latest run "Open a browser and search for droidrun" -p OpenAILike -m gpt-oss --api_base http://IP-of-LMStudio-server:PORT/v1
```

--------------------------------

### Install ADB on macOS and Linux

Source: https://docs.droidrun.ai/guides/device-setup

Installs the Android Debug Bridge (ADB) using package managers for macOS and Linux environments. ADB is essential for communicating with Android devices from your computer.

```bash
brew install android-platform-tools
```

```bash
sudo apt install adb
```

--------------------------------

### Create Custom App Instruction Cards (Bash)

Source: https://docs.droidrun.ai/guides/migration-v3-to-v4

Teaches agents how to use specific apps by creating custom instruction guides. This involves creating a directory for app cards, defining markdown files for each app, and registering them in a JSON configuration file.

```bash
# App cards are enabled by default
droidrun run "Send an email to john@example.com" --reasoning
```

```bash
# 1. Create app cards directory
mkdir -p config/app_cards

# 2. Create a markdown file for your app
touch config/app_cards/chrome.md

# 3. Register in app_cards.json
echo '{"com.android.chrome": "chrome.md"}' > config/app_cards/app_cards.json
```

--------------------------------

### Install Portal App with Droidrun CLI

Source: https://docs.droidrun.ai/guides/device-setup

Automatically downloads, installs, and grants necessary permissions for the Droidrun Portal app on a connected Android device. Optionally, a specific device can be targeted using its serial number.

```bash
droidrun setup
droidrun setup --device SERIAL_NUMBER
```

--------------------------------

### DeviceConfig Initialization (Python)

Source: https://docs.droidrun.ai/sdk/configuration

Shows how to initialize DeviceConfig, specifying device connection details like serial number, platform, and communication protocol (TCP vs. content provider).

```python
from droidrun import DeviceConfig

DeviceConfig(
    serial=None,
    platform="android",
    use_tcp=False,
)
```

--------------------------------

### DroidAgent Initialization

Source: https://docs.droidrun.ai/sdk/configuration

Demonstrates minimal and config file-based initialization of the DroidAgent.

```APIDOC
## DroidAgent Initialization

### Description
Provides examples for initializing the DroidAgent, either with minimal settings or by loading configuration from a YAML file.

### Method
`DroidAgent()`

### Endpoint
N/A (Class Initialization)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
from droidrun import DroidAgent, DroidrunConfig

# Minimal (uses defaults)
agent = DroidAgent(goal="Open settings")
result = await agent.run()

# Load from config.yaml
config = DroidrunConfig.from_yaml("config.yaml")
agent = DroidAgent(goal="Open settings", config=config)
result = await agent.run()
```

### Response
#### Success Response (200)
N/A (Class Initialization)

#### Response Example
N/A
```

--------------------------------

### CodeActConfig Initialization (Python)

Source: https://docs.droidrun.ai/sdk/configuration

Demonstrates the configuration for CodeActConfig, which controls code execution capabilities, including vision, prompt files, and safe execution settings.

```python
CodeActConfig(
    vision=True,
    system_prompt="system.jinja2",
    user_prompt="user.jinja2",
    safe_execution=True,
)
```

--------------------------------

### ManagerConfig Initialization (Python)

Source: https://docs.droidrun.ai/sdk/configuration

Illustrates the configuration for ManagerConfig, enabling vision capabilities and specifying the system prompt file for the manager component.

```python
ManagerConfig(
    vision=True,
    system_prompt="system.jinja2",
)
```

--------------------------------

### Run DroidRun Commands for iOS (CLI)

Source: https://docs.droidrun.ai/guides/device-setup

These command-line examples show how to execute DroidRun commands targeting an iOS device. The `--ios` flag explicitly designates the platform, or alternatively, the platform can be set to 'ios' within the `config.yaml` file for persistent configuration.

```bash
# Use --ios flag
droidrun run "your command" --ios

# Or set platform in config.yaml:
# device:
#   platform: ios
```

--------------------------------

### Python: Initialize Droid Agent with Tools and Configuration

Source: https://docs.droidrun.ai/sdk/base-tools

This Python code snippet shows the initialization of a Droid Agent, which requires a `Tools` instance for device control and a `DroidrunConfig` object for configuration settings. It demonstrates how to create an `AdbTools` instance with a specific serial number and a default `DroidrunConfig`.

```python
from droidrun import DroidAgent
from droidrun.tools import AdbTools
from droidrun.config_manager import DroidrunConfig

# Create tools instance
tools = AdbTools(serial="emulator-5554")

# Create config
config = DroidrunConfig()

```

--------------------------------

### List USB Devices (Bash)

Source: https://docs.droidrun.ai/guides/docker

Lists connected USB devices to identify vendor and product IDs. This is a prerequisite for setting up udev rules to uniquely identify your Android phone.

```bash
> lsusb
Bus 003 Device 002: ID 18d1:4ee2 Google Inc. Nexus/Pixel Device (MTP + debug)
```

--------------------------------

### Enable Wireless Debugging (TCP/IP Mode) - Older Android

Source: https://docs.droidrun.ai/guides/device-setup

Enables the TCP/IP mode for wireless debugging on older Android versions (10 and below). This setup requires an initial USB connection.

```bash
# Enable TCP/IP Mode (USB Required)
# (Command details omitted as per input)
```

--------------------------------

### Best Practice: Handle Platform Differences

Source: https://docs.droidrun.ai/sdk/base-tools

Provides an example of how to handle platform-specific differences, such as the back button implementation, between Android (AdbTools) and iOS (IOSTools). It checks the type of the tools object to execute platform-specific logic.

```python
from droidrun.tools import AdbTools, IOSTools

if isinstance(tools, AdbTools):
    await tools.press_key(4)  # Android back button
elif isinstance(tools, IOSTools):
    # iOS doesn't have back button - find in UI
    state = tools.get_state()
    for elem in state['a11y_tree']:
        if 'back' in elem.get('label', '').lower():
            tools.tap_by_index(elem['index'])
```

--------------------------------

### Python Example: Droidrun Agent with Gemini LLM

Source: https://docs.droidrun.ai/v3/guides/gemini

A minimal Python script demonstrating how to initialize a Droidrun agent using the Gemini LLM. It sets up ADB tools, configures the GoogleGenAI LLM with an API key and model name, and then runs the agent to perform a specified goal like opening settings and checking battery level. Ensure to replace 'YOUR_GEMINI_API_KEY' with your actual key.

```python
import asyncio
from llama_index.llms.google_genai import GoogleGenAI
from droidrun import DroidAgent, AdbTools

async def main():
    # load adb tools for the first connected device
    tools = AdbTools()

    # Set up the Gemini LLM
    llm = GoogleGenAI(
        api_key="YOUR_GEMINI_API_KEY",  # Replace with your Gemini API key
        model="gemini-2.5-flash",       # or "gemini-2.5-pro" for enhanced reasoning
    )

    # Create the DroidAgent
    agent = DroidAgent(
        goal="Open Settings and check battery level",
        llms=llm,
        tools=tools,
        # vision=True,        # Optional: enable if using multimodal models
        # reasoning=False,    # Optional: enable planning/reasoning
    )

    # Run the agent
    result = await agent.run()
    print(f"Success: {result['success']}")
    if result.get('output'):
        print(f"Output: {result['output']}")

if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Setup and Run Commands with Droidrun CLI

Source: https://docs.droidrun.ai/guides/cli

This snippet demonstrates the basic usage of the Droidrun CLI for device setup and executing natural language commands. It showcases the auto-configuration feature and command shorthand.

```bash
# Setup device
droidrun setup

# Run a command (shorthand - no "run" needed)
droidrun "Open Spotify and play my Discover Weekly"

# Or explicit
droidrun run "Turn on Do Not Disturb"
```

--------------------------------

### Enable Droidrun Accessibility Service

Source: https://docs.droidrun.ai/guides/device-setup

Guides on enabling the Droidrun accessibility service, which is crucial for `droidrun ping` to function correctly. It includes commands for auto-enabling via ADB and manual steps through device settings.

```bash
# Auto-enable accessibility service
# Ensure Droidrun Portal is installed first

# Set enabled services
# Replace 'com.droidrun.portal/com.droidrun.portal.DroidrunAccessibilityService' if your portal package name differs
# adb shell settings put secure enabled_accessibility_services \
#  com.droidrun.portal/com.droidrun.portal.DroidrunAccessibilityService

# Enable accessibility globally
# adb shell settings put secure accessibility_enabled 1

# Verify enabled services (should contain the Droidrun service)
# adb shell settings get secure enabled_accessibility_services
```

--------------------------------

### Python Example: Droidrun with OpenAI-like LLM

Source: https://docs.droidrun.ai/v3/guides/openailike

A minimal Python script demonstrating how to initialize Droidrun with an OpenAI-compatible LLM. It sets up ADB tools, configures the LLM (including local endpoints via api_base), creates a DroidAgent with a specific goal, and runs the agent to automate an Android device.

```python
import asyncio
from llama_index.llms.openai_like import OpenAILike
from droidrun import DroidAgent, AdbTools

async def main():
    # Load adb tools for the first connected device
    tools = AdbTools()

    # Set up the OpenAI-like LLM (uses env vars for API key and base by default)
    llm = OpenAILike(
        model="gpt-3.5-turbo",  # or "gpt-4o", "gpt-4", etc.
        api_base="http://localhost:1234/v1",  # For local endpoints
        is_chat_model=True, # droidrun requires chat model support
        api_key="YOUR API KEY"
    )

    # Create the DroidAgent
    agent = DroidAgent(
        goal="Open Settings and check battery level",
        llm=llm,
        tools=tools,
        vision=False,        # Set to True if your model supports vision
        reasoning=False,     # Optional: enable planning/reasoning
    )

    # Run the agent
    result = await agent.run()
    print(f"Success: {result['success']}")
    if result.get('output'):
        print(f"Output: {result['output']}")

if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Run Droidrun Container (Bash)

Source: https://docs.droidrun.ai/guides/docker

Launches the Droidrun Docker container with specific configurations to enable Android device access. It includes options for group membership, device mapping, USB bus mounting, and Android configuration directory mounting, followed by the Droidrun command.

```bash
docker run \
  --group-add plugdev \
  --device /dev/phone1/phone:/dev/phone \
  --volume /dev/bus/usb:/dev/bus/usb \
  --volume ~/.android:/home/droidrun/.android \
  ghcr.io/droidrun/droidrun:latest \
  <droidrun command>
```

--------------------------------

### ExecutorConfig Initialization (Python)

Source: https://docs.droidrun.ai/sdk/configuration

Shows the configuration for ExecutorConfig, which enables vision and sets the system prompt file for the executor component.

```python
ExecutorConfig(
    vision=True,
    system_prompt="system.jinja2",
)
```

--------------------------------

### Initialize Droid Agent in v3

Source: https://docs.droidrun.ai/guides/migration-v3-to-v4

This Python code snippet demonstrates how to initialize a Droid Agent in v3. It involves manual setup of the LLM and tools, passing them directly to the agent constructor.

```python
from droidrun import AdbTools, DroidAgent
from llama_index.llms.google_genai import GoogleGenAI

# Manual LLM setup
llm = GoogleGenAI(
    api_key="YOUR_GEMINI_API_KEY",
    model="gemini-2.5-flash",
)

# Manual tools loading
tools = AdbTools()

# Agent creation
agent = DroidAgent(
    goal="Open Settings and check battery level",
    llm=llm,
    tools=tools,
    vision=True,
    reasoning=False,
)
```

--------------------------------

### Set environment variables for API keys

Source: https://docs.droidrun.ai/guides/migration-v3-to-v4

Example commands to set environment variables for API keys required by various LLM providers in Droidrun v4. These keys are used for authentication.

```bash
export GOOGLE_API_KEY=your-api-key
export OPENAI_API_KEY=your-api-key
export ANTHROPIC_API_KEY=your-api-key
```

--------------------------------

### Enable TCP Communication Mode

Source: https://docs.droidrun.ai/guides/device-setup

Activates the TCP communication mode for Droidrun operations. This involves setting up ADB port forwarding and configuring the Droidrun client or Python tools to use TCP.

```bash
# CLI
droidrun run "your command" --tcp

# Python
tools = DeviceConfig(serial="DEVICE_SERIAL", use_tcp=True)
```

--------------------------------

### Run DroidAgent with LLM and Config

Source: https://docs.droidrun.ai/sdk/droid-agent

Initializes a DroidAgent with a specified LLM and configuration to perform a goal, such as taking a screenshot. It requires the 'droidrun' library and an LLM instance.

```python
from droidrun import DroidAgent
from openai import OpenAI

# Assuming 'config' is defined elsewhere
# config = DroidrunConfig()

llm = OpenAI(model="gpt-4o", temperature=0.2)

agent = DroidAgent(
    goal="Take a screenshot and save it",
    llms=llm,
    config=config
)

result = await agent.run()
```

--------------------------------

### Test Droidrun Device Connection

Source: https://docs.droidrun.ai/quickstart

Tests the connection between Droidrun and the connected Android device. A successful ping confirms that the Portal app is running, the accessibility service is enabled, and the device is ready for control.

```bash
droidrun ping
```

--------------------------------

### Configure Udev Rule for Android Device (Bash)

Source: https://docs.droidrun.ai/guides/docker

Creates a custom udev rule to map a specific Android device to a static path within the system. This ensures consistent device recognition across reconnections, essential for Docker container access.

```bash
SUBSYSTEM=="usb", ATTR{idVendor}=="XXXX", ATTR{idProduct}=="YYYY", ATTR{serial}=="SSSS", MODE="0666", GROUP="plugdev", SYMLINK+="phone1/phone"
```

--------------------------------

### Serve Ollama and Pull Models (Shell)

Source: https://docs.droidrun.ai/v3/guides/ollama

Commands to start the Ollama local LLM server and download specific models. Ensure Ollama is installed and running before pulling models. These commands are executed in a shell environment.

```sh
ollama serve

```

```sh
ollama pull qwen2.5vl
ollama pull gemma3
ollama pull deepseek-r1 # no vision capabilities. can only be used with vision disabled
ollama pull llama4

```

--------------------------------

### Connect and Verify Wireless Debugging

Source: https://docs.droidrun.ai/guides/device-setup

Establishes a connection to the Android device over the network using wireless debugging and then verifies the connection with the Droidrun `ping` command, specifying the device's IP address and port.

```bash
adb connect IP:PORT
droidrun ping --device IP:PORT
```

--------------------------------

### Best Practice: Get State Before Tapping

Source: https://docs.droidrun.ai/sdk/base-tools

Demonstrates the correct sequence for interacting with UI elements. It's crucial to call get_state() before tap_by_index() to ensure the UI element cache is up-to-date, preventing errors.

```python
# Correct
state = await tools.get_state()
await tools.tap_by_index(5)

# Wrong - will fail with "No UI elements cached"
await tools.tap_by_index(5)
```

--------------------------------

### Pair Device for Wireless Debugging (QR Code)

Source: https://docs.droidrun.ai/guides/device-setup

Pairs the Android device with the computer using the QR code method for wireless debugging. This is typically used for the first-time connection when wireless debugging is enabled.

```bash
adb pair <QR_CODE_STRING>
```

--------------------------------

### Jinja2 Syntax: Variables, Conditionals, and Loops

Source: https://docs.droidrun.ai/concepts/prompts

Provides concise examples of fundamental Jinja2 templating syntax. It shows how to display variables (both direct and nested), implement conditional logic using `if` statements, and iterate over collections using `for` loops. These are the building blocks for creating dynamic prompt templates.

```jinja2
{{ instruction }}
{{ variables.my_var }}
```

```jinja2
{% if app_card %}
<app_card>{{ app_card }}</app_card>
{% endif %}

{% if error_history %}
You have {{ error_history | length }} errors
{% endif %}
```

```jinja2
{% for error in error_history %}
- {{ error.action }}: {{ error.error }}
{% endfor %}
```

--------------------------------

### Troubleshoot ADB Device Not Found or Unauthorized

Source: https://docs.droidrun.ai/guides/device-setup

Provides steps to resolve issues where ADB does not recognize connected devices or shows them as unauthorized. This includes physical connection checks, authorization resets, and restarting the ADB server.

```bash
# Restart ADB
adb kill-server && adb start-server
```

--------------------------------

### Troubleshoot TCP Communication

Source: https://docs.droidrun.ai/guides/device-setup

Provides commands to diagnose and resolve issues with TCP communication mode, including checking ADB port forwards, verifying the Portal server status on the device, and resetting all port forwards.

```bash
# Check port forwarding
adb forward --list

# Test Portal server
adb shell netstat -an | grep 8080

# Remove all forwards and retry
adb forward --remove-all
droidrun ping --tcp
```

--------------------------------

### ScripterConfig Initialization (Python)

Source: https://docs.droidrun.ai/sdk/configuration

Demonstrates the configuration for ScripterConfig, controlling off-device Python execution, including enabling/disabling, step limits, timeouts, prompt paths, and safety settings.

```python
ScripterConfig(
    enabled=True,
    max_steps=10,
    execution_timeout=30.0,
    system_prompt_path="system.jinja2",
    safe_execution=False,
)
```

--------------------------------

### Define Structured Output Model with Pydantic

Source: https://docs.droidrun.ai/sdk/configuration

This example illustrates setting a structured output model for the DroidAgent using Pydantic's BaseModel. The agent will attempt to parse its output according to this model, enabling typed access to results.

```python
from pydantic import BaseModel

class FlightInfo(BaseModel):
    airline: str
    flight_number: str
    confirmation_code: str

agent = DroidAgent(
    goal="Book a flight and extract details",
    output_model=FlightInfo
)
result = await agent.run()
print(result.structured_output.airline)  # Typed output
```

--------------------------------

### AppCardConfig Initialization (Python)

Source: https://docs.droidrun.ai/sdk/configuration

Illustrates the configuration for AppCardConfig, which enables app-specific instructions and defines modes, directories, server details, and timeouts for app card processing.

```python
AppCardConfig(
    enabled=True,
    mode="local",
    app_cards_dir="config/app_cards",
    server_url=None,
    server_timeout=2.0,
    server_max_retries=2,
)
```

--------------------------------

### Troubleshoot: LLM provider errors

Source: https://docs.droidrun.ai/guides/cli

Helps resolve errors related to Large Language Model (LLM) providers. It guides users on installing necessary provider packages, checking existing API keys, and setting them if they are missing.

```bash
# Install provider
uv pip install 'droidrun[google,openai,anthropic]'

# Check API key
echo $GOOGLE_API_KEY

# Set if missing
export GOOGLE_API_KEY=your-key
```

--------------------------------

### Initialize AdbTools Instance

Source: https://docs.droidrun.ai/sdk/adb-tools

Initializes the AdbTools with various configuration options including device serial, communication mode (TCP/content provider), and optional LLM integrations for advanced workflows. It automatically sets up the Droidrun Portal keyboard and establishes a connection client.

```python
from droidrun.tools import AdbTools

# Auto-detect device
tools = AdbTools()

# Specific device
tools = AdbTools(serial="emulator-5554")

# TCP mode (faster communication, requires port forwarding)
tools = AdbTools(serial="emulator-5554", use_tcp=True)

# With LLM support for advanced workflows
from llama_index.llms.openai import OpenAI
llm = OpenAI(model="gpt-4")
tools = AdbTools(
    serial="emulator-5554",
    app_opener_llm=llm,
    text_manipulator_llm=llm
)
```
Tokens:
Raw