mirror of
https://github.com/droidrun/droidrun.git
synced 2026-05-23 07:40:37 +00:00
johnmalek312
171 lines
4.7 KiB
Plaintext
171 lines
4.7 KiB
Plaintext
---
|
|
title: 'Quickstart'
|
|
description: 'Get up and running with Droidrun quickly and effectively'
|
|
---
|
|
|
|
<iframe
|
|
className="w-full aspect-video rounded-xl"
|
|
src="https://www.youtube.com/embed/4WT7FXJah2I"
|
|
title="YouTube video player"
|
|
frameBorder="0"
|
|
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
|
|
allowFullScreen
|
|
></iframe>
|
|
|
|
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.11-3.13** installed on your system
|
|
2. [Android Debug Bridge (adb)](https://developer.android.com/studio/releases/platform-tools) installed and configured
|
|
3. **Android device** with:
|
|
- [Developer options enabled](https://developer.android.com/studio/debug/dev-options)
|
|
- USB debugging enabled
|
|
- Connected via USB or on the same network (for wireless debugging)
|
|
|
|
### Installation
|
|
|
|
Droidrun is installed using [`uv`](https://docs.astral.sh/uv/), a fast Python package installer and resolver.
|
|
|
|
**Install uv (if not already installed):**
|
|
|
|
```bash
|
|
# macOS/Linux
|
|
curl -LsSf https://astral.sh/uv/install.sh | sh
|
|
|
|
# Windows (PowerShell)
|
|
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
|
|
```
|
|
|
|
**Choose your installation method:**
|
|
|
|
**For CLI usage only:**
|
|
```bash
|
|
uv tool install droidrun
|
|
```
|
|
|
|
**For CLI + Python code integration:**
|
|
```bash
|
|
uv pip install droidrun
|
|
```
|
|
|
|
<Note>
|
|
Most LLM providers (Google Gemini, OpenAI, Ollama, OpenRouter) are included by default. For additional providers, install extras: `uv tool install 'droidrun[anthropic,deepseek]'`.
|
|
</Note>
|
|
|
|
### Set Up the Portal APK
|
|
|
|
Droidrun requires the Portal app to be installed on your Android device for device control. The Portal app provides accessibility services that expose the UI accessibility tree, enabling the agent to see and interact with UI elements.
|
|
|
|
```bash
|
|
droidrun setup
|
|
```
|
|
|
|
This command automatically:
|
|
1. Downloads the latest Portal APK
|
|
2. Installs it on your connected device
|
|
3. Enables the accessibility service
|
|
|
|
### Test Connection
|
|
|
|
Verify that Droidrun can communicate with your device:
|
|
|
|
```bash
|
|
droidrun ping
|
|
```
|
|
|
|
If successful, you'll see:
|
|
```
|
|
Portal is installed and accessible. You're good to go!
|
|
```
|
|
|
|
### Configure Your LLM
|
|
|
|
Droidrun uses a configuration-driven approach. On first run, Droidrun creates a `config.yaml` file with default settings. You'll need to set your API key for your chosen LLM provider.
|
|
|
|
**Set your API key:**
|
|
|
|
```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
|
|
```
|
|
|
|
### Run Your First Command via CLI
|
|
|
|
Now you're ready to control your device with natural language:
|
|
|
|
```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
|
|
```
|
|
|
|
**Common CLI flags:**
|
|
- `--provider` - LLM provider (GoogleGenAI, OpenAI, Anthropic, etc.)
|
|
- `--model` - Model name (gemini-3.1-flash-lite-preview, gpt-4o, etc.)
|
|
- `--vision` - Enable screenshot processing
|
|
- `--reasoning` - Enable multi-agent planning mode
|
|
- `--steps N` - Maximum execution steps (default: 15)
|
|
- `--debug` - Enable detailed logging
|
|
|
|
### Create a Simple Agent via Script
|
|
|
|
For complex automation or integration into your Python projects, create a script:
|
|
|
|
```python
|
|
import asyncio
|
|
from droidrun import DroidAgent, DroidConfig
|
|
|
|
async def main():
|
|
# Use default configuration with built-in LLM profiles
|
|
config = DroidConfig()
|
|
|
|
# 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())
|
|
```
|
|
|
|
## Next Steps
|
|
|
|
Now that you've got Droidrun running, explore these topics:
|
|
|
|
- Walk through a [Guide](/guides/overview)
|
|
- Learn about [Agent Architecture](/concepts/architecture)
|
|
- Customize the Agent [Configuration System](/sdk/configuration)
|
|
- Guide the agent with [App Cards](/features/app-cards)
|
|
|
|
|
|
--- |