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. Android Debug Bridge (adb) installed and configured
  3. Android device with:

​
Install from PyPI

pip install droidrun

​
Setup the Portal APK

droidrun setup

​
Test functionality

droidrun ping

​
Run Your First Command via CLI

export OPENAI_API_KEY=<YOUR API KEY>
droidrun "Open the settings app and tell me the android version" --provider OpenAI --model gpt-4o

​
Create a Simple Agent via Script

For complex automation, create a Python script:

#!/usr/bin/env python3
import asyncio
from droidrun import AdbTools, DroidAgent
from llama_index.llms.google_genai import GoogleGenAI

async def main():
    # Load tools
    tools = await AdbTools.create()
    # set up google 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 agent
    agent = DroidAgent(
        goal="Open Settings and check battery level",
        llm=llm,
        tools=tools
    )
    
    # 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())

​
Next Steps

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