nanoMuse手机本地运行时揭秘:APK内塞入Alpine Linux+Proot,让AI在手机上跑完整Linux
nanoMuse手机本地运行时揭秘:APK内塞入Alpine Linux+Proot,让AI在手机上跑完整Linux
nanoMuse 手机本地运行时把一套 Alpine Linux(aarch64)根文件系统和 PRoot 直接塞进 APK,让 AI Agent 无需 root 权限就能在手机上运行完整 Linux:真实 shell、文件读写、git、Python、定时任务全部在这台“口袋里的 Linux 小机器”里执行。这篇文章带你拆解这个 APK 里到底藏了什么,以及 PRoot 是如何绕过 Android 沙箱跑起一个操作系统的。
一、为什么 AI 助手需要一部“手机里的 Linux”
大多数 AI 助手只会聊天,而 nanoMuse 的 Agent 要动手干活:跑脚本、克隆仓库、处理文件、调用 MCP 工具、执行定时任务。这些事光靠云端 API 做不到——你需要一个真实的执行环境。
把执行环境做成云端服务会带来网络依赖和数据出境问题;而 nanoMuse 的选择是:把整个运行时打包进 APK,全部跑在手机本地。模型推理走云端(或你自己的 Key),但 shell、文件和工具执行都在设备内完成,断网了定时任务照样记账,隐私数据不出手机。
这套“手机本地运行时”是 nanoMuse 在 Android、iOS 上最核心的工程之一。
二、APK 里到底塞了哪三样东西
拆开 APK 看,本地运行时由三个部分组成:
| 组件 | 作用 | 构建脚本 |
|---|---|---|
| Alpine Linux aarch64 minirootfs | 一个约几十 MB 的完整 Linux 根文件系统(busybox、ash、apk 包管理器) | prepare_android_sandbox.sh |
| PRoot 5.1(静态编译的 aarch64 二进制) | 用户态“伪 chroot”,不需要 root 就能挂载并运行 rootfs | build_proot.sh |
ELF Loader(libproot-loader.so) |
绕过 Android W^X 限制、让 PRoot 能启动 guest 进程的关键 | 同上 |
构建脚本的思路非常直接:prepare_android_sandbox.sh 从 Alpine 官方源下载 alpine-minirootfs-3.21.3-aarch64.tar.gz,从 Termux 软件源解出 PRoot 的 aarch64 静态二进制,然后全部放进 app/src/main/assets/,随 APK 一起分发。build_proot.sh 则用 Android NDK r28+(minSdk 26)把 OpenMinis 的 proot 分支和 talloc 2.4.2 交叉编译成三个产物:
assets/proot-aarch64 # 沙箱二进制
jniLibs/arm64-v8a/libproot.so # 以 .so 身份进入 nativeLibraryDir
jniLibs/arm64-v8a/libproot-loader.so # 64 位 loader
jniLibs/arm64-v8a/libproot-loader32.so # 32 位 loader
⚠️ 注意那两个“挂着 .so 后缀的可执行文件”——这不是笔误,而是 Android 10+ 的 W^X 策略逼出来的:标记为
app_data_file的文件(包括解压后的整个 rootfs)永远不可执行,只有从jniLibs解压到nativeLibraryDir的.so才能执行。loader 伪装成.so才能过这一关,细节可见 build_proot.sh 开头的设计注释。
三、PRoot 原理:无 root 的“用户态 chroot”
传统 chroot 需要 root 权限来切换根目录、伪造设备节点;手机上没有 root,怎么办?PRoot 的答案是 ptrace:
- 以普通进程启动,fork 出 guest 进程;
- 用
ptrace拦截 guest 的每一次系统调用; - 在拦截点上重定向路径——把 guest 眼中的
/映射到 app 私有目录下的alpine-rootfs/,把/dev、/proc、/sys绑定到真实文件; - 伪造
getuid()返回 0,让 guest 里的apk add、pip install以为自己是 root。
每次 shell 执行时,Kotlin 侧的 PRootKernel.kt 会拼出一条这样的命令行:
proot -0 --link2symlink \
-r <files>/alpine-rootfs \
-b /dev -b /proc -b /sys \
-w /root \
-b <host>:<guest> ... \
--native-offload=<socket>:<handlers> \
/bin/sh -c "<command>"
几个参数各有讲究:
-0:伪 root。guest 里的包管理器都要求 uid 0,PRoot 在 ptrace 拦截层里骗过它们;--link2symlink:Android 的/data文件系统拒绝应用 uid 创建跨目录硬链接(EPERM),而 Alpine 的apk安装 busybox 工具时就靠硬链接——这个开关把所有link()系统调用翻译成符号链接,apk才能正常工作;-b绑定挂载:除了/dev、/proc、/sys,还会把 app 私有目录里的memory/、skills/、shared/、mcp-servers/挂到 guest 的/var/minis/下,用户在设置页挂载的外部文件夹(Obsidian 库、Downloads 等)也挂到/var/minis/mounts/<name>,guest 里改文件就是直接改手机上的真实文件。
四、首次启动:进度条背后的解压与装配
第一次打开 App 时,RootfsManager.kt 会从 assets 里取出压缩的 alpine-minirootfs.tar.gz,用自带的 POSIX tar 解析器逐条解压到 files/alpine-rootfs/,并对外发布 Preparing → Extracting(进度) → Finalizing → Installed 状态流——界面上的进度条正是这个 StateFlow 驱动的,进度按压缩字节消耗计算,所以全程平滑单调。
解压完成后,PRootKernel.boot() 还会做一套“开机仪式”:
- 把
default_mount/覆盖层叠到 rootfs 上(每次开机重新覆盖,保证 pip/npm/apk 的镜像配置随版本更新); - 刷新 DNS,把系统代理注入 guest 环境变量;
- 注入一批环境变量:
HOME=/root、手机时区转成的 POSIXTZ、NO_COLOR=1、GOMAXPROCS=2、UV_LINK_MODE=symlink等; - 启动 native-offload 服务,在 guest 的
/usr/local/bin/里为每个已注册的宿主处理器放置一个空壳脚本(stub)。
五、AI 如何驱动这台 Linux:shell 工具与审批卡片
Agent 的 shell_execute 工具本质就是走上面那条 proot /bin/sh -c "..." 通道:命令在 Alpine 里真实执行,stdout/stderr 原样回到对话里。而 native-offload 机制则让一些“必须回到宿主执行”的操作(打开系统浏览器、设备能力调用)也能像普通命令一样运行:guest 执行 stub 时触发 execve,PRoot 扩展会把它通过 abstract unix socket 转给 Kotlin 侧的 NativeOffloadServer,宿主执行完再把输出写成 guest /tmp 里的文件,并重写执行流为 /bin/cat <文件>——guest 视角里这只是一次普通的命令输出。
安全是这套本地沙箱的重要部分:由于 Agent 真的能在 Linux 里跑任意命令,nanoMuse 对删除、发送、支付这类不可撤销的操作会弹出审批卡片(如上图),允许/拒绝完全由用户决定;同时所有 /var/minis/... 路径在解析时会被限制在沙箱内,.. 和越界符号链接一律失效。
六、已知局限:ptrace 的代价
无 root 的强大能力来自 ptrace,代价也来自 ptrace,官方设计文档里写得很坦率:
- 系统调用密集的场景变慢:PRoot 拦截每一个 syscall,纯计算的 Python 几乎无感,但
git clone大仓库、pip install大量小文件这类操作会比原生慢 2–5 倍; - musl 而非 glibc:Alpine 用 musl libc,预编译二进制要选
musllinux版本,否则需要apk add gcompat; - 没有真 root 的能力:绑定 1024 以下端口、改 uid 等操作不可用;
/proc里读到的是 Android 的真实值或替代品; - 内存压力:Android 在后台仍可能回收服务,服务用
START_STICKY加闹钟补跑机制兜底。
这些权衡的设计记录见 docs/local-runtime.md,整体 Android 侧说明见 docs/android.md。
七、动手构建:自己编译一个含 Linux 沙箱的 APK
如果你想完整体验这套手机本地运行时,构建门槛并不高(JDK 17/21 + Android SDK + NDK r28+):
git clone --recurse-submodules https://gitcode.com/gh_mirrors/na/nanoMuse
cd nanoMuse
bash scripts/android/env.sh # 裸机环境初始化
./deps/build_proot.sh # 交叉编译 PRoot + loader
./scripts/prepare_android_sandbox.sh # 下载 Alpine aarch64 rootfs
cd android/src/android && ./gradlew :app:assembleDebug
构建顺序有讲究:loader 缺失时故障很隐蔽——PRoot 能启动、日志看起来一切正常,但第一条 execve("/bin/sh") 就会 Permission denied,所有命令都返回 <a href="https://link.gitcode.com/i/32f4fc674cc7682ad3c8da72cc87721a" target="_blank">Shell not running] (exit code: -1)。unzip -l app-debug.apk | grep libproot 确认三个 .so 都在,再跑一条真实命令断言退出码为 0,才算通过。完整的依赖清单和排错指南在 [android/BUILDING.md。
八、总结
nanoMuse 用手机本地运行时证明了一件事:一个 APK 可以装下一整台 Linux。Alpine minirootfs 提供系统,PRoot 用 ptrace 在用户态伪造出 root 与文件系统视图,Kotlin 侧负责装配、挂载、offload 和审批。没有虚拟机镜像、没有 root、没有模拟器——只是更聪明的系统调用拦截。对想在移动端跑 AI Agent 的开发者来说,这套“APK 内嵌 Linux 沙箱”的方案值得一读:核心代码都集中在 android/src/android/app/src/main/java/com/openminis/app/sandbox/ 和 android/deps/ 下,路径清晰,注释详尽。

