Deterministic Arch Linux Runtime for Rooted Android
Run Arch Linux on your Android device with predictable behavior, verified installs, and safe updates — no more broken chroot states or manual recovery.
⚠️ Alpha Software — It works. It's tested. But it needs your help to get battle-hardened on more devices. Read more below.
Every Arch-on-Android setup eventually breaks the same way:
- Environment gets polluted by Android/Termux
- Installs fail halfway with no recovery path
- Updates silently corrupt the system
- Failures are silent and a nightmare to debug
ArchDroid fixes this by enforcing correctness instead of adapting to brokenness.
- Validates system state before execution
- Forces a clean, isolated runtime
- Installs and updates atomically — no partial states
- Detects and recovers from failures automatically
git clone https://github.com/AmnAnon/archdroid.git
cd archdroid
su
./archdroid bootstrap
./archdroid startIf bootstrap succeeds, your system is guaranteed to be in a valid state.
ArchDroid v0.1-alpha is functional and tested, but we need your help to make it bulletproof on more devices.
- ✅ Deterministic chroot runtime with environment isolation
- ✅ Cryptographically verified bootstrap with checksum anchors
- ✅ Atomic in-place updates with snapshot rollback
- ✅ Comprehensive doctor/verify diagnostics
- ✅ Tested under failure: process kills, corruption, resource exhaustion
- 🎯 Device compatibility — tested on Poco X3 Pro (SD860, Android 11+), but what about yours?
- 🎯 Root method compatibility — KernelSU, Magisk, APatch?
- 🎯 Android version quirks — SELinux policies, mount behaviors, linker quirks
- 🎯 Performance edge cases — slower storage, low memory, custom ROMs
- Install it on your device
- Run the diagnostics:
./archdroid doctor - Report what works and what doesn't → open a GitHub issue with your:
- Device model and chipset
- Android version and ROM
- Root method (KernelSU / Magisk / APatch)
- Any errors from
archdroid doctor
Every report gets us one step closer to v1.0.
- Rooted Android: KernelSU, Magisk, or APatch
- Architecture:
aarch64(ARMv8) — covers most modern devices - Storage: ~2GB free space for rootfs + operations
- Network: HTTPS connectivity for secure downloads
- Dependencies:
curl,tar,sha256sum,jq,bash
| Device | Chipset | Android | Root | Status |
|---|---|---|---|---|
| Poco X3 Pro | Snapdragon 860 | 11+ | KernelSU | ✅ Verified |
| Your device? | 🎯 Test needed |
ArchDroid operates in a strict loop:
inspect → enforce → execute → verify → (repeat)
- Inspect — validate system state and detect issues
- Enforce — fix or block invalid conditions
- Execute — run in a clean, controlled environment
- Verify — confirm system integrity post-execution
This guarantees the system is never left in an unknown or partially broken state.
- 🔐 Secure Bootstrap — HTTPS downloads with checksum verification and external trust anchors
- ⚡ Atomic Updates — zero-downtime in-place updates with guaranteed rollback
- 🛡️ Failure-Tested — validated against process kills, file corruption, resource exhaustion, and network drops
- 🔍 Comprehensive Diagnostics — full
doctorinspection, independentverify, real-timestatus - 🧰 Complete CLI — unified tool for all operations
- 📊 Trust Model — explicit security boundaries documented in
TRUST_MODEL.md
./archdroid bootstrap # First-time installation (requires root)
./archdroid start # Enter the Arch Linux chroot./archdroid status # System health and version info
./archdroid doctor # Comprehensive diagnostics
./archdroid verify # Independent integrity check
./archdroid update # Atomic system update./archdroid reset-trust # Clear state, force fresh bootstrap# Bypass validation to enter anyway (for debugging)
ARCHDROID_SAFE_MODE=1 ./archdroid start
# Use an alternative rootfs path
export ARCH_PATH=/data/local/arch-test
./archdroid bootstrapArchDroid protects against runtime inconsistency and supply-chain risks, not full system compromise.
- MITM attacks, DNS hijacking, compromised mirrors
- Tampered rootfs archives, corrupted packages
- Environment contamination, mount corruption
- Partial installations, incomplete upgrades
- Interrupted operations (automatic cleanup)
- Compromised root environment
- Kernel-level attacks
- Physical device access
- System clock tampering
See TRUST_MODEL.md for full details.
setenforce 0 && archdroid startThis is temporary — resets on reboot.
You need to run ./archdroid bootstrap first.
Run archdroid doctor again — some mounts need a warmup cycle.
Try the manual chroot test to see the real error:
chroot /data/local/arch /bin/bash -c 'echo ok'archdroid/
├── archdroid # Unified CLI interface
├── core/
│ ├── inspect-runtime.sh # System validation & diagnostics
│ ├── runtime.sh # Deterministic runtime enforcement
│ ├── bootstrap.sh # Secure bootstrap & installation
│ ├── verify.sh # Independent verification
│ ├── atomic-update.sh # Atomic updates with rollback
│ ├── trust-reset.sh # Trust recovery mechanism
│ ├── versions.sh # Version tracking
│ └── json-utils.sh # Safe JSON parsing
├── test/
│ ├── fuzz-framework.sh # Failure injection testing
│ └── recovery-validation.sh # Recovery scenario validation
├── install.sh # Quick installation helper
├── start-arch.sh # Legacy start script
├── stop-arch.sh # Legacy stop script
├── TRUST_MODEL.md # Security boundaries
├── test-android-compatibility.sh # Compatibility checker
└── README.md # This file
MIT License — use it, share it, improve it.
Attribution appreciated but not required.
- Found a bug? Open an issue with your device info and
doctoroutput - Got a fix? PRs are welcome
- Tested on a new device? Add it to the verified platforms table
Built for reliability. Engineered for security. Tested against chaos.
v0.1-alpha — Help us make it better.