Quickstart with Docker

This guide will help you get Mobilerun 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.

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.
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.
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
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/mobilerun:latest

Before running the container, note that the following options are always required when launching Mobilerun in Docker:

Docker option	What it does	Why it matters for Mobilerun
`--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 Mobilerun 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 Mobilerun to discover and interact with the phone.
`--volume ~/.android:/home/mobilerun/.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, Mobilerun doesn’t prompt for it again inside the container.

The Docker image uses the mobilerun 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/mobilerun/.android \
  ghcr.io/droidrun/mobilerun:latest \
  <mobilerun command>

Set Up 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/mobilerun/.android \
  ghcr.io/droidrun/mobilerun: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/mobilerun/.android \
  ghcr.io/droidrun/mobilerun: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/mobilerun/.android --env GOOGLE_API_KEY=your-api-key-here ghcr.io/droidrun/mobilerun: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/mobilerun/.android --env OPENAI_API_KEY=your-api-key-here ghcr.io/droidrun/mobilerun:latest run "Open a browser and search for mobilerun" -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/mobilerun/.android --network host ghcr.io/droidrun/mobilerun:latest run "Open a browser and search for mobilerun" -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 - Dive into the various parameters and start building your own projects with Docker!

Introduction

Features

Guides

Concepts

SDK Reference

Quickstart with Docker

Host configuration

Usage

Set Up the Portal APK

Verify the setup

Run some agents

Troubleshooting

Next Steps

​Host configuration

​Usage

​Set Up the Portal APK

​Verify the setup

​Run some agents

​Troubleshooting

​Next Steps

Host configuration

Usage

Set Up the Portal APK

Verify the setup

Run some agents

Troubleshooting

Next Steps