Vanilla Mobile NixOS Workshop

Quick Reference

For all of the following procedures, unplug the USB cable first and make sure the phone is completely powered off:

• Enter fastboot/bootloader: Hold Power + Volume Up until the fastboot screen appears. Do not release the buttons before then.
• Force reboot: Hold Power + Volume Up for about 10 seconds, until the phone vibrates or the OnePlus logo appears.
• Enter Qualcomm EDL/9008: With the phone powered off, hold Volume Up + Volume Down while connecting the USB cable, and keep holding them. The screen usually remains black. The host should detect Qualcomm HS-USB QDLoader 9008. If ADB is still available, you can also run adb reboot edl.

EDL is a recovery and low-level firmware flashing mode. MSMDownload Tool and other EDL tools may erase the device. Confirm that the device model and firmware match exactly before proceeding. See the postmarketOS OnePlus 6 page for additional fastboot and EDL instructions.

This repository carries a local Disko patch for nix-community/disko#1277. It preserves the required virtual-devices-option fork while fixing image generation with current nixpkgs.

Build the netboot bundle

Build the Android netboot image and both Disko raw images together:

nix build .#enchilada-netboot --accept-flake-config

The result contains u-boot.img, u-boot-upstream.img, nixos-netboot.img, nixos-boot.raw, and nixos-root.raw. The root image is an unencrypted Btrfs filesystem with @root, @home, and @nix subvolumes.

nixos-netboot.img is an Android boot header v2 image with a separate DTB for U-Boot's fastboot handoff.

Build U-Boot

nix build .#nixosConfigurations.enchilada.config.vanilla-mobile.deviceInfo.uboot --accept-flake-config

The resulting Android boot image is result/u-boot.img.

Netboot

This configuration uses the generated nixos-root.raw as a Btrfs NBD root disk over USB-NCM. The root image stays on the build host, so kernel, initrd, and root image testing is iterative without flashing them.

After building the images, use the following sequence:

1. In one terminal, prepare a writable NBD root image, start its server, and wait for the phone's USB-NCM interface. The recipe refreshes /tmp/nixos-root.raw, makes that temporary copy writable for nbd-server, stops the NBD server it previously started, and starts a new one on port 9999. nbd-server listens on all host addresses, so the USB-NCM interface does not need to exist yet:

   just netboot-up

   netboot-up waits up to three minutes for the interface; pass a different duration in seconds if needed, for example just netboot-up 300.

   The boot image and root image must come from the same nix build. Rebuilding can change the NixOS closure hash embedded in nixos-netboot.img. Run just netboot-server after every rebuild; reusing an older /tmp/nixos-root.raw makes initrd-find-nixos-closure fail even when NBD itself connects successfully. To stop the managed server after a test, run just netboot-server-stop. A manually started NBD server is never stopped automatically; stop it yourself before using the recipe.

2. Power off the phone and enter fastboot/bootloader mode using the key combination described above.

3. Connect the phone to the build host over USB and start U-Boot in RAM:

   fastboot boot result/u-boot.img

4. When the U-Boot menu appears, choose Enable fastboot mode. If the menu does not appear, hold Volume Down while U-Boot is starting. The USB device will disconnect and re-enumerate as U-Boot fastboot.

5. Confirm that the second-stage fastboot device is visible, then send the NixOS image to U-Boot's RAM buffer:

   fastboot devices
   fastboot boot result/nixos-netboot.img

6. netboot-up detects the OnePlus USB-NCM interface automatically when it is the only one, configures it with 172.16.42.2/24, and temporarily permits NBD TCP port 9999 only on that interface. If multiple USB-NCM interfaces are connected, it stops rather than guessing; configure the intended one with just netboot-network <usb-network-interface>.

   When the netboot session is over, power off the phone, then remove the temporary NetworkManager profile, firewall exception, and managed NBD server:

   just netboot-down

The initrd creates the USB-NCM gadget, assigns the phone 172.16.42.1/24, and connects /dev/nbd0 to the host. NixOS finds and mounts its Btrfs root by the nixos-root filesystem label. Keep the NBD server and USB cable connected for the entire boot. U-Boot's fastboot server waits for commands; there is no Android fastboot boot timeout during the host-side setup. The second fastboot boot command must be sent after selecting U-Boot's fastboot mode.

First boot

The installer starts a USB network gadget; connect from the build host with:

ssh -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -o PasswordAuthentication=yes -o PreferredAuthentications=password nixos@172.16.42.1

The nixos and root installer accounts have empty passwords. Use nmtui to configure Wi-Fi when needed.

Check Accelerometer:

ssh -F /dev/null -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null nixos@172.16.42.1 'sudo busctl --system call net.hadess.SensorProxy /net/hadess/SensorProxy net.hadess.SensorProxy ClaimAccelerometer; sleep 1; sudo busctl --system get-property net.hadess.SensorProxy /net/hadess/SensorProxy net.hadess.SensorProxy AccelerometerOrientation; sudo busctl --system get-property net.hadess.SensorProxy /net/hadess/SensorProxy net.hadess.SensorProxy AccelerometerTilt; sudo busctl --system call net.hadess.SensorProxy /net/hadess/SensorProxy net.hadess.SensorProxy ReleaseAccelerometer'

Further work

• Validate and document the OnePlus 6 fastboot partition/slot mapping.
• Test boot, display, touch, Wi-Fi, Bluetooth, modem, audio, sensors, suspend, and USB networking on real hardware.
• Record a recovery procedure before treating this configuration as daily-use ready.