DroidRun is a powerful framework for controlling Android devices through LLM agents. It allows you to automate Android device interactions using natural language commands.
- Control Android devices with natural language commands
- Supports multiple LLM providers (OpenAI, Anthropic, Gemini)
- Easy to use CLI
- Extendable Python API for custom automations
- Screenshot analysis for visual understanding of the device
pip install droidrungit clone https://github.com/droidrun/droidrun.git
cd droidrun
pip install -e .- An Android device connected via USB or ADB over TCP/IP
- ADB (Android Debug Bridge) installed and configured
- DroidRun Portal app installed on your Android device
- API key for at least one of the supported LLM providers:
- OpenAI
- Anthropic
- Google Gemini
ADB (Android Debug Bridge) is required for DroidRun to communicate with your Android device:
-
Install ADB:
- Windows: Download Android SDK Platform Tools and extract the ZIP file
- macOS:
brew install android-platform-tools - Linux:
sudo apt install adb(Ubuntu/Debian) orsudo pacman -S android-tools(Arch)
-
Add ADB to your PATH:
- Windows: Add the path to the extracted platform-tools folder to your system's PATH environment variable
- macOS/Linux: Add the following to your ~/.bashrc or ~/.zshrc:
export PATH=$PATH:/path/to/platform-tools
-
Verify ADB installation:
adb version
-
Enable USB debugging on your Android device:
- Go to Settings → About phone
- Tap Build number 7 times to enable Developer options
- Go to Settings → System → Developer options (location may vary by device)
- Enable USB debugging
DroidRun requires the DroidRun Portal app to be installed on your Android device:
- Download the DroidRun Portal APK from the DroidRun Portal repository
- Use DroidRun to install the portal app:
droidrun setup --path=/path/to/droidrun-portal.apk
Alternatively, you can use ADB to install it manually:
adb install -r /path/to/droidrun-portal.apkCreate a .env file in your working directory or set environment variables:
# Choose at least one of these based on your preferred provider
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" To load the environment variables from the .env file:
source .envConnect your device via USB or set up wireless ADB:
# List connected devices
droidrun devices
# Connect to a device over Wi-Fi
droidrun connect 192.168.1.100Verify that everything is set up correctly:
# Should list your connected device and show portal status
droidrun statusDroidRun's CLI is designed to be simple and intuitive. You can use it in two ways:
# Format: droidrun "task description" [options]
droidrun "Open the settings app"# Using OpenAI
droidrun "Open the calculator app" --provider openai --model gpt-4o-mini
# Using Anthropic
droidrun "Check the battery level" --provider anthropic --model claude-3-sonnet-20240229
# Using Gemini
droidrun "Install and open Instagram" --provider gemini --model gemini-2.0-flash# Specify a particular device
droidrun "Open Chrome and search for weather" --device abc123
# Set maximum number of steps
droidrun "Open settings and enable dark mode" --steps 20If you want to use DroidRun in your Python code rather than via the CLI, you can create a minimal test script:
#!/usr/bin/env python3
import asyncio
import os
from droidrun.agent.react_agent import ReActAgent
from droidrun.agent.llm_reasoning import LLMReasoner
from dotenv import load_dotenv
# Load environment variables from .env file
load_dotenv()
async def main():
# Create an LLM instance (choose your preferred provider)
llm = LLMReasoner(
llm_provider="gemini", # Can be "openai", "anthropic", or "gemini"
model_name="gemini-2.0-flash", # Choose appropriate model for your provider
api_key=os.environ.get("GEMINI_API_KEY"), # Get API key from environment
temperature=0.2
)
# Create and run the agent
agent = ReActAgent(
task="Open the Settings app and check the Android version",
llm=llm
)
steps = await agent.run()
print(f"Execution completed with {len(steps)} steps")
if __name__ == "__main__":
asyncio.run(main())Save this as test_droidrun.py, ensure your .env file has the appropriate API key, and run:
python test_droidrun.pyIf you encounter errors about missing API keys, ensure:
- You've set the correct environment variable for your chosen provider
- The API key is valid and has appropriate permissions
- You've correctly sourced your
.envfile or exported the variables manually
If you have trouble connecting to your device:
- Ensure USB debugging is enabled on your Android device
- Check that your device is recognized by ADB:
adb devices - For wireless connections, make sure your device and computer are on the same network
If DroidRun is using the wrong LLM provider:
- Explicitly specify the provider with
--provider(in CLI) orllm_provider=(in code) - When using Gemini, ensure you have set
GEMINI_API_KEYand specified--provider gemini
-
Shopping Assistant: Watch how DroidRun searches Amazon for headphones and sends the top 3 products to a colleague on WhatsApp.
Prompt: "Go to Amazon, search for headphones and write the top 3 products to my colleague on WhatsApp."
-
Social Media Automation: See DroidRun open X (Twitter) and post "Hello World".
Prompt: "Open up X and post Hello World."
- Automated UI testing of Android applications
- Creating guided workflows for non-technical users
- Automating repetitive tasks on Android devices
- Remote assistance for less technical users
- Exploring Android UI with natural language commands
- Improve memory: Enhance context retention for complex multi-step tasks
- Improve vision capabilities: Better UI element recognition and visual feedback interpretation
- Add Integrations: Support more LLM providers and agent frameworks (LangChain, Agno etc.)
- Create Automation Scripts: Generate reusable scripts from agent actions that can be scheduled or shared
- Hosted version: Remote device control via web interface without local setup
- Add-Ons: Marketplace for extensions serving specific use cases
- Proxy Hours: Cloud compute time with tiered pricing for running automations
- Droidrun AppStore: Simple installation of Apps on your hosted devices
Contributions are welcome! Please feel free to submit a Pull Request.
This project is licensed under the MIT License - see the LICENSE file for details.