Android Virtualization Framework is a new virtualization environment for Android
Among others, it is used to provide the Terminal App starting from Android 15 QPR2
This profile contains the necesarry services and kernel configs to get it running under the Terminal app
The system changes have been taken from https://android.googlesource.com/platform/packages/modules/Virtualization/+/refs/heads/main/build/debian
There is now an app that performs the installation steps for you.
Note that currently the guides in the README are out of sync as I'm busy with other things.
If you have any problems, feel free to join the Matrix Chat
» Download nixos-unstable aarch64 image
» Other architectures/releases
Assuming current folder is the root of this repo, build the following: nix-build initial.nix -A config.system.build.avfImage
Copy the result file to /sdcard/linux/images.tar.gz on your phone.
If the VM fails to start, include ./avf/debug.nix and view the logs on a debuggable version of Android from the Terminal app (there is no better way currently)
If you don't have enabled the Terminal App already you need to enable it in the Developer Options.
Go to Settings > System > Developer Options > Linux development environment (it's close to USB Debugging in the list)
If you don't have Developer Options enabled » read how to do it here
Note
After installation of the image you want to expand the disk as you will run into space problems during rebuild otherwise.
You can resize the disk under "Settings (Gear) > Disk resize". We recommend 8 GB or more.
Important
The image only works on Android 16+ ( » Beta Program ) and on Android 15 flavours that have the Android 16 Terminal patches backported (example: GrapheneOS)
You will need a debuggable android build also known as userdebug (eng build also works)
Place the image under /sdcard/linux/images.tar.gz or use scripts/android-download-vm.sh to download and copy the latest image.
Delete existing VM configuration either via app (Settings > Recovery) or via scripts/android-clean-vm.sh
Restart the terminal app. You should get a popup saying "Auto installing" and the Terminal should automatically use your image.
todo, help needed
Magisk:
adb shell "su -c 'rm -rfv /data/data/com.android.virtualization.terminal/{files/nixos.log,files/debian.log,files/linux,vm/nixos,vm/debian}'" # clean
adb shell "su -c 'magisk resetprop ro.debuggable 1; stop; start;'" # enable debuggable
adb shell "su -c 'rm -f /data/media/0/linux/images.tar.gz'"
adb shell "su -c 'wget https://github.com/nix-community/nixos-avf/releases/download/nixos-unstable/image-unstable-aarch64.tar.gz -O /data/media/0/linux/images.tar.gz'"Then launch the terminal app. It should auto-install.
After installation is finished you can revert the changes to ro.debuggable.
Try restarting the app. Try re-installing the image if that doesn't help.
Check /data/data/com.android.virtualization.terminal/files/nixos.log
If the log contains EFI boot manager: Cannot load any image or is missing any systemd messages like "Started xyz.service..." then the image might be corrupted
Run adb shell rm -rfv /data/data/com.android.virtualization.terminal/{files/nixos.log,files/debian.log,files/linux,vm/nixos,vm/debian} to clear up any remnants of previous installs, then install the image again
The VM has a 4 GB allocation of memory. This allocation does not represent the RAM the VM can actually physically use, only the maximum amount of memory it will be given from the host system under any condition.
That means while the VM may think it has 4 GB of RAM available, there may not be enough physical memory available on the Phone itself.
If the host memory runs full, the guest will crash.
For rebuilds you can split up the rebuild into evaluation and build+switch. Just run sudo nixos-rebuild dry-build and only afterwards sudo nixos-rebuild switch. This usually works even on low-memory systems.
