proot-forge

A standalone Android APK project for running a full PRoot container environment on-device: Compose terminal, session manager, bundled native PRoot runtime, and a bundled Debian rootfs.

Everything needed to run is bundled in the APK — no Termux dependency, no external rootfs URL, and no VM/QEMU layer.

What's in the app

• core/main — the Compose terminal UI, SessionService, and session management. The terminal is based on TerminalView/TerminalEmulator from Termux, with ANSI/color/screen redraw support.
• core/proot — the native PRoot runtime, built from C source by CMake: libproot.so and libloader.so (custom ARM64 build with --link2symlink, seccomp, etc.).
• core/components, core/resources — shared UI/components and app resources used by the core.
• Bundled Debian rootfs — core/main/src/main/assets/boffin-rootfs.bin is a Debian 12 ARM64 rootfs. On first launch it is copied to filesDir/boffin.tar.gz, then init-host.sh extracts it to local/boffin. No download or external URL is used.
• Session service — SessionService keeps each Boffin container session running in the foreground; multiple sessions, rename, sort, and session switching are supported.
• Init scripts — init-host.sh/init.sh/rm-wrapper.sh, written from assets into <filesDir-parent>/local/bin when missing.
• Automatic package repair — after the rootfs is extracted, the first container start runs apt update and reinstalls perl and gzip; a marker prevents it from rerunning after it succeeds.
• Shell script support — opening a .sh file with the app runs it inside the bundled Debian container.

The app requires Android 8.0+ (minSdk 26) and is built for arm64-v8a. Its application ID is io.boffin.prootforge.

All container state lives in <filesDir-parent>/local/. With the current application ID, that resolves to /data/user/0/io.boffin.prootforge/local/ (init scripts use $PREFIX = filesDir.parentFile and $PKG = package name, so there are no hardcoded /data/data/... paths left anywhere).

Releases and CI build

The latest signed APK is published on the repository's Releases page (currently v0.1.8).

.github/workflows/build.yml automatically builds debug and release APKs on every push/PR to main using the checked-in Gradle wrapper.

To build locally, use JDK 17 and an Android SDK with NDK 29.0.14206865 and CMake 3.22.1:

export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
export ANDROID_HOME=/opt/android-sdk
./gradlew assembleDebug assembleRelease

The release APK installs directly; no extra setup is needed.

Setup

1. Install the APK and open proot-forge.
2. On first launch the bundled Debian rootfs is copied from the APK and extracted into local/boffin.
3. The terminal starts inside the container automatically. Use Add Session in the drawer or toolbar to start another Boffin session.
4. Opening a .sh file with the app runs it inside the same container.

Still to do

• Test more ROMs/devices, especially storage binding and foreground service behavior on hardened Android builds.
• Replace the throwaway release keystore with a long-lived signing key before wider distribution.