> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mobilerun.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart with Docker

> Get up and running with Mobilerun in Docker quickly and effectively

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.

1. Make sure you’ve completed the prerequisite steps in the [Quickstart](/framework/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 theme={null}
     > 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 theme={null}
     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 theme={null}
     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 theme={null}
   adb kill-server
   ```

### Usage

Pull the image from the GitHub Container Registry:

```bash theme={null}
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](/framework/guides/cli) section and append it to the following base command:

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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:

```bash theme={null}
# 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](/framework/guides/cli) - Dive into the various parameters and start building your own projects with Docker!