Quickstart

This guide will help you get DroidRun installed and running quickly, controlling your Android device through natural language in minutes.

​

📋 Prerequisites

Before installing DroidRun, ensure you have:

1. Python 3.10+ installed on your system
2. ADB (Android Debug Bridge) installed and configured
   • Download Android SDK Platform Tools
   • Make sure adb is in your PATH
3. Android device with:
   • Developer options enabled
   • USB debugging enabled
   • Connected via USB or on the same network (for wireless debugging)
4. DroidRun Portal app installed on your Android device
   • Available from the DroidRun Portal repository
   • Installation instructions are provided in the Install DroidRun Portal App section below

​

🚀 Installation Methods

​

Method 1: Install from PyPI (Recommended)

The simplest way to install DroidRun is using pip:

pip install droidrun

​

Method 2: Install from Source

To install the latest development version:

# Clone the repository
git clone https://github.com/droidrun/droidrun.git
cd droidrun

# Create a virtual environment (highly recommended)
python -m venv .venv

# Activate the virtual environment
# On Windows:
.venv\Scripts\activate
# On macOS/Linux:
source .venv/bin/activate

# Install dependencies and the package in development mode
pip install -e .

Using a virtual environment helps isolate DroidRun’s dependencies from your global Python environment, preventing potential conflicts with other packages.

​

🔑 API Key Setup

DroidRun supports multiple LLM providers. Set up at least one:

​

OpenAI

1. Sign up at OpenAI
2. Create an API key
3. Set environment variable:

   export OPENAI_API_KEY="your_openai_api_key_here"

​

Anthropic

1. Sign up at Anthropic
2. Get API key
3. Set environment variable:

   export ANTHROPIC_API_KEY="your_anthropic_api_key_here"

​

Google Gemini (Default)

1. Sign up for Google AI Studio
2. Create API key
3. Set environment variable:

   export GEMINI_API_KEY="your_gemini_api_key_here"

​

Ollama (Local)

1. Install Ollama
2. Pull desired models:

   ollama pull llama2

3. No API key needed

​

Deepseek

1. Sign up at Deepseek
2. Get API key
3. Set environment variable:

   export DEEPSEEK_API_KEY="your_deepseek_api_key_here"

For convenience, create a .env file:

# .env file example
export OPENAI_API_KEY="your_openai_api_key_here"
export ANTHROPIC_API_KEY="your_anthropic_api_key_here"
export GEMINI_API_KEY="your_gemini_api_key_here"
export DEEPSEEK_API_KEY="your_deepseek_api_key_here"

Then load it:

source .env

​

📱 Device Configuration

​

Verify ADB Installation

Ensure ADB is properly installed:

adb version

​

Connect to Device

Connect your device via USB or Wi-Fi:

# List connected devices
droidrun devices

# Connect over TCP/IP
droidrun connect 192.168.1.100

Make sure:

• USB debugging is enabled
• Device appears in droidrun devices

​

📦 Install DroidRun Portal App

The DroidRun Portal app provides accessibility services needed for device control:

1. Download the APK from DroidRun Portal repository
2. Install using DroidRun:

   droidrun setup --path=/path/to/droidrun-portal.apk

The setup command will:

1. Install the APK
2. Enable accessibility service
3. Configure necessary permissions

​

💻 Run Your First Command

Test with these commands:

# Using default (Gemini)
droidrun "Open the settings app"

# Using specific provider and model
droidrun "Open calculator" --provider Gemini --model models/gemini-2.5-pro-preview-05-06

# With vision and planning
droidrun "Take a screenshot and describe what's on the screen" --vision --reasoning

# Using local Ollama
droidrun "Check battery level" --provider Ollama --model llama2

​

⚙️ Command Options

DroidRun CLI supports various options:

# Specify device
droidrun "Open Chrome" --device your_device_serial

# Set max steps
droidrun "Open settings" --steps 20

# Enable vision
droidrun "Analyze screen" --vision

# Enable planning mode
droidrun "Complex task" --reasoning

# Enable tracing (requires running 'phoenix serve' in a separate terminal first)
droidrun "Debug this" --tracing

# Adjust temperature
droidrun "Creative task" --temperature 0.7

​

📝 Create a Simple Script

For complex automation, create a Python script:

#!/usr/bin/env python3
import asyncio
from droidrun.agent.droid import DroidAgent
from droidrun.agent.utils.llm_picker import load_llm
from droidrun.tools import load_tools

async def main():
    # Load tools and LLM
    tool_list, tools_instance = await load_tools()
    llm = load_llm(
        provider_name="Gemini",  # Case sensitive: OpenAI, Ollama, Anthropic, Gemini, DeepSeek
        model="models/gemini-2.5-pro-preview-05-06",
        temperature=0.2
    )
    
    # Create agent
    agent = DroidAgent(
        goal="Open Settings and check battery level",
        llm=llm,
        tools_instance=tools_instance,
        tool_list=tool_list,
        vision=True,
        reasoning=True,
        enable_tracing=True  # Requires running 'phoenix serve' in a separate terminal first
    )
    
    # Run 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())

​

🔄 Using LlamaIndex Integration

DroidRun v2 uses LlamaIndex for LLM integration, providing more flexibility:

import asyncio
from llama_index.core.llms import LLM
from llama_index.llms.gemini import Gemini
from droidrun.agent.droid import DroidAgent
from droidrun.tools import load_tools

async def main():
    # Load tools
    tool_list, tools_instance = await load_tools()
    
    # Create LlamaIndex LLM directly
    llm = Gemini(
        model="models/gemini-2.5-pro-preview-05-06",
        temperature=0.2,
        additional_kwargs={"safety_settings": {"hate": "block_none"}}
    )
    
    # Or use OpenAI
    # from llama_index.llms.openai import OpenAI
    # llm = OpenAI(model="gpt-4o", temperature=0.2)
    
    # Create agent with LlamaIndex LLM
    agent = DroidAgent(
        goal="Open Settings and check battery level",
        llm=llm,
        tools_instance=tools_instance,
        tool_list=tool_list,
        vision=True,
        reasoning=True
    )
    
    # Run agent
    result = await agent.run()
    print(f"Success: {result['success']}")

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

​

🔎 Vision Capabilities

When vision is enabled:

• The agent can take and analyze screenshots
• Ideal for UI-based tasks that require visual context

​

🕵️ Tracing and Debugging

DroidRun integrates with Arize Phoenix for execution tracing and debugging:

# Install Phoenix (if not already installed)
pip install "arize-phoenix[llama-index]"

# Start Phoenix server in a separate terminal
phoenix serve

Tracing provides:

• Visual execution flow
• LLM prompts and responses
• Tool execution details
• Error detection

For detailed instructions, see the Execution Tracing documentation.

​

📊 Token Usage Tracking

DroidRun tracks token usage for all LLM calls:

• Total prompt tokens
• Total completion tokens
• Number of API calls

This helps you optimize your automation tasks and manage costs effectively.

​

🔧 Common Installation Issues

​

ADB Not Found

Ensure ADB is in your PATH or add it:

export PATH=$PATH:/path/to/android-sdk/platform-tools

​

Device Not Detected

• Check that USB debugging is enabled on your device
• Try a different USB cable or port
• For wireless debugging, ensure device and computer are on the same network

​

API Key Issues

• Verify you’ve correctly set the environment variable
• Ensure your API key is valid and has not expired
• Check for whitespace or extra characters in your API key

​

✅ Verify Installation

Verify DroidRun is installed correctly:

# Check installed version
pip show droidrun

​

🎉 Next Steps

Now that you’ve got DroidRun running, you can:

• Learn about the DroidAgent system
• Explore planning capabilities
• Discover Android interactions
• Learn about the Portal App