Skip to content

đŸŗ Running DroidMind with Docker

Docker provides a convenient way to run DroidMind in a containerized, consistent environment. This guide covers building the DroidMind Docker image and running it with various configurations.

Prerequisites

  • Docker: Ensure Docker Desktop (for Mac/Windows) or Docker Engine (for Linux) is installed and running on your system. Get Docker.
  • DroidMind Source Code: You'll need the DroidMind source code, specifically the Dockerfile, to build the image. If you haven't already, clone the repository: 
    git clone https://github.com/hyperb1iss/droidmind.git
cd droidmind

đŸ“Ļ Building the Docker Image

Navigate to the root directory of the DroidMind project (where the Dockerfile is located) and run the following command to build the image:

docker build -t droidmind:latest .

This command builds a Docker image tagged as droidmind:latest using the instructions in the Dockerfile.

āļ° Running the Docker Container

Once the image is built, you can run DroidMind as a container. The entrypoint.sh script within the Docker image handles how DroidMind starts based on environment variables and command-line arguments.

Interactive CLI (Stdio Transport - Default)

By default, the container runs DroidMind with stdio transport, ideal for direct command-line interaction if you were to exec into the container or use it as part of a script.

docker run -it --rm --name droidmind-cli droidmind:latest
  • -it: Runs the container in interactive mode with a pseudo-TTY.
  • --rm: Automatically removes the container when it exits.
  • --name droidmind-cli: Assigns a name to the container for easier management.

To pass specific arguments to droidmind when using stdio mode directly (less common for typical AI assistant use):

docker run -it --rm --name droidmind-cli droidmind:latest droidmind --your-stdio-options

To connect DroidMind with AI assistants like Claude Desktop or other MCP clients, you'll typically use the SSE (Server-Sent Events) transport. The entrypoint.sh script is designed to facilitate this.

Using the DROIDMIND_TRANSPORT Environment Variable (Recommended):

This is the easiest way to run in SSE mode. The entrypoint script will automatically configure DroidMind to listen on 0.0.0.0 inside the container.

docker run -d -p 4256:4256 -e DROIDMIND_TRANSPORT=sse --name droidmind-server droidmind:latest
  • -d: Runs the container in detached mode (in the background).
  • -p 4256:4256: Maps port 4256 of the container to port 4256 on your host machine. This allows your AI assistant (running on the host) to connect to DroidMind (running in the container).
  • -e DROIDMIND_TRANSPORT=sse: Tells the entrypoint script to start DroidMind in SSE mode.
  • --name droidmind-server: Assigns a name to the container.

Your AI assistant can then connect to sse://localhost:4256/sse (or sse://<your-host-ip>:4256/sse if connecting from a different machine on your network).

Overriding the Command for SSE:

You can also explicitly specify all DroidMind arguments:

docker run -d -p 4256:4256 --name droidmind-server droidmind:latest droidmind --transport sse --host 0.0.0.0 --port 4256

This command tells DroidMind to use SSE transport and listen on all interfaces (0.0.0.0) within the container on port 4256.

🔌 Connecting to ADB Devices

For DroidMind in Docker to control your Android devices, the container needs access to an ADB server that can see your devices. This is the most complex part of using DroidMind with Docker.

1. Networked ADB Devices (Recommended for Docker)

This is the most straightforward method for Docker setups.

  • Enable ADB over TCP/IP on your Android device(s):
  • Connect your device via USB to your host machine.
  • Find your device's IP address (usually in Settings > About phone > Status > IP address).
  • Run adb tcpip 5555 (or another port if you prefer).
  • Disconnect the USB cable.
  • Run adb connect <device_ip_address>:5555 from your host machine to confirm it works.
  • Ensure your Docker container's network configuration allows outbound connections to your device's IP address on your local network. If you're using default Docker networking (bridge), this usually works out of the box as long as your host firewall isn't blocking it.
  • Once DroidMind is running in the container, you can use its connect_device tool (via your AI assistant) to connect to <device_ip_address>:5555.

2. USB-Connected ADB Devices (Advanced)

Connecting to USB devices from within a Docker container is platform-dependent and can be challenging.

  • Option A: Use the Host's ADB Server (More Common) The idea is to make the Docker container use the ADB server already running on your host machine.

  • Linux: You might share the host's network: docker run --network host .... This gives the container direct access to the host's network interfaces, including the ADB server. Note: --network host has security implications.

  • macOS/Windows: Docker Desktop runs in a virtual machine, making direct host ADB server access trickier. You might need to forward the ADB server port (default 5037) from the host to the Docker VM or container, or use solutions that share the ADB server socket if available for your Docker version.

  • You might need to set the ADB_SERVER_SOCKET environment variable inside the container to point to the correct socket (e.g., tcp:host.docker.internal:5037 if you can forward the port, or a mounted socket path).

  • Option B: Run an ADB Server Inside the Container (More Complex) This involves passing USB device access into the container and running an ADB server within it.

  • This often requires running the container in --privileged mode, which has significant security implications.
  • You'd need to mount the USB device bus, e.g., -v /dev/bus/usb:/dev/bus/usb (Linux specific).
  • The DroidMind Docker image includes android-sdk-platform-tools, so an ADB server can be started inside it. However, making this server see host-connected USB devices is the main challenge.

✨ Recommendation: For ease of use with Docker, connecting your Android devices via ADB over TCP/IP is strongly recommended. It avoids the complexities of USB passthrough and host ADB server sharing.

⚙ī¸ Customizing DroidMind Arguments

You can append DroidMind-specific arguments to your docker run command. The entrypoint.sh script is designed to pass these along to the droidmind executable.

  • If DROIDMIND_TRANSPORT is set (e.g., to sse): The script will inject --transport sse --host 0.0.0.0 --port 4256 (or the value of DROIDMIND_PORT if set). You can still add other DroidMind arguments.

Example: Run with SSE (handled by env var), a custom ADB path, and debug mode:

docker run -d -p 4256:4256 \
  -e DROIDMIND_TRANSPORT=sse \
  -e ADB_SERVER_SOCKET=tcp:host.docker.internal:5037 \ # Example for host ADB on Mac/Win
  --name droidmind-custom-sse \
  droidmind:latest droidmind --adb-path /custom/adb --debug
  • If DROIDMIND_TRANSPORT is NOT set: The script assumes you will provide all necessary arguments, including --transport if you don't want stdio.

Example: Explicitly specify all options for SSE on a different port:

docker run -d -p 8000:8000 \
  --name droidmind-explicit-sse \
  droidmind:latest droidmind --transport sse --host 0.0.0.0 --port 8000 --log-level DEBUG

📜 Viewing Logs

If you're running DroidMind in detached mode (-d), you can view its logs (output to stdout/stderr in the container) using:

docker logs <container_name_or_id>

For example:

docker logs droidmind-server

To follow the logs in real-time:

docker logs -f droidmind-server

✅ Next Steps

  • Quick Start Guide: Learn how to connect DroidMind (whether running in Docker or locally) to your AI assistant.
  • User Manual: Explore all the features DroidMind offers.