Skip to main content
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. 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. 
      > 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: 
      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 
      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: 
    adb kill-server

​
Usage

Pull the image from the GitHub Container Registry: 
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 optionWhat it doesWhy it matters for Droidrun
--group-add plugdevAdds 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/phoneMaps 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/usbMounts 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/.androidMounts 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 section and append it to the following base command: 
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>

​
Setup the Portal APK

Simply run the container with the setup CLI command. 
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. 
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: 
# 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-40

# 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 enconter 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 - Dive into the various parameters and start building your own projects with the docker!