mirror of
https://github.com/droidrun/droidrun.git
synced 2026-05-23 07:40:37 +00:00
johnmalek312
be0048196a
Remove v3, v4, and v5 directories. Move latest (v5) docs to docs root. Update docs.json navigation to use flat tabs instead of versioned layout. Fix all internal links to use unversioned paths.
142 lines
6.0 KiB
Plaintext
142 lines
6.0 KiB
Plaintext
---
|
||
title: 'Quickstart with Docker'
|
||
description: 'Get up and running with Droidrun in Docker quickly and effectively'
|
||
---
|
||
|
||
This guide will help you get Droidrun running in a Docker container, controlling your Android device through natural language without installing it natively.
|
||
|
||
### Host configuration
|
||
|
||
Follow the steps below to ensure your host system is properly configured to mount the smartphone inside the container.
|
||
|
||
1. Make sure you’ve completed the prerequisite steps in the [Quickstart](/quickstart). Then verify the ADB connection with `adb devices`. This should list your phone as “device” along with its Serial Number. If the phone appears as `unauthorized` make sure to accept the prompt on your phone.
|
||
|
||
2. Confirm that the ADB keys have been correctly created. Check for an `.android` folder under your `$HOME` directory that contains: `adb.5037`, `adbkey`, and `adbkey.pub`.
|
||
|
||
3. Set up a custom rule to uniquely identify your phone and map it to a static path:
|
||
- Open a terminal and find your device’s `idVendor` and `idProduct` using the `lsusb` command.
|
||
|
||
In the example below, the `idVendor` and `idProduct` are `18d1` and `4ee2`, respectively.
|
||
|
||
```bash
|
||
> lsusb
|
||
Bus 003 Device 002: ID 18d1:4ee2 Google Inc. Nexus/Pixel Device (MTP + debug)
|
||
```
|
||
|
||
- Create a new file (sudo may be required) under `/etc/udev/rules.d` and name it `51-android.rules`.
|
||
|
||
- Add the following content and save the file:
|
||
|
||
```bash
|
||
SUBSYSTEM=="usb", ATTR{idVendor}=="XXXX", ATTR{idProduct}=="YYYY", ATTR{serial}=="SSSS", MODE="0666", GROUP="plugdev", SYMLINK+="phone1/phone"
|
||
```
|
||
|
||
where `XXXX`, `YYYY`, and `SSSS` are the vendor ID, product ID, and serial number of your phone.
|
||
|
||
This static mapping is required because otherwise the phone’s mount path will change across reconnections!
|
||
|
||
- Reload the rules
|
||
|
||
```bash
|
||
sudo udevadm control --reload-rules
|
||
sudo udevadm trigger
|
||
```
|
||
|
||
4. Kill the ADB server on the host so that the container can actually detect the phone:
|
||
|
||
```bash
|
||
adb kill-server
|
||
```
|
||
|
||
### Usage
|
||
|
||
Pull the image from the GitHub Container Registry:
|
||
|
||
```bash
|
||
docker pull ghcr.io/droidrun/droidrun:latest
|
||
```
|
||
|
||
Before running the container, note that the following options are always required when launching Droidrun in Docker:
|
||
|
||
| Docker option | What it does | Why it matters for Droidrun |
|
||
|---------------|--------------|-----------------------------|
|
||
| `--group-add plugdev` | Adds the host user to the container’s `plugdev` group. | Gives the container permission to access USB devices (e.g., your Android phone) without requiring root. |
|
||
| `--device /dev/phone1/phone:/dev/phone` | Maps a specific USB device file from the host into the container. Thanks to our udev rule, the phone will always be mapped here. | Allows Droidrun to see the phone as `/dev/phone` inside the container, so it can communicate with the device. |
|
||
| `--volume /dev/bus/usb:/dev/bus/usb` | Mounts the entire USB bus directory. | Provides access to all connected USB devices, enabling Droidrun to discover and interact with the phone. |
|
||
| `--volume ~/.android:/home/droidrun/.android` | Mounts the host’s Android configuration directory into the container. | Stores ADB keys and settings so that once you grant permission on the host, Droidrun doesn’t prompt for it again inside the container. |
|
||
|
||
The Docker image uses the `droidrun` entrypoint, which means you can use any of the CLI commands described in the [CLI Usage](/guides/cli) section and append it to the following base 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>
|
||
```
|
||
|
||
#### Set Up the Portal APK
|
||
|
||
Simply run the container with the `setup` CLI 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 \
|
||
setup
|
||
```
|
||
|
||
#### Verify the setup
|
||
|
||
Simply run the container with the `ping` CLI 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 \
|
||
ping
|
||
```
|
||
|
||
#### Run some agents
|
||
|
||
Now you’re ready to control your device using Docker and natural language:
|
||
|
||
```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"
|
||
|
||
# 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
|
||
|
||
# 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
|
||
```
|
||
|
||
#### Troubleshooting
|
||
|
||
* Error response from daemon
|
||
|
||
If you encounter the following error:
|
||
|
||
```
|
||
docker: Error response from daemon: error gathering device information while adding custom '/dev/phone1/phone': no such file or directory
|
||
```
|
||
|
||
it usually indicates one of two things:
|
||
- The phone isn’t mounted at the expected custom path. Verify that `/dev/phone1/phone` exists.
|
||
- An ADB server is still running on the host. Stop it with `adb kill-server`.
|
||
|
||
---
|
||
|
||
## Next Steps
|
||
|
||
- [CLI Usage](/guides/cli) - Dive into the various parameters and start building your own projects with Docker!
|