redroid-doc: running Android in a Docker container with GPU acceleration

What redroid replaces, and for whom

redroid is an Android-in-Cloud solution: it boots Android system images as containers on a Linux host rather than inside a virtual machine or a desktop emulator. The README describes it as GPU accelerated and multi-arch, supporting both arm64 and amd64, and lists Cloud Gaming, virtualised phones and automation testing as the intended uses. The unit of deployment is a container image, so the same workflow applies whether the orchestrator is Docker, podman or k8s.

The practical audience is infrastructure engineers who need many Android instances on one machine and want to manage them with the tooling they already use for other services. The project publishes images for Android 8.1 through Android 16, including 64bit-only variants from Android 12 onward. That range matters for compatibility testing: an app that only reproduces a bug on Android 10 can be pinned to the 10.0.0-latest tag instead of hoping a newer runtime behaves the same.

The trade-off is that redroid is not a consumer emulator. There is no bundled window, no snapshot UI, and no vendor support contract. You get a container that speaks adb, and you supply the display, the networking and the lifecycle management.

How a redroid container boots Android on the host kernel

The mechanism is kernel sharing. redroid does not emulate a device; the container runs Android userspace directly against the host Linux kernel, which is why the Getting Started section insists on installing the kernel modules first. The README's Ubuntu 20.04 example installs linux-modules-extra for the running kernel, then loads binder_linux with the device names binder, hwbinder and vndbinder, and loads ashmem_linux. Without those, the container exits immediately, which the troubleshooting section confirms as the first thing to check.

Because the container needs to create and mount those kernel interfaces, it runs with --privileged. The README is explicit about the second consequence: the adb port must not be exposed on a public network, or the container and possibly the host OS may be compromised. Anyone evaluating redroid for a shared cluster should treat that warning as part of the architecture, not a footnote.

Configuration is passed as kernel command line arguments after the image name, prefixed androidboot. The README documents display width, height, FPS and DPI, networking entries for DNS and HTTP proxies, and a gpu_mode switch with auto, host and guest values. Guest means software rendering; host means GPU accelerated rendering; auto detects. The default is guest, so a deployment that never sets gpu_mode is not using the GPU path the project advertises. The README also documents a use_redroid_overlayfs option that splits /data-base as a shared partition and /data-diff as private data, which is how several instances can start from one base image without duplicating it.

Installing redroid and connecting adb for the first time

The README targets any Linux distribution with the required kernel features, and points to the deploy directory for distributions other than Ubuntu 20.04. Docker itself is a prerequisite; the README links to Docker's own server install instructions rather than packaging one. After Docker is present, install the extra kernel modules and load the two redroid needs:

apt install linux-modules-extra-`uname -r`
modprobe binder_linux devices="binder,hwbinder,vndbinder"
modprobe ashmem_linux

If modprobe returns an error, stop here. The container will not stay up, and dmesg -T is the log the README tells you to read. When the modules load, start an instance. The flags below pull the newest image, mount a host directory as the data partition, and publish the adb port:

docker run -itd --rm --privileged \
    --pull always \
    -v ~/data:/data \
    -p 5555:5555 \
    redroid/redroid:12.0.0_64only-latest

Then connect from a machine that has adb installed. The README notes that localhost becomes the host's IP when redroid runs remotely:

adb connect localhost:5555

A successful connection shows the device as available. To see the screen, the README uses scrcpy against the same address: scrcpy -s localhost:5555. Display geometry is set by appending androidboot arguments after the image name, for example androidboot.redroid_width=1080, androidboot.redroid_height=1920 and androidboot.redroid_dpi=480. Those values replace the defaults of 720 by 1280 at 320 DPI.

The GPU, native bridge and GMS questions

Three capabilities are commonly assumed to be built in and are not. GPU acceleration depends on androidboot.redroid_gpu_mode being set to host or auto, with androidboot.redroid_gpu_node available to pin a specific device; the default of guest means software rendering, and the README's own FPS table reflects that, listing 30 FPS with GPU enabled and 15 without. If your workload is video or game streaming, leaving the default in place silently halves the frame budget.

Running arm applications on an x86 instance requires a translation layer. The README names libhoudini, libndk_translation and a QEMU translator, says published redroid images already include libndk_translation, and shows a Dockerfile pattern of ADD native-bridge.tar / on top of a redroid base image for cases where you supply the bridge yourself. The README warns that file owner and mode matter in that tree, which is the kind of detail that costs an afternoon when it is wrong.

GMS is not shipped. The README lists Open GApps, MicroG and MindTheGapps as ways to add it and points to the android-builder-docker directory for the build. For a test fleet that does not need Play services, this is a benefit: no Google binaries, no licensing question. For a virtual-phone product, it is a build step you own.

WebRTC streaming is listed as a plan, not a feature: the README says the intent is to port solutions from cuttlefish, including an HTML5 frontend, a backend and virtual HALs. Do not plan around it today.

Where redroid is the wrong choice

The privileged container requirement is the hard boundary. On a managed Kubernetes cluster that forbids privileged pods, or a host where you cannot load out-of-tree kernel modules, redroid does not degrade gracefully; the container disappears. The README's own troubleshooting entry for that symptom points back to the kernel modules, which tells you how common the failure is.

Kernel coupling is the second constraint. Because the Android userspace runs against the host kernel, the host distribution and kernel version are part of your compatibility surface. The README says redroid should run on any Linux distribution with the right features and offers a deploy directory for other distributions, but that is a statement about intent, not a support matrix. A rolling-release host that upgrades its kernel underneath a running fleet is a risk you carry.

Finally, if you need a graphical emulator with snapshots, a device manager and commercial support, redroid is the wrong shape. It gives you adb and a container. Everything above that, including how users reach the screen, is yours to build.

How redroid differs from a desktop Android emulator

The obvious alternative is a desktop emulator such as the Android Emulator shipped with the SDK. The difference is architectural: the emulator runs a guest kernel inside a virtual machine and virtualises hardware, so it can present a self-contained device with a window, snapshots and a virtual GPU, all without touching the host kernel. redroid skips the guest kernel and runs Android userspace on the host, which is why it starts faster per instance and why it needs binder and ashmem on the host. One model trades host coupling for isolation; the other trades isolation for density and orchestration fit.

That distinction drives the choice. If you need dozens of Android instances managed by the same scheduler as your other services, and you own the hosts, redroid's model fits. If you need a reproducible device on a developer laptop with no kernel changes and no privileged containers, the VM-based emulator fits better, and redroid will fight you.

Within the container world, the alternative to redroid is building your own Android container from AOSP. The README points at android-builder-docker for exactly that, noting the build follows the AOSP process and suggesting Docker for it. That path gives you control over every module but makes you responsible for the images, the native bridge and the release cadence that redroid's published tags provide.

Maintenance, licensing and the cost of upgrading

The repository is not archived, and its last push was on 2026-05-17. There are no releases in the repository; distribution happens through Docker image tags such as redroid/redroid:15.0.0-latest, so upgrades are image pulls rather than package version bumps. The --pull always flag in the README's run command makes that explicit, and it also means an unpinned deployment can change under you. Pinning to a specific tag is the only way to make a fleet reproducible.

The upgrade cost is not only the image. The androidboot parameters are the interface between your deployment configuration and the image, and the README marks use_memfd as a planned default change. A parameter that is optional today can become the default later, so configuration files deserve a review at each Android version bump. Native bridge contents and GMS integration, if you added them, are rebuilt per version.

On licensing, the README states that redroid itself is under the Apache License, that the kernel modules are under GPL v2, and that because redroid includes many third-party modules you may need to examine licenses carefully. That last sentence is the operative one: the project is telling you the aggregate image is not uniformly Apache-2.0, and the README does not enumerate the third-party components. Anyone shipping redroid inside a product should inventory the image contents rather than rely on the top-level license line. This is a description of what the documentation says, not legal advice.

Editorial conclusion

Adopt redroid if you control the Linux host kernel, can run privileged containers, and need many Android instances on servers for cloud gaming, virtual phones or automation. Do not adopt it if you cannot install binder_linux and ashmem_linux on the host, cannot grant --privileged, or need a desktop emulator with a GUI and a support contract. Before committing, verify three things on your own hardware: that modprobe binder_linux devices="binder,hwbinder,vndbinder" succeeds on your kernel, that adb connect localhost:5555 reports a device rather than offline, and that your chosen androidboot.redroid_gpu_mode value actually changes rendering on your GPU node.

Frequently asked questions

Official sources

1. Issues
2. README
3. remote-android/redroid-doc on GitHub