Forem: Ai2th

Linxr | Part 4 — Test Results

Ai2th — Mon, 09 Mar 2026 17:05:50 +0000

Test Results

Part 4 of 4 — the final chapter of building Linxr, a single APK that runs Alpine Linux on non-rooted Android.
← Part 3: SSH Terminal in Flutter

Download

linxr-v1.apk — v1.0 · ARM64 · 63 MB

Requires Android 8.0+ (API 26), ARM64 device. Enable "Install from unknown sources" before sideloading.

How We Test

Testing on a Mac with an Android emulator doesn't work — QEMU inside an emulator needs nested virtualisation, which isn't available.

We use Firebase Test Lab with an automated Robo test:

Setting	Value
Device	Pixel 2 (arm64)
Android version	11 (API 31)
Test type	Robo (automated UI crawler)
Timeout	600 seconds

Test Result: Pass ✅

→ Full test results

No crashes. Key events from the logcat:

01:29:38  VmManager: startVm()
01:29:38  VmManager: Reusing existing user.qcow2
01:29:38  VmManager: VM process launched

01:29:43  QEMU: OpenRC 0.52.1 is starting up Linux 6.6.14-0-virt (aarch64)
01:29:51  QEMU: * eth0 ... [ ok ]
01:29:52  QEMU: * Starting sshd ... [ ok ]
01:29:52  QEMU: Welcome to Alpine Linux 3.19

From QEMU launch to sshd ready: ~14 seconds.

What the Robo Test Found

The crawler navigated all three tabs — Home, Terminal, About — and exercised the Start VM / Stop VM flow. It found and read through the full open-source component list in the About screen: dartssh2, xterm, QEMU, Alpine, OpenSSH.

No crashes. No ANRs. No unexpected states.

What Works

✅ Install APK → tap Start VM → Alpine boots in ~14 seconds
✅ sshd starts automatically; built-in terminal auto-connects
✅ Persistent overlay — state survives VM restarts
✅ Internet access — apk add works inside the VM
✅ No root. No Termux. No PC required after install.
✅ Foreground service keeps VM alive when app is backgrounded

Current Limitations

Limitation	Notes
ARM64 only	QEMU binary targets `aarch64` only
Password auth	SSH key setup requires manual `~/.ssh/authorized_keys`
No GUI	Text terminal only
APK size 63 MB	Alpine disk image + QEMU + 50 shared libraries

What's Next

[ ] SSH key management from the app UI
[ ] Configurable RAM and vCPU in settings
[ ] File transfer (SCP/SFTP) from the app
[ ] ARM32 / x86_64 support

The Full Series

Linxr Series — Alpine Linux on Android

Linxr = Linux + r. A single Android APK that runs a full Alpine Linux shell on any Android phone — no root, no Termux, no PC required.

#	Post	Topic
📖	Intro	What is Linxr? Start here
1	Part 1	The Idea and Architecture
2	Part 2	Shipping QEMU in an APK
3	Part 3	SSH Terminal in Flutter
4	Part 4	Test Results

GitHub: github.com/AI2TH/Linxr
Website: ai2th.github.io

Contributor: Kalvin Nathan
skalvinnathan@gmail.com · LinkedIn

Linxr | Part 3 — SSH Terminal in Flutter

Ai2th — Mon, 09 Mar 2026 17:03:29 +0000

SSH Terminal in Flutter

Part 3 of 4 — building Linxr, a single APK that runs Alpine Linux on non-rooted Android.
← Part 2: Shipping QEMU in an APK

The Goal

Once Alpine boots and sshd starts, the app needs a usable terminal — without requiring an external SSH client.

Two Flutter packages make this possible:

Package	Role
`dartssh2`	Pure-Dart SSH2 client — connects to the VM's sshd
`xterm`	Terminal emulator widget — renders VT100/xterm sequences

Both are pure Dart. No platform channels, no native code, no extra Android permissions.

Connecting to the VM

final socket = await SSHSocket.connect('127.0.0.1', 2222)
    .timeout(const Duration(seconds: 10));

_client = SSHClient(
    socket,
    username: 'root',
    onPasswordRequest: () => 'alpine',
);

_session = await _client!.shell(
    pty: SSHPtyConfig(
        type: 'xterm-256color',
        width: _terminal.viewWidth,
        height: _terminal.viewHeight,
    ),
);

SSHPtyConfig allocates a pseudo-terminal with xterm-256color — enabling colour output, cursor movement, and correct TERM variable.

Wiring SSH to the Terminal

// VM output → terminal display
_session!.stdout.listen(
    (data) => _terminal.write(String.fromCharCodes(data)),
);

// Keyboard input → SSH session
_terminal.onOutput = (data) {
    _session?.stdin.add(Uint8List.fromList(data.codeUnits));
};

// Terminal resize → SSH PTY resize
_terminal.onResize = (w, h, pw, ph) {
    _session?.resizeTerminal(w, h);
};

Resize events keep tools like vim, htop, and nano correctly sized.

Auto-Reconnect

Alpine takes ~15 seconds to boot. The terminal handles the window where sshd isn't ready yet:

static const _maxRetries = 24; // 24 × 5s = 2 minutes

void _retryOrError(String msg) {
    _retryCount++;
    if (_retryCount < _maxRetries) {
        _terminal.write('\r\n[$msg — retrying in 5s...]\r\n');
        _scheduleConnect(delaySeconds: 5);
    } else {
        _setError('Gave up after $_maxRetries attempts.');
    }
}

Progress messages appear inline in the terminal buffer — no separate loading spinner.

Terminal Theme

theme: const TerminalTheme(
    cursor:     Color(0xFF20C997),   // teal
    foreground: Color(0xFFE0E0E0),   // light grey
    background: Color(0xFF0E1117),   // near-black
    green:      Color(0xFF20C997),
    blue:       Color(0xFF0D6EFD),
    yellow:     Color(0xFFFFC107),
    red:        Color(0xFFDC3545),
)

The cursor teal (#20C997) matches the "Connected" status chip.

VM-Not-Running Banner

if (vmStatus != 'running')
    _Banner(
        icon: Icons.warning_amber,
        color: Color(0xFFFFC107),
        message: 'VM is not running. Start it from the Home tab.',
    )

Prevents confusing "Connection refused" errors when the user opens the terminal before starting the VM.

Next: Part 4 — Test Results

GitHub: github.com/AI2TH/Linxr

Linxr Series — Alpine Linux on Android

Linxr = Linux + r. A single Android APK that runs a full Alpine Linux shell on any Android phone — no root, no Termux, no PC required.

#	Post	Topic
📖	Intro	What is Linxr? Start here
1	Part 1	The Idea and Architecture
2	Part 2	Shipping QEMU in an APK
3	Part 3	SSH Terminal in Flutter
4	Part 4	Test Results

GitHub: github.com/AI2TH/Linxr
Website: ai2th.github.io

Linxr | Part 2 — Shipping QEMU in an APK

Ai2th — Mon, 09 Mar 2026 17:03:22 +0000

Shipping QEMU in an APK

Part 2 of 4 — building Linxr, a single APK that runs Alpine Linux on non-rooted Android.
← Part 1: The Idea and Architecture

The Same Wall as Pockr

Getting QEMU to run on non-rooted Android is the same challenge Pockr solved first. If you've read Pockr Part 2 and Part 3, you already know the full story. This article gives the overview as it applies to Linxr.

Problem 1: SELinux Blocks execve()

On Android 10+, files in app storage have the SELinux label app_data_file. That label does not allow execve().

Cannot run program ".../files/qemu/qemu-system-aarch64":
error=13, Permission denied

chmod +x doesn't help — it's a mandatory access control policy, not a Unix permission issue.

Fix: Put QEMU in jniLibs/arm64-v8a/ as a .so file.

qemu-system-aarch64  →  jniLibs/arm64-v8a/libqemu.so
qemu-img             →  jniLibs/arm64-v8a/libqemu_img.so

Android's PackageManager installs these to nativeLibraryDir which has exec_type SELinux label — execve() works.

Problem 2: Compressed jniLibs

AGP 3.6+ compresses native libraries inside the APK by default — they're loaded directly from the zip, not extracted to disk. QEMU needs to be on disk to execute.

Fix in build.gradle:

android {
    packagingOptions {
        jniLibs {
            useLegacyPackaging true
        }
    }
}

Problem 3: Wrong ELF Interpreter

A self-built QEMU from a Linux desktop uses glibc:

[Requesting program interpreter: /lib/ld-linux-aarch64.so.1]

Android's PackageManager only extracts .so files using Android's Bionic linker:

[Requesting program interpreter: /system/bin/linker64]

Fix: Use Termux's pre-built QEMU packages — compiled against Bionic.

Problem 4: 50 Shared Library Dependencies

Termux QEMU dynamically links ~50 shared libraries that live at Termux's prefix — a path that doesn't exist on non-Termux devices. All 50 must be bundled in jniLibs/.

Two sub-problems:

Termux embeds a hardcoded RUNPATH pointing to /data/data/com.termux/files/usr/lib/ — Android's linker tries it first and fails
patchelf --remove-rpath corrupts ELF — it restructures LOAD segments, breaking Android 11's strict segment count limits

Fix: An in-place Python script that zeroes only the d_val field of DT_RPATH/DT_RUNPATH ELF entries, leaving the structure intact. See Pockr Part 3 for the full implementation.

Linxr vs Pockr: Same Libraries

Linxr uses the same 50-library bundle as Pockr. The only difference in the QEMU launch command is the forwarded port:

// Linxr: SSH only
cmd += listOf("-netdev", "user,id=net0,hostfwd=tcp::2222-:22")

// Pockr: HTTP API
cmd += listOf("-netdev", "user,id=net0,hostfwd=tcp::7080-:7080")

Next: Part 3 — SSH Terminal in Flutter

GitHub: github.com/AI2TH/Linxr

Linxr Series — Alpine Linux on Android

Linxr = Linux + r. A single Android APK that runs a full Alpine Linux shell on any Android phone — no root, no Termux, no PC required.

#	Post	Topic
📖	Intro	What is Linxr? Start here
1	Part 1	The Idea and Architecture
2	Part 2	Shipping QEMU in an APK
3	Part 3	SSH Terminal in Flutter
4	Part 4	Test Results

GitHub: github.com/AI2TH/Linxr
Website: ai2th.github.io

Linxr | Part 1 — The Idea and Architecture

Ai2th — Mon, 09 Mar 2026 17:01:16 +0000

The Idea and Architecture

Part 1 of 4 — building Linxr, a single APK that runs Alpine Linux on non-rooted Android.

The Constraint

Android is a locked-down Linux system. For regular (non-root) apps:

execve() from app storage is blocked by SELinux W^X policy
Native Linux tools are unavailable without Termux
The kernel disables CONFIG_USER_NS — Docker rootless mode is impossible
No way to load kernel modules or create network namespaces

A QEMU virtual machine sidesteps all of this. The VM runs its own kernel with its own namespace — completely isolated from Android's restrictions.

Why Alpine?

Alpine Linux is the right guest OS for a mobile VM:

Property	Alpine	Debian/Ubuntu
Compressed disk image	~35 MB	~300 MB+
Boot time	~5 s	~30+ s
RAM at idle	~30 MB	~100 MB+
Package manager	`apk`	`apt`
Init system	OpenRC	systemd

Small footprint, fast boot, full POSIX shell — ideal for embedding in an APK.

Architecture

Android OS (non-rooted)
└── APK (Flutter + Kotlin)
    ├── VmManager — asset extraction, QEMU lifecycle
    ├── VmService — ForegroundService (keeps QEMU alive)
    └── Flutter UI — Home, Terminal, About tabs
          └── TerminalScreen (dartssh2 + xterm)

QEMU process (libqemu.so)
└── Alpine Linux 3.19 VM
    └── OpenRC init → sshd on :22
          ↑
          SLIRP hostfwd tcp::2222-:22
          ↑
    SSH on 127.0.0.1:2222 (from Android app)

Disk Layout

Linxr uses QCOW2 copy-on-write layering:

base.qcow2 (read-only — Alpine rootfs, openssh baked in)
  └── user.qcow2 (writable overlay — your data lives here)

base.qcow2 ships compressed in the APK assets. Extracted once on first install.
user.qcow2 is created fresh on first install. Persists across VM restarts — installed packages and files survive.

The overlay is only recreated when base.qcow2 changes (asset version marker bumps on app update).

SLIRP Networking

QEMU SLIRP requires no root and no kernel modules:

Android app
  └── TCP to 127.0.0.1:2222
        └── QEMU hostfwd: tcp::2222-:22
              └── Alpine VM eth0 (10.0.2.15):22
                    └── sshd

Inside the VM:

eth0:    10.0.2.15/24
gateway: 10.0.2.2
DNS:     10.0.2.3  (SLIRP built-in resolver)

The VM has full outbound internet access. apk add, curl, git all work normally.

Token-Free Design

Pockr uses a UUID token injected via QEMU kernel cmdline to authenticate its HTTP API. Linxr doesn't need that — SSH handles authentication natively:

Username: root
Password: alpine (baked into the base image)

No tokens, no custom API — standard SSH.

Next: Part 2 — Shipping QEMU in an APK

GitHub: github.com/AI2TH/Linxr

Linxr Series — Alpine Linux on Android

Linxr = Linux + r. A single Android APK that runs a full Alpine Linux shell on any Android phone — no root, no Termux, no PC required.

#	Post	Topic
📖	Intro	What is Linxr? Start here
1	Part 1	The Idea and Architecture
2	Part 2	Shipping QEMU in an APK
3	Part 3	SSH Terminal in Flutter
4	Part 4	Test Results

GitHub: github.com/AI2TH/Linxr
Website: ai2th.github.io

Linxr — Alpine Linux on Android (No Root)

Ai2th — Mon, 09 Mar 2026 17:01:14 +0000

What is Linxr?

Linxr = Linux + r (as in: run it).

Linux in your pocket.

Linxr is a single Android APK that runs a full Alpine Linux environment on any non-rooted Android phone. No Termux. No root. No PC required after install.

Install it, tap Start VM, wait ~15 seconds, and you have a live Linux shell — from the built-in terminal tab or any SSH client on the same device.

GitHub: github.com/AI2TH/Linxr
Download: linxr-v1.apk — ARM64 · 63 MB

Why Does This Exist?

Modern Android phones are powerful Linux machines underneath — 8 cores, 8 GB RAM, a full Linux 6.x kernel. But the platform deliberately limits what regular apps can do. Running native Linux tools requires either rooting the device or a runtime like Termux.

Linxr explores how far a normal, unmodified APK can go using only standard Android APIs. The answer: far enough for a full Alpine Linux VM with SSH access, persistent storage, and internet — in a 63 MB APK.

What You Get

Feature	Details
Alpine Linux 3.19	bash, sudo, apk package manager, openssl
Built-in SSH terminal	Auto-connects when VM starts; auto-retries
External SSH	`ssh root@localhost -p 2222` from any SSH client
Persistent storage	Installed packages survive VM restarts
Internet access	`apk add curl git python3` just works
No root	QEMU runs as a regular app process

Default credentials: root / alpine

The Stack

Flutter UI (Dart)
  └── MethodChannel
        └── Kotlin VmManager
              └── QEMU (libqemu.so — ships inside APK jniLibs)
                    └── Alpine Linux 3.19 VM (QCOW2 disk image)
                          └── OpenSSH sshd (port 22)
                                ↑
                    SLIRP hostfwd: Android :2222 → VM :22
                                ↑
              SSH client (dartssh2 + xterm — Flutter)

How It Compares to Pockr

Linxr is the sibling of Pockr — which runs Docker on Android. Linxr strips that down to the essentials:

	Linxr	Pockr
Guest runtime	OpenSSH	Docker daemon + FastAPI
Access method	SSH terminal	REST API
APK size	63 MB	163 MB
Boot time	~15 s	~60 s
First-run setup	None	~5 min (Docker install)

If you just need a Linux shell, Linxr is the right tool.

About the Name

Linxr = Linux with a dropped vowel. Same naming pattern as Pockr — short, memorable, double meaning. The goal was always "install this APK, get Linux" — no configuration, no server, no extra steps.

Linxr Series — Alpine Linux on Android

Linxr = Linux + r. A single Android APK that runs a full Alpine Linux shell on any Android phone — no root, no Termux, no PC required.

#	Post	Topic
📖	Intro	What is Linxr? Start here
1	Part 1	The Idea and Architecture
2	Part 2	Shipping QEMU in an APK
3	Part 3	SSH Terminal in Flutter
4	Part 4	Test Results

GitHub: github.com/AI2TH/Linxr
Website: ai2th.github.io

Idea & Contributor: Kalvin Nathan
skalvinnathan@gmail.com · LinkedIn

Pockr | Part 6 — Test Results and What's Next

Ai2th — Thu, 05 Mar 2026 13:27:14 +0000

Test Results, Firebase Test Lab, and What's Next for Pockr

Part 6 of 6 — the final chapter of building Pockr, a single APK that runs Docker on non-rooted Android.
← Part 5: Debugging a VM Restart Loop

Download

pockr-v1.apk — v1.0.0 · ARM64 · 163 MB
Release notes · GitHub

Requires Android 9+ (API 28), ARM64 device. Enable "Install from unknown sources" before installing.

How We Test: Firebase Test Lab

Physical device testing on a Mac with an Android emulator is unreliable for this project — QEMU needs hardware virtualisation, and nested virtualisation in emulators doesn't work.

Instead, every build gets tested on Firebase Test Lab with a Robo test:

Setting	Value
Device	Pixel 2 (arm64)
Android version	11 (API 30)
Test type	Robo (automated UI crawler)
Timeout	600 seconds
Architecture	ARM64 (same as real phones)

The Robo crawler explores the UI systematically — tapping every button it finds, navigating every screen, filling forms. It's brutal but effective at finding race conditions and edge cases that manual testing misses.

Test History

Version	Result	What Changed
v11–v20	❌ Various crashes	ELF/linker issues, asset extraction bugs
v22	✅ Pass	VmManager as Application singleton — QEMU survives Activity relaunch
v23	✅ Pass	DNS fix (`use-vc` + 8.8.8.8 fallback) — Docker Hub reachable
v24	✅ Pass	Flutter `ScaffoldMessenger` context fix
v25	✅ Pass	First container pull + run — busybox and nginx from Docker Hub (~78s)
v28	✅ Pass	Release APK + Pockr branding
v30	✅ Pass	Corrected APK filename in test script
v33	✅ Pass	Race condition fix in `VmManager.getStatus()` — no more restart loop
v34	❌ Fail	Double-start found — Robo tapped Start during `starting→running` transition, launching a second QEMU instance
v35	✅ Pass	Double-start guard in `VmState.startVm()` — confirmed no double-start, containers running

→ Full test results

What a Passing Test Looks Like

From the v35 logcat (second boot — Docker image cache already warm):

03:38:02  VmManager: Starting VM...
03:38:02  VmManager: Reusing existing user.qcow2 (Docker image cache preserved)
03:38:02  VmManager: VM process launched

         ... Alpine second boot: ~50 seconds ...
         ... API server comes up ...

03:38:53  VmApiClient: Container started: alpine_1772710722409  ✅
03:39:28  VmApiClient: Container started: test_1772710762640    ✅

From cold install (first boot, Docker + Python setup):

03:35:33  VmManager: Starting VM...
03:35:33  VmManager: Extracted vm/base.qcow2 (fresh install)
03:35:33  VmManager: VM process launched

         ... Alpine first boot: ~2–5 minutes ...
         ... Docker installs, API server bootstraps ...

From cold install to running container: ~5 minutes.
Second boot (Docker image cache warm): ~50 seconds.

What Works Today

✅ Install APK → tap Start → QEMU boots Alpine Linux
✅ Docker pulls images from Docker Hub over SLIRP networking
✅ busybox, alpine, nginx confirmed running on real hardware (ARM64, Android 11)
✅ Persistent overlay disk — pulled images survive VM restarts
✅ No root. No Termux. No PC required after install.
✅ Foreground service keeps VM alive when app is backgrounded
✅ Auto-start option to launch VM on app open

Current Limitations

Limitation	Notes
First boot ~5 min	Docker + Python bootstrap on Alpine; subsequent boots ~50s
ARM64 only	QEMU binary targets `aarch64` only (no ARM32/x86)
Storage driver: `vfs`	Less efficient than `overlay2`, but works without kernel modules
`--network host` only	No isolated container networks without bridge module
APK size ~163 MB	Includes full Alpine disk image + QEMU binary + 50 libraries

What's Next

[ ] Stop container / view logs in app UI
[ ] ARM32 device support
[ ] Reduce first-boot time
[ ] Custom container image support from UI

The Full Series

Part 1: The Idea and Architecture
Part 2: Executing Binaries on Android — The SELinux Problem
Part 3: Bundling 50 Native Libraries Without Breaking the Android Linker
Part 4: Making Docker Run Without iptables, bridge, or overlay2
Part 5: Debugging a VM Restart Loop — A Race Condition in Kotlin
Part 6: Test Results and What's Next ← you are here

Pockr Series — Docker in Your Pocket

Pockr = Pocket + Docker. A single Android APK that runs real Docker containers in your pocket — no root, no Termux, no PC required.

#	Post	Topic
📖	Intro	What is Pockr? Start here
1	Part 1	The Idea and Architecture
2	Part 2	Executing Binaries — The SELinux Problem
3	Part 3	Bundling 50 Native Libraries
4	Part 4	Docker Without Kernel Modules
5	Part 5	Debugging the VM Restart Loop
6	Part 6	Test Results and What's Next

GitHub: github.com/AI2TH/Pockr
Website: ai2th.github.io
Contributor: Kalvin Nathan
skalvinnathan@gmail.com · LinkedIn

Pockr | Part 5 — Debugging the VM Restart Loop

Ai2th — Thu, 05 Mar 2026 13:26:35 +0000

A Race Condition in Kotlin

Part 5 of 6 — building Pockr, a single APK that runs Docker on non-rooted Android.
← Part 4: Making Docker Run Without Kernel Modules

The Symptom

Alpine Linux takes ~5 minutes on first boot to set up Docker, install Python packages, and start the API server. During that time, the app shows a loading state.

On real device testing (Firebase Test Lab), we kept seeing a cycle:

VM starts → health check fails at ~35s → VM restarts → repeat

Alpine was never given enough time to finish first-boot setup. Docker Hub pulls never happened.

Reading the Logcat

The logcat told the story:

VmManager: Starting VM...
VmManager: VM process launched
VmApiClient: Health check failed: timeout          ← 35s in
VmManager: Starting VM...                          ← restarted!
VmManager: Stopping existing VM before restart     ← killed Alpine mid-boot
VmManager: VM process launched
VmApiClient: Health check failed: timeout          ← again
VmManager: Starting VM...                          ← restarted again

The VM was restarting every ~35 seconds — exactly the health check timeout. But why? Nobody was tapping Stop.

The Race Condition

Here's getStatus() before the fix:

fun getStatus(): String {
    if (!isRunning) return "stopped"   // ← THE BUG
    vmProcess?.let {
        return try {
            it.exitValue()
            isRunning = false
            "stopped"
        } catch (_: IllegalThreadStateException) {
            "running"
        }
    }
    return "stopped"
}

And startVm() does this:

@Synchronized
fun startVm() {
    // Stop existing VM before restart
    if (isRunning || vmProcess != null) {
        stopVm()   // kills QEMU
    }
    // ... launches new QEMU
    isRunning = true
}

Do you see the window? Inside startVm():

stopVm() is called → sets isRunning = false
New QEMU not yet launched → vmProcess = null
During this window, getStatus() is called by the Flutter health poll
!isRunning is true → returns "stopped" — even though we're mid-restart
Flutter sets _status = "stopped" → Start Engine button re-enables
User or Robo taps Start Engine → calls startVm() AGAIN → kills Alpine mid-boot

The Fix

Check the live process first, not the boolean flag:

fun getStatus(): String {
    // Check the process directly first — isRunning can be briefly false
    // during the startVm() window between stopVm() and isRunning=true
    vmProcess?.let {
        return try {
            it.exitValue()
            // Process actually exited — clean up
            isRunning = false
            vmProcess = null
            "stopped"
        } catch (_: IllegalThreadStateException) {
            "running"   // Process is alive
        }
    }
    return "stopped"
}

If vmProcess is non-null, we check whether the process is actually alive (exitValue() throws if still running). Only if the process has genuinely exited do we return "stopped".

A Second Guard in Flutter

We also added a guard in the Dart layer to prevent double-starts:

Future<void> startVm() async {
    if (_status == 'running' || _status == 'starting') return;  // guard
    _isLoading = true;
    _status = 'starting';
    ...
}

Even if something pushes a second startVm() call, it no-ops if the VM is already in motion.

Confirmed Fixed

Firebase Test Lab v33 logcat:

VmManager: Starting VM...           ← first boot
VmManager: VM process launched
VmApiClient: Health check failed: Connection reset   ← still booting, normal
... (2 minutes of booting) ...
VmApiClient: Container started: alpine_1772702979346  ← SUCCESS ✅

No restart loop. Alpine booted fully. Container started from Docker Hub.

Lessons

Boolean flags lie during state transitions. Check the real source of truth — the OS process handle.
Log everything. Logcat timestamps and thread IDs revealed the exact 3ms window where the race occurred.
Robo testing is brutal. Firebase's Robo crawler taps every visible button, exposing race conditions that manual testing misses.

Next: Part 6 — Test Results and What's Next

GitHub: github.com/AI2TH/Pockr
Website: ai2th.github.io

Pockr Series — Docker in Your Pocket

Pockr = Pocket + Docker. A single Android APK that runs real Docker containers in your pocket — no root, no Termux, no PC required.

#	Post	Topic
📖	Intro	What is Pockr? Start here
1	Part 1	The Idea and Architecture
2	Part 2	Executing Binaries — The SELinux Problem
3	Part 3	Bundling 50 Native Libraries
4	Part 4	Docker Without Kernel Modules
5	Part 5	Debugging the VM Restart Loop
6	Part 6	Test Results and What's Next

GitHub: github.com/AI2TH/Pockr
Website: ai2th.github.io

Pockr | Part 4 — Docker Without Kernel Modules

Ai2th — Thu, 05 Mar 2026 13:26:02 +0000

Docker Run Without iptables, bridge, or overlay2

Part 4 of 6 — building Pockr, a single APK that runs Docker on non-rooted Android.
← Part 3: Bundling 50 Native Libraries

Docker Starts — Then Immediately Fails

Once QEMU was running and Alpine booted, we launched Docker. It started, then failed silently. Containers wouldn't run. No useful error message.

The root cause: Alpine 3.19's Docker daemon defaults assume a full Linux kernel. Our QEMU kernel (6.6.14-0-virt) is stripped — it doesn't load iptables, bridge, overlay2, or ip_masq as kernel modules because there's no /lib/modules in the disk image.

What Was Missing

Feature Docker Expects	Kernel Module	Status in Our VM
Network filtering	`iptables` / `nf_tables`	❌ Not available
Container networking	`bridge`	❌ Not available
Efficient storage	`overlay2`	❌ Not available
NAT/masquerade	`ip_masq`	❌ Not available

Docker's default config tries to set up all of these on startup. Every one fails with operation not supported.

The Fix: Minimal Docker Config

We bake a custom /etc/docker/daemon.json into the Alpine base image:

{
  "iptables": false,
  "bridge": "none",
  "dns": ["10.0.2.3", "8.8.8.8", "8.8.4.4"],
  "ip-masq": false,
  "userland-proxy": false,
  "storage-driver": "vfs"
}

Setting	Why
`iptables: false`	Alpine's iptables uses nft backend — module unavailable
`bridge: none`	Bridge kernel module unavailable
`ip-masq: false`	No masquerading needed with host networking
`userland-proxy: false`	Avoids port proxy process startup failures
`storage-driver: vfs`	overlay2 needs kernel module; vfs always works

Container Networking: `--network host`

With no bridge, containers run with --network host — they share the VM's network stack directly.

The VM's network is QEMU SLIRP (user-mode networking). SLIRP gives the guest:

An eth0 at 10.0.2.15
Default gateway at 10.0.2.2
DNS proxy at 10.0.2.3
Port forwarding from Android host to guest

Containers inherit all of this. They can reach the internet, pull images from Docker Hub, and serve traffic on forwarded ports.

The DNS Trap

QEMU's built-in DNS proxy at 10.0.2.3 uses UDP. On real Android hardware (confirmed on Firebase Test Lab Pixel2.arm), UDP DNS is unreliable — Docker Hub pulls fail intermittently with:

Error response from daemon: Get "https://registry-1.docker.io/v2/":
dial tcp: lookup registry-1.docker.io: i/o timeout

Fix in /etc/resolv.conf:

nameserver 10.0.2.3
nameserver 8.8.8.8
nameserver 8.8.4.4
options timeout:2 attempts:2 use-vc

use-vc forces all DNS over TCP. With multiple fallback nameservers, Docker Hub pulls work reliably — confirmed with nginx (~78 seconds on Pixel2.arm, Android 11).

Storage: vfs vs overlay2

vfs is not space-efficient (it copies layers instead of linking them), but it works without kernel modules. For our use case — a VM with an 8 GB overlay disk — it's perfectly acceptable.

Pulled images are stored in the writable user.qcow2 overlay and survive VM restarts. Once nginx is pulled, subsequent boots start it instantly with no re-download.

Next: Part 5 — Debugging a VM Restart Loop

GitHub: github.com/AI2TH/Pockr
Website: ai2th.github.io

Pockr Series — Docker in Your Pocket

Pockr = Pocket + Docker. A single Android APK that runs real Docker containers in your pocket — no root, no Termux, no PC required.

#	Post	Topic
📖	Intro	What is Pockr? Start here
1	Part 1	The Idea and Architecture
2	Part 2	Executing Binaries — The SELinux Problem
3	Part 3	Bundling 50 Native Libraries
4	Part 4	Docker Without Kernel Modules
5	Part 5	Debugging the VM Restart Loop
6	Part 6	Test Results and What's Next

GitHub: github.com/AI2TH/Pockr
Website: ai2th.github.io

Pockr | Part 3 — Bundling 50 Native Libraries

Ai2th — Thu, 05 Mar 2026 13:25:32 +0000

Libraries Without Breaking the Android Linker

Part 3 of 6 — building Pockr, a single APK that runs Docker on non-rooted Android.
← Part 2: Executing Binaries on Android

QEMU Needs Friends

QEMU from Termux doesn't link statically. It depends on a chain of ~50 shared libraries:

libqemu.so
  ├── libcurl.so → libssl.so, libcrypto.so, libssh.so, libgnutls.so ...
  ├── libglib-2.0.so → libpcre2-8.so, libffi.so, libandroid-support.so ...
  ├── libbz2.so
  └── libzstd.so
      ... (44 more)

All of these are bundled in Termux's own prefix at /data/data/com.termux/files/usr/lib/ — which doesn't exist on devices without Termux installed.

Problem 1: RUNPATH Points to Nowhere

Every Termux binary has a hardcoded RUNPATH in its ELF:

readelf -d libqemu.so | grep RUNPATH
  (RUNPATH) Library runpath: [/data/data/com.termux/files/usr/lib]

Android's dynamic linker tries this path first. It doesn't exist → symbols not found → crash.

Fix: Zero out the RUNPATH in every .so file.

Why Not patchelf?

The obvious tool is patchelf --remove-rpath. We tried it. It works on a PC, but the resulting .so files crash Android's linker:

bionic/linker/linker_phdr.cpp:168:
Load CHECK 'did_read_' failed

patchelf restructures ELF LOAD segments when it modifies the file — sometimes creating 5 to 50 segments per library. Android 11's linker has strict limits on LOAD segment count.

Fix: An in-place Python script that zeroes only the d_val field of DT_RUNPATH/DT_RPATH entries, leaving the ELF structure completely intact:

import struct, sys

with open(sys.argv[1], 'r+b') as f:
    data = bytearray(f.read())
    # Parse ELF header, find .dynamic section
    # For each DT_RPATH/DT_RUNPATH entry:
    #   zero out d_val only — leave d_tag intact
    # Write back
    f.seek(0)
    f.write(data)

This preserves every byte of the ELF except the path string offset — exactly what the linker needs.

Problem 2: Versioned Sonames

Termux packages use versioned filenames (libzstd.so.1.5.7) with sonames like libzstd.so.1. Android's linker needs exact filename matches.

Fix: Rename every library to its base soname and update the soname field:

# Before
libzstd.so.1.5.7  (soname: libzstd.so.1)

# After
libzstd.so  (soname: libzstd.so)

Problem 3: Namespace Isolation

Android 7+ enforces linker namespace isolation. A library loaded transitively (e.g. libgnutls.so via libcurl.so) is NOT visible to other libraries unless they have a direct DT_NEEDED entry.

This caused errors like:

cannot locate symbol "gnutls_cipher_init"
referenced by libqemu_img.so

Even though libgnutls.so was present and loaded.

Fix: Add explicit DT_NEEDED entries for the minimum set of libs that provide undefined symbols — again using the in-place approach, not patchelf.

The Final Set: 50 Libraries

Category	Libraries
TLS / Crypto	libssl, libcrypto, libgnutls, libnettle, libhogweed, libtasn1, libgmp
SSH	libssh, libssh2
HTTP/2-3	libcurl, libnghttp2, libnghttp3, libngtcp2
Compression	libzstd, libbz2, libz
GLib	libglib-2.0, libffi, libpcre2-8, libiconv
Android compat	libandroid-support
Unicode	libidn2, libunistring
Events	libevent
...	27 more

Key Rule

Never use patchelf on these libraries. The in-place Python script is the only safe modification method. patchelf restructures ELF LOAD segments and breaks Android 11's linker.

Next: Part 4 — Making Docker Run Without Kernel Modules

GitHub: github.com/AI2TH/Pockr
Website: ai2th.github.io

Pockr Series — Docker in Your Pocket

Pockr = Pocket + Docker. A single Android APK that runs real Docker containers in your pocket — no root, no Termux, no PC required.

#	Post	Topic
📖	Intro	What is Pockr? Start here
1	Part 1	The Idea and Architecture
2	Part 2	Executing Binaries — The SELinux Problem
3	Part 3	Bundling 50 Native Libraries
4	Part 4	Docker Without Kernel Modules
5	Part 5	Debugging the VM Restart Loop
6	Part 6	Test Results and What's Next

GitHub: github.com/AI2TH/Pockr
Website: ai2th.github.io

Pockr | Part 2 — Executing Binaries on Android

Ai2th — Thu, 05 Mar 2026 13:24:45 +0000

Executing Binaries on Android — The SELinux Problem

Part 2 of 6 — building Pockr, a single APK that runs Docker on non-rooted Android.
← Part 1: The Idea and Architecture

The First Wall: Permission Denied

The most obvious approach is to bundle the QEMU binary inside the APK and extract it to app storage on first launch, then execute it with ProcessBuilder.

On Android 10+, this silently fails:

Cannot run program ".../files/qemu/qemu-system-aarch64":
error=13, Permission denied

This isn't a file permission issue. chmod +x won't fix it.

Why: SELinux W^X Policy

Android 10 enforces a W^X (Write XOR Execute) policy via SELinux. Any file in getFilesDir() — the app's private data directory — is labelled app_data_file. That label does not allow execve().

Directory	SELinux Label	Executable?
`getFilesDir()`	`app_data_file`	❌
`getCacheDir()`	`app_data_file`	❌
`nativeLibraryDir`	`exec_type`	✅

The native library directory is the exception — it's specifically labelled to allow execution. This is where Android puts .so files from your APK's jniLibs/.

The Fix: Ship QEMU as a `.so` File

Android's PackageManager extracts files from jniLibs/<abi>/ to nativeLibraryDir during installation. Those files must end in .so, but they don't have to be shared libraries.

We renamed the QEMU binary:

qemu-system-aarch64  →  libqemu.so
qemu-img             →  libqemu_img.so

Put them in android/app/src/main/jniLibs/arm64-v8a/ and Android extracts them to:

/data/app/~~.../com.example.dockerapp-.../lib/arm64/libqemu.so

This path has exec_type. execve() works.

The Second Problem: Wrong ELF Interpreter

Our first attempt used a self-built QEMU binary compiled on Debian. Android installed it to nativeLibraryDir but silently refused to extract it.

The reason: Android's PackageManager only extracts .so files with the Android linker as interpreter:

# Debian-built QEMU (rejected)
readelf -l qemu | grep interpreter
  [Requesting program interpreter: /lib/ld-linux-aarch64.so.1]  ← glibc

# Termux-built QEMU (accepted)
readelf -l qemu | grep interpreter
  [Requesting program interpreter: /system/bin/linker64]  ← Bionic

Fix: Switch to pre-built QEMU from Termux packages. Termux builds everything against Android's Bionic libc and uses /system/bin/linker64.

One More Catch: `useLegacyPackaging`

AGP 3.6+ compresses native libraries inside the APK by default (to reduce download size). Compressed .so files are NOT extracted to disk — they're loaded directly from the APK zip.

QEMU is not a shared library. We need it on disk to execute it. Fix in build.gradle:

android {
    packagingOptions {
        jniLibs {
            useLegacyPackaging true  // force extraction to disk
        }
    }
}

Summary

Problem	Root Cause	Fix
`Permission denied` on exec	SELinux W^X on `filesDir`	Ship as `.so` in `jniLibs/`
`.so` not extracted	APK compression	`useLegacyPackaging true`
Wrong ELF interpreter	glibc binary	Use Termux pre-built QEMU

Next: Part 3 — Bundling 50 Native Libraries

GitHub: github.com/AI2TH/Pockr
Website: ai2th.github.io

Pockr Series — Docker in Your Pocket

Pockr = Pocket + Docker. A single Android APK that runs real Docker containers in your pocket — no root, no Termux, no PC required.

#	Post	Topic
📖	Intro	What is Pockr? Start here
1	Part 1	The Idea and Architecture
2	Part 2	Executing Binaries — The SELinux Problem
3	Part 3	Bundling 50 Native Libraries
4	Part 4	Docker Without Kernel Modules
5	Part 5	Debugging the VM Restart Loop
6	Part 6	Test Results and What's Next

GitHub: github.com/AI2TH/Pockr
Website: ai2th.github.io

Pockr | Part 1 — The Idea and Architecture

Ai2th — Thu, 05 Mar 2026 13:23:41 +0000

The Idea and Architecture

This is Part 1 of a 6-part series on building Pockr — a single APK that runs real Docker containers on a non-rooted Android phone.

The Problem

Android phones are powerful computers. A mid-range device today has 8 cores, 8 GB RAM, and runs a full Linux kernel underneath.

Yet you cannot run a Docker container on one — not without root, not without Termux, not without jumping through hoops.

We wanted to change that. One APK. Install it. Tap Start. Run containers.

No root required. No Termux. No PC after install.

The Architecture

The stack is simpler than it sounds:

Flutter UI
  └── MethodChannel (Kotlin)
        └── QEMU (ARM64 binary embedded in APK)
              └── Alpine Linux VM
                    └── Docker daemon
                          └── Your containers

The phone runs a real Alpine Linux virtual machine using QEMU. Inside that VM, Docker runs normally — same as on any Linux server. The app communicates with a FastAPI server running inside the VM over a forwarded port (localhost:7080).

How the Pieces Fit Together

Layer	Technology	Notes
UI	Flutter (Dart)	Dark-themed dashboard, container list, settings
Bridge	MethodChannel	Flutter ↔ Kotlin
VM launcher	Kotlin `ProcessBuilder`	Spawns QEMU as a child process
Hypervisor	QEMU `qemu-system-aarch64`	Runs Alpine in a headless VM
Guest OS	Alpine Linux 3.19	~100 MB QCOW2 disk image
Container runtime	Docker (inside Alpine)	Full Docker daemon, no restrictions
API	FastAPI (Python 3)	Runs on `0.0.0.0:7080` inside VM
Auth	UUID token	Injected via QEMU kernel cmdline

Network Architecture

QEMU's SLIRP networking provides user-mode TCP/IP without kernel modules:

Android app
  └── HTTP to 127.0.0.1:7080
        └── QEMU hostfwd: hostfwd=tcp::7080-:7080
              └── Alpine guest eth0 (10.0.2.15):7080
                    └── FastAPI server
                          └── Docker socket

The API server must bind to 0.0.0.0:7080 — not 127.0.0.1. SLIRP delivers connections to the guest's eth0, not its loopback interface.

The QCOW2 Disk Strategy

Rather than shipping one large disk image, we use QCOW2 copy-on-write layering:

base.qcow2 (read-only, 102 MB compressed)
  └── user.qcow2 (writable overlay, 8 GB virtual, starts empty)

base.qcow2 — Alpine Linux with Docker pre-installed. Bundled in the APK.
user.qcow2 — Created fresh on first install. Persists between VM restarts. Stores pulled Docker images.

This means: pull nginx once, and it's available on every subsequent boot — no re-download.

Coming Up

Part 2: Why you can't just execve() a binary on Android — and how we worked around SELinux
Part 3: Bundling 50 Termux shared libraries without breaking the ELF linker
Part 4: Making Docker start without iptables or bridge kernel modules
Part 5: Debugging a VM restart loop caused by a race condition
Part 6: Firebase Test Lab results and what comes next

GitHub: github.com/AI2TH/Pockr
Website: ai2th.github.io

Pockr Series — Docker in Your Pocket

Pockr = Pocket + Docker. A single Android APK that runs real Docker containers in your pocket — no root, no Termux, no PC required.

#	Post	Topic
📖	Intro	What is Pockr? Start here
1	Part 1	The Idea and Architecture
2	Part 2	Executing Binaries — The SELinux Problem
3	Part 3	Bundling 50 Native Libraries
4	Part 4	Docker Without Kernel Modules
5	Part 5	Debugging the VM Restart Loop
6	Part 6	Test Results and What's Next

GitHub: github.com/AI2TH/Pockr
Website: ai2th.github.io

Pockr — Running Docker on a Non-Rooted Android Phone

Ai2th — Thu, 05 Mar 2026 13:22:00 +0000

What is Pockr?

Pockr stands for Pocket + Docker.

Docker in your pocket.

Pockr is a single Android APK that runs real Docker containers on any non-rooted Android phone. No Termux. No root access. No PC required after install.

You install it, tap Start Engine, and within minutes you have a live Docker daemon running inside a QEMU virtual machine — pulling images from Docker Hub, running containers, all from a device in your pocket.

GitHub: github.com/AI2TH/Pockr
Website: ai2th.github.io
Download: pockr-v1.apk — v1.0.0 · ARM64 · 163 MB

Why Does This Exist?

Android phones are powerful computers. A mid-range 2024 device has 8 cores, 8 GB RAM, and a full Linux kernel underneath. Yet the platform makes it nearly impossible to run Linux tools natively without root access.

Pockr explores how far you can push Android without any special privileges — using only public APIs, standard APK packaging, and a creatively bundled QEMU binary.

What You Need to Know Before Reading

This series assumes basic familiarity with:

Topic	Why it matters
Docker	What containers and images are, basic `docker run` usage
Linux	Filesystems, processes, shared libraries (`.so` files)
Android	App lifecycle, APK structure, ADB basics
ELF binaries	Helpful for Parts 2–3 (linker, shared libraries)
Kotlin / Flutter	Helpful for Parts 1 and 5

You do NOT need to know QEMU, Alpine Linux, or virtual machines — those are explained as we go.

The Stack at a Glance

Flutter UI (Dart)
  └── MethodChannel
        └── Kotlin VmManager
              └── QEMU (ARM64 binary, ships as libqemu.so)
                    └── Alpine Linux 3.19 (QCOW2 disk image)
                          └── Docker daemon
                                └── Your containers

Layer	Technology
UI	Flutter + Provider
Native bridge	Android MethodChannel (Kotlin)
Hypervisor	QEMU 10.x, aarch64
Guest OS	Alpine Linux 3.19
Container runtime	Docker (inside Alpine)
API	FastAPI on port 7080

About the Name: Pockr

Pockr = Pocket + Docker

The goal was always something you could hand to someone — "here, install this APK, and you have Docker". No server. No laptop. No setup beyond tapping a button.

Docker in your pocket. The dropped vowel keeps it short. The double meaning — pocket-sized and Docker — felt right.

Pockr Series — Docker in Your Pocket

Pockr = Pocket + Docker. A single Android APK that runs real Docker containers in your pocket — no root, no Termux, no PC required.

#	Post	Topic
📖	Intro	What is Pockr? Start here
1	Part 1	The Idea and Architecture
2	Part 2	Executing Binaries — The SELinux Problem
3	Part 3	Bundling 50 Native Libraries
4	Part 4	Docker Without Kernel Modules
5	Part 5	Debugging the VM Restart Loop
6	Part 6	Test Results and What's Next

GitHub: github.com/AI2TH/Pockr
Website: ai2th.github.io

Idea & Contributor: Kalvin Nathan
skalvinnathan@gmail.com · LinkedIn

Forem: Ai2th

Linxr | Part 4 — Test Results

Test Results

Download

How We Test

Test Result: Pass ✅

What the Robo Test Found

What Works

Current Limitations

What's Next

The Full Series

Linxr Series — Alpine Linux on Android

Linxr | Part 3 — SSH Terminal in Flutter

SSH Terminal in Flutter

The Goal

Connecting to the VM

Wiring SSH to the Terminal

Auto-Reconnect

Terminal Theme

VM-Not-Running Banner

Linxr Series — Alpine Linux on Android

Linxr | Part 2 — Shipping QEMU in an APK

Shipping QEMU in an APK

The Same Wall as Pockr

Problem 1: SELinux Blocks execve()

Problem 2: Compressed jniLibs

Problem 3: Wrong ELF Interpreter

Problem 4: 50 Shared Library Dependencies

Linxr vs Pockr: Same Libraries

Linxr Series — Alpine Linux on Android

Linxr | Part 1 — The Idea and Architecture

The Idea and Architecture

The Constraint

Why Alpine?

Architecture

Disk Layout

SLIRP Networking

Token-Free Design

Linxr Series — Alpine Linux on Android

Linxr — Alpine Linux on Android (No Root)

What is Linxr?

Why Does This Exist?

What You Get

The Stack

How It Compares to Pockr

About the Name

Linxr Series — Alpine Linux on Android

Pockr | Part 6 — Test Results and What's Next

Test Results, Firebase Test Lab, and What's Next for Pockr

Download

How We Test: Firebase Test Lab

Test History

What a Passing Test Looks Like

What Works Today

Current Limitations

What's Next

The Full Series

Pockr Series — Docker in Your Pocket

Pockr | Part 5 — Debugging the VM Restart Loop

A Race Condition in Kotlin

The Symptom

Reading the Logcat

The Race Condition

The Fix

A Second Guard in Flutter

Confirmed Fixed

Lessons

Pockr Series — Docker in Your Pocket

Pockr | Part 4 — Docker Without Kernel Modules

Docker Run Without iptables, bridge, or overlay2

Docker Starts — Then Immediately Fails

What Was Missing

The Fix: Minimal Docker Config

Container Networking: --network host

The DNS Trap

Storage: vfs vs overlay2

Pockr Series — Docker in Your Pocket

Pockr | Part 3 — Bundling 50 Native Libraries

Libraries Without Breaking the Android Linker

QEMU Needs Friends

Container Networking: `--network host`

The Fix: Ship QEMU as a `.so` File

One More Catch: `useLegacyPackaging`