Boxes in containers

Redroid is Android running as a Docker container on a Linux host. Magnemite treats one container as one box: it enrolls, heartbeats, takes rollouts and installs real APKs, all through the same agent and the same protocol as a TV box on a shelf.

This is not the fake fleet. A fake box is a Go process on your laptop wearing an Android costume, with pm and dumpsys stubbed out. A Redroid box is Android — pm install-create genuinely installs.

This page is the image and the container: what to build, what to pass it, and what a box can and cannot see from inside one. The Linux machine underneath is itself a device in Magnemite — see The machines that run them for what it reports, what the Machines screens say, and the traps that belong to the host rather than to the box.

What Magisk was actually forCopy Anchor Link

Nothing in the agent binary needs Magisk. It never shells out to su and never checks whether it is root; it assumes it was started as root and would fail at the first pm call if it were not. Magisk supplies exactly three things, all of them in service.sh: start the agent as root, wait for sys.boot_completed, restart it when it exits.

Android's own init does all three. So the container equivalent of the module zip is an init service — agent/redroid/magnemite.rc — and a start script that does what customize.sh did at flash time.

Host requirementsCopy Anchor Link

• arm64. The fleet's bundles carry an arm64-v8a split and the agent matches the ABI exactly, refusing to install the wrong native libraries. An x86_64 Redroid needs ARM translation and a different split policy; it is not a supported target.
• The binder kernel module, with the device names Android expects — and the devices openable by somebody other than root:

sudo modprobe binder_linux devices="binder,hwbinder,vndbinder"
sudo chmod 0666 /dev/binder /dev/hwbinder /dev/vndbinder
# kernels older than 5.18 also want:
sudo modprobe ashmem_linux

Build the imageCopy Anchor Link

make redroid
# → magnemite/redroid:5

Unlike make module, this takes no SERVER and no TOKEN. The image holds no secret, so one image serves every fleet — the hub URL and the enrollment token are properties passed to each container at run time.

What the image fixes that a container cannot fix for itselfCopy Anchor Link

Three of them, and all three were found the hard way: each one leaves a scanner that is running, reported healthy, and doing nothing at all. They are listed in the order they bite, and the third hides behind the second — a granted root that the app can never ask for looks exactly like no grant.

• A su an app can reach. --setup-sbin puts Magisk's applets in /sbin, and /sbin is not on the PATH the zygote gives apps. What is on it is the base image's own stub at /system/xbin/su, mode -rwsr-x--- root shell — executable by uid 0 and the shell group, and by no app. So exec("su") dies with EACCES before Magisk is involved: magiskd logs no request and SELinux logs no denial, and the scanner falls back to an unprivileged shell that cannot traverse /data/adb (0700, root). The image ships /system/bin/su as a symlink to the binary, and /system/bin comes before /system/xbin, so it wins the lookup without replacing the base's file. The prerooted base this replaced had Magisk inside /system already, which is why this only appeared once the injection became ours.

• Magisk's busybox. The scanner's injector calls /data/adb/magisk/busybox by absolute path, and this base image gives root without ever putting one there — that directory is empty on a fresh box. The image carries Magisk's own build and the start script seeds it into /data, which is a volume and therefore survives nothing the image does. It is checked by applet, not by existence, because the two obvious substitutes both exist and neither works: a symlink to Android's toybox answers Unknown command busybox, and Debian's busybox-static is built without pgrep.

• The root grant. Magisk keys its su policy on the uid, Android gives a package a new uid when it is installed fresh rather than updated, and a request nobody answers times out as a deny that is then written down. On hardware a person taps Grant; a container has no screen. So every rollout that reinstalls the scanner revokes its root, and the agent reconciles the policy after each install — only where the image ships /system/bin/magnemite-root-grant, which is nowhere else.

  The same uid change happens on hardware, and nothing here fixes it: an install that falls back to uninstall-and-reinstall is just as unattended there, and a Magisk module ships no helper to reconcile with. The difference is only that a box with a screen can be answered — by somebody who knows to.

The tag comes from the redroid= line of VERSION, and deliberately not from the agent's. The agent inside is only a seed that each box's own self-update replaces, so a tag that moved with every agent release would change the image: line and have Docker recreate every container on the machine — a full Android cold boot each, to deliver a binary the boxes would have swapped in seconds on their own. Bump redroid= when the base image, the start script or the init service changes.

The base image is redroid/redroid:12.0.0_64only-latest — the official image, and 64-bit only. Magisk is not inherited from it; the build injects it, pinned to one version.

Both values live as ARG defaults in the Dockerfile and nowhere else, which is also how you change them. The bootstrap builds this image on each machine with a plain docker build and no --build-arg, so the Dockerfile's defaults are what the whole fleet gets; a second default in the Makefile could drift from it and give one tag two meanings depending on who ran the build. make redroid REDROID_BASE=… MAGISK_VERSION=… still overrides either one for an experiment.

Why 64-bit onlyCopy Anchor Link

An arm64 Android normally ships two zygotes, and the 32-bit one needs AArch32, which Arm has been removing generation by generation. Neoverse N1 and V1 (Ampere Altra, Graviton 2 and 3) still have it at EL0; Neoverse V2 and V3 (Graviton 4 and 5, Google Axion, NVIDIA Grace) and every Apple Silicon do not. There the 32-bit zygote cannot start, and the symptom is a container that runs with an Android that never finishes booting — an instance left running, not enrolled, which reads like a network fault and is not one.

Nothing is lost by dropping it. The fleet's .apkm bundles carry an arm64-v8a split and the agent picks a split by exact ABI match, so no 32-bit runtime was ever used by anything here. The _64only variants begin at Android 12, which is why the base is 12 and not 11.

Why Magisk is injected rather than inheritedCopy Anchor Link

The base used to be abing7k/redroid:a11_magisk_arm, prerooted, and that was a dead end: it carries Magisk Delta 25206 canary from a 2023 androidfilehost mirror, Delta's own repositories are gone from GitHub, and the repo that built it says it is no longer maintained. Nobody can rebuild that image, its author included.

So the injection is ours, and it is the same one ayasa520/redroid-script performs — the script abing7k forked, still maintained, and the source of every line of the init block in the Dockerfile. Bootless Magisk is a handful of binaries under /system/etc/init/magisk plus a hook appended to bootanim.rc, so doing it in the image keeps provisioning to one docker build on the machine: no Python, no lzip, nothing fetched from a third party while a machine is being set up.

The apk comes from ayasa520/Magisk — the script's own source for it, and not topjohnwu/Magisk. That is load-bearing rather than incidental, and it is the one thing to understand before bumping MAGISK.

The apk's md5 is pinned beside the version, so a release that moves or an owner changed by hand fails the build instead of the fleet. Trying another version means moving both, or MAGISK_MD5= empty to skip the check.

Run the boxesCopy Anchor Link

Set two values in .env:

REDROID_HUB_URL=https://magnemite.example.com
REDROID_ENROLL_TOKEN=…

docker compose --env-file .env -f deploy/redroid.compose.yml up -d

Each box is one service. The shipped file has two; a third is that block copied with a new name, a new volume and a new serial.

The serial is the whole identityCopy Anchor Link

The hub keys a device on its serial string and nothing else. A box that reports a new serial is a new box, with a new row, a new name and no history.

A container has no ro.serialno of its own, and the agent's fallback is the first MAC it finds — which Docker reassigns every time the container is recreated. Left alone, every docker compose up --force-recreate would fill the Devices table with duplicates.

Reboot means something differentCopy Anchor Link

A container has no kernel of its own to restart — it shares the host's, and the kernel refuses reboot(2) without CAP_SYS_BOOT. Killing pid 1 from inside does not work either: the kernel ignores signals a process in its own PID namespace sends to its pid 1.

So ro.magnemite.reboot_cmd=stop && start restarts the framework instead: zygote and every app come back, init and the kernel do not move. That is what a monitoring rule with a REBOOT action actually wants — the scanner and the game running again.

The hub's reboot button and every REBOOT rule run this command. It is a property, so a fleet whose image handles reboots differently changes it without rebuilding anything.

Which metrics are realCopy Anchor Link

Boxes sharing a host therefore show identical load and temperature. That is correct, not a bug — but do not write a monitoring rule that reads either as one box's own state. A probe that greps /proc/loadavg fails on every box on the machine at once, for one cause; the host page explains why that is unfixable in code.

Self-updates still workCopy Anchor Link

Exactly as on hardware: the hub sends agent_update, the box downloads with its own device token, verifies the sha256, keeps .old and re-execs.

The agent runs from /data/adb/magnemite/magnemite-agent, not from /system/bin — /system is read-only at runtime, so an agent running from there could never replace itself. The image ships a seed copy in /system/bin, and magnemite-start.sh copies it across on first boot.

A version marker keeps the two from fighting: an over-the-air update survives a docker restart, and rebuilding the image raises the floor for every box.

When a box does not appearCopy Anchor Link

Everything here is docker, not adb. The compose file publishes no port at all — no 5555, nothing — so adb connect <host>:5555 cannot work and never could; it connects to nothing and tells you the host is unreachable, which is not what is wrong. docker exec needs no port and no daemon inside the box.

1. Is the container even up? docker compose -f deploy/redroid.compose.yml ps. A container that is restarting is a boot failure, not an agent failure, and the next step is where it says why.
2. What did Android say on the way up? docker logs magnemite-box-01 — the container's stdout is init's, which is where a missing binder device or a failed mount shows up.
3. Did the service start? docker exec magnemite-box-01 sh -c 'ps -A | grep magnemite-agent'. It should be there, as root.
4. What did the agent say? docker exec magnemite-box-01 logcat -b all -d | grep -i magnemite, and docker exec magnemite-box-01 cat /data/adb/magnemite/agent.log.
5. SELinux. Redroid normally runs permissive, and magnemite.rc sets no seclabel for that reason. An image that enforces will deny the service; the denial is in logcat.
6. A duplicate row per restart is the serial. See above.