简体中文 · English
IrisBox (虹膜空间) is a container manager that runs multiple isolated Android userspaces simultaneously on a rooted ARM64 Android host using Linux namespaces (all 7 namespaces with unprivileged User-namespace UID mapping), private BinderFS, and OverlayFS. Workflow: Install APK → Grant host Magisk root → Install built-in engine → Import compatible ROM → Create instance → Start.
Version 0.3.0 (engine 0.3.0-e41) runs on a unified ARM64 container core + declarative Board Profiles (board.json) across two verified host platforms:
- Raspberry Pi 4B (
rpi4-a13-v1): Raspberry Vanilla AOSP 13 (Linux 5.15 / Mesa V3D), with a public AOSP.irisromand clean USB host image preview. - Orange Pi 5 (
opi5-a12-v1): RK3588S Android 12 (Linux 5.10 / Mali-G610), featuring enforced external NVMe/USB SSD isolation (/data/irisboxUUID binding + boot restoration). No proprietary/GMS ROM is redistributed for Orange Pi 5.
Instances share the host Linux kernel (no CPU emulation, no guest kernel boot). Apps, accounts, writable overlays, and configs stay isolated per instance; arbitrary phone ROMs cannot be imported.
- Read the host and installation guide and release/image boundaries to verify kernel support, GPU nodes, Wi-Fi, and Permissive setup (Orange Pi 5 additionally requires binding an external SSD under
/data/irisbox). - Install host Magisk yourself per its upstream guide for your board. IrisBox never installs host Magisk or modifies host partitions/SELinux.
- Install
IrisBox-0.3.0.apk, tap Authorize and check, then Install engine. - On Raspberry Pi 4, import
IrisBox-rpi4-a13-aosp.irisromand create/start an instance. On Orange Pi 5, prepare a matching local ROM per the OPi5 adaptation notes. - Use EN / 中文 to switch System default, English, or 简体中文 for the host UI without altering guest locales or data.
Downloads and SHA-256 · GitHub Releases
The diagram illustrates the workflow and contains no account or device data.
Existing 0.1.5–0.2.1 installations can upgrade the engine in place while preserving instance data via tools/upgrade_engine.py --apply (no repeated UID remapping needed). Earlier 0.1.4/e21 setups must first follow the stopped-state namespace migration guide.
- Board decoupling (
0.2.0+):engine/boards/<profile>/board.json+tools/board_profiles.pysynchronize SoC parameters, Android 12/13 BPF modes, memory ceilings, and media filters from a single source. Orange Pi 5 enforces dedicated external SSD mounting (storage_ssd.sh+ Magiskservice.dauto-restore) to keep host internal flash clean. - Identity isolation & safe ROM import: Dedicated 7-namespace isolation with disjoint non-root Host UID ranges and zero Host-UID0 fallback (UserNS guide); ROM imports verify paths, sizes, and per-file SHA-256 without executing archive scripts.
- Dynamic uplink probing & egress control (
0.2.1+): Tracks active physical uplinks (wlan0/eth0) and VPNtuninterfaces, with per-guest direct/proxy egress and liveauto/domestic/overseas/ custom DNS switching while preserving shared eBPFINTERNETpermission enforcement. - Sub-second fullscreen handoff & audio/video bridge: Direct shared-buffer GPU output, live orientation switching, parallelized display handoff (~
0.65s–0.85sobserved on Orange Pi 5,~0.93son Raspberry Pi 4), 48 kHz PCMAudioBridge, touch/keyboard/mouse input, and fullscreen Recents button. - Live Linux/Cgroup/FPS telemetry & swap protection: Zero-fork
LinuxTelemetryreads hierarchical memcgtotal_rss/total_cache/Swap/majfault, PSI, 7 namespaces, and 500ms sliding-window FPS/composition rate/Fence latency into card bars, an auto-refreshing monitor dialog, and a persistent fullscreen performance HUD. Retains 1/2/4 GiB host swap and available-RAM guardrails. - Cross-instance migration & safety gate (
0.3.0): Host-to-guest APK installs and guest-to-guest migration (APK/Android/data/ optional/data/datawith UID/SELinux relabeling). Because migrating social session data across different container fingerprints can trigger vendor risk bans,0.3.0enforces an explicit typed-phrase gate before unlocking/data/datamigration and blocks/data/datamigration for high-risk messaging apps (WeChat / QQ / TIM / WeWork).
Public ROMs contain AOSP and compatibility overlays without Google apps or accounts. Optional Google support requires user-supplied matching components; guest Magisk remains per-instance and separate from host Magisk.
Real-hardware verification highlights across 0.1.4–0.3.0 (full logs, conditions, and boundaries are in the Chinese validation log and English summary):
- Raspberry Pi 4B (AOSP 13 / 3.69 GiB):
0.2.1-e40in-place upgrade verified;1010(2048 MiB Google+Magisk) booted in85.9switheth0connectivity, live DNS switching,Via/OpenSudoku/Calculator/Magisk Manager, and RPi4 telemetry; earlier0.1.6validated simultaneous Clash + Angry Birds 2, YouTube playback, and host-reboot 2 GiB swap restoration (Play device certification remains unmet). - Orange Pi 5 (RK3588S / Android 12): Enforced
114 GBexternal SSD isolation + reboot auto-mount verified; dual instances, 60fps HUD, Douyin (FPS 33.8–33.9+ AudioBridge) & Bilibili (FPS 29.9) playback,3.70 GB1007 -> 1010streaming migration, and the0.3.0/data/datasafety-gate warning dialog passed on device.
| Play installation in progress | Installed from Play | Tiantian Xiangqi running |
|---|---|---|
![]() |
![]() |
![]() |
| Clash of Clans tutorial village | YouTube video playback | Angry Birds 2 actual target destruction | Swap settings |
|---|---|---|---|
![]() |
![]() |
![]() |
![]() |
Above captures are early owner-approved crops/redactions with no AI redraw; newer OPi5 and RPi4 raw screenshots remain private per project rules. Image details.
- Unverified flashing & fresh-host setup: The clean RPi4 USB host image (
USB/sda, 16 GB+, 12 GiB blank userdata, not SD/mmc) passed static checks only; a fresh physical USB-disk flash and first boot have not been tested, nor has initial BPF dispatcher creation on a completely clean host that never ran Project Iris. - Out of scope: Arbitrary kernels/SoCs, SELinux
Enforcing, physical camera/microphone passthrough, hardware DRM playback, Play Integrity / Google device certification, and arbitrary third-party Root modules. - Anti-fraud / account risk boundary: Migrating
/data/datatransfers app state into a different container identity (SSAID, virtual MAC). Sensitive apps (e.g., WeChat, QQ, commercial risk-controlled clients) can impose account restrictions; rely on APK-only migration and fresh in-container logins.
See third-party notices and source provenance. Project-specific code carries no blanket license grant; keys, user data, proprietary/GMS ROMs, and raw device logs/screenshots are excluded from public distribution.








