An ultra-lightweight, zero-friction container image providing the Android Debug Bridge (adb) thanks to Alpine Linux.
Pre-built and ready to run with Podman or Docker on both linux/amd64 and linux/arm64 (Apple Silicon, Raspberry Pi, and x86_64).
Installing the official Android SDK command-line tools often pulls in Java runtimes, hundreds of megabytes (or gigabytes) of SDK components, and clutters your host system path.
adb-runner keeps things minimal, clean, and honest:
- Featherweight: Built directly on official Alpine Linux with only
android-tools-adb. The entire image is under 20 MB download size (compared to 500MB+ for standard Android SDK containers). - Multi-Architecture: Multi-arch builds for
linux/amd64andlinux/arm64. - Always Up-to-Date: Automated dependency tracking via Renovate continuously checks upstream Alpine repositories and rebuilds the container whenever
android-tools-adbor the Alpine base image receives an update. - Ephemeral & Clean: Mount your APKs or scripts, do what you need to do, and exit. No lingering daemons or unwanted files on your host.
- Ready for CI/CD & Local Dev: Perfect for GitHub Actions, GitLab CI, local development, wireless debugging, and sideloading APKs.
Run an interactive shell right away:
# Using Podman
podman run -it --rm ghcr.io/datf/adb-runner:latest
# Using Docker
docker run -it --rm ghcr.io/datf/adb-runner:latestMount your current host directory (containing your .apk files or scripts) into the container's working directory (/app):
# Using Podman (with SELinux ':z' flag)
podman run -it --rm -v "$(pwd):/app:z" ghcr.io/datf/adb-runner:latest
# Using Docker
docker run -it --rm -v "$(pwd):/app:z" ghcr.io/datf/adb-runner:latestYou can add an alias to your ~/.bashrc or ~/.zshrc so you can launch the container from any directory just like a native command:
# For Podman users (recommended)
alias adb-runner='podman run -it --rm -v "$(pwd):/app:z" ghcr.io/datf/adb-runner:latest'
# For Docker users
alias adb-runner='docker run -it --rm -v "$(pwd):/app:z" ghcr.io/datf/adb-runner:latest'If you prefer to build and run the image from source, a docker-compose.yml file is included:
# Clone the repository
git clone https://github.com/datf/adb-runner
cd adb-runner
# Build the image
docker compose build
# Launch the container with the current directory mounted at /app
docker compose run --rm -it adbYour current path will be mounted on /app, where all your local files will be accessible.
The base image intentionally keeps its footprint minimal by including only ADB. If you need fastboot for flashing partitions or unlocking bootloaders, you can easily install it on the fly inside the running container:
apk add --update android-tools-fastbootOr, if you build locally and want it pre-installed, simply add android-tools-fastboot to the RUN apk add instruction in Dockerfile.
Make sure your Android device and host machine are on the same network (or the host can reach the device IP):
# Inside adb-runner shell:
adb connect 192.168.1.150:5555
adb devices
adb shellPlace your APK in the directory from which you launch adb-runner (so it appears in /app):
# Inside adb-runner shell:
adb install my-app.apkTo connect to physical devices via USB cable, pass the host's USB bus devices into the container:
# Podman / Docker with USB passthrough
docker run -it --rm --privileged -v /dev/bus/usb:/dev/bus/usb -v "$(pwd):/app:z" ghcr.io/datf/adb-runner:latestThis repository uses automated dependency management powered by Renovate.
The Dockerfile pins both the Alpine base image and android-tools-adb package version:
# renovate: datasource=repology depName=alpine_3_24/android-tools-adb versioning=loose
ENV ADB_APK_VERSION="35.0.2-r21"Whenever Alpine updates the android-tools package in its official repositories, Renovate opens a pull request and the GitHub Actions release workflow builds and pushes multi-architecture images to GitHub Container Registry (ghcr.io).
A huge thank you to the Alpine Linux developers and package maintainers! Their work packaging Android platform tools (android-tools-adb, android-tools-fastboot) into clean, standalone Alpine packages makes ultra-lightweight utilities like this possible without the bloat of full SDK toolchains.
This project is free and unencumbered software released into the public domain under The Unlicense.