Boot ChromeOS on x86_64 PC (supports most Intel CPU/GPU or AMD Stoney Ridge)
First of all, thanks goes to project Croissant, the swtpm maintainer and the Chromebrew framework for their work which was actively used when creating this project.
The purpose of the Brunch framework is to create a generic x86_64 ChromeOS image from an official recovery image. To do so, it uses a 1GB ROOTC partition (containing a custom kernel, an initramfs, the swtpm binaries, userspace patches and config files) and a specific EFI partition to boot from it.
Warning: As Brunch is not the intended way for ChromeOS to work, at some point a ChromeOS script could potentially behave badly with Brunch and delete data unexpectedly (even on non-ChromeOS partitions). Also, ChromeOS recovery images include device firmware updates that a close enough device might potentially accept and get flashed with the wrong firmware. By installing Brunch you agree to take those risks and I cannot be held responsible for anything bad that would happen to your device including data loss. It is therefore highly recommended to only use this framework on a device which does not contain any sensitive data and to keep non-sensitive data synced with a cloud service.
Hardware support is highly dependent on the general Linux kernel hardware compatibility. As such only Linux supported hardware will work and the same specific kernel command line options recommended for your device should be passed through the GRUB bootloader (see "Modify the GRUB bootloader" section).
Base hardware compatibility: - x8664 computers with UEFI boot support (BIOS/MBR devices have limited support through a specific procedure detailled in "Limited support for MBR/BIOS devices" section), - Intel hardware (CPU and GPU) starting from 1st generation "Nehalem" (refer to https://en.wikipedia.org/wiki/IntelCore), - AMD Ryzen 3XXX (CPU and GPU), only with "zork" recovery image (newer Ryzen models are not yet supported), - AMD Stoney Ridge (refer to https://en.wikipedia.org/wiki/ListofAMDacceleratedprocessing_units), only with "grunt" recovery image (older AMD CPU are not supported), - Devices having only a Nvidia graphic card are not supported.
Notes: - Intel Gen 1 graphics do not work with ChromeOS versions above r81 (it might still change with a future ChromeOS update). - Some Intel 10th Gen devices do not seem to be compatible with the android container. - Intel 11th Gen devices are not supported for now.
Specific hardware support: - sensors: an experimental patch aims to allow intel ISH accelerometer and light sensors through a custom kernel module, - Microsoft Surface devices: dedicated kernel patches are included.
Additional features: - nano text editor - efibootmgr
2 types of ChromeOS recovery images exist and use different device configuration mechanisms: - non-unibuild images: configured for single device configurations like eve (Google Pixelbook) and nocturne (Google Pixel Slate) for example. - unibuild images: intended to manage multiple devices through the use of the CrosConfig tool.
Contrarily to the Croissant framework which mostly supports non-unibuilds images (configuration and access to android apps), Brunch should work with both but will provide better hardware support for unibuild images.
Currently: - "rammus" is the recommended image for devices with 4th generation Intel CPU and newer. - "samus" is the recommended image for devices with 3rd generation Intel CPU and older. - "zork" is the image to use for AMD Ryzen 3XXX. - "grunt" is the image to use for AMD Stoney Ridge.
ChromeOS recovery images can be downloaded from: https://cros-updates-serving.appspot.com/ or https://cros.tech/
If you are not comfortable with the linux commands in the below instructions, the "brunch-toolkit" provided by WesBosch has been designed to make installing and updating brunch easy: https://github.com/WesBosch/brunch-toolkit
General features (available within Brunch, Linux & WSL): - Check user's CPU for Brunch compatibility. - Suggest usable recoveries based on user's hardware. - Install Brunch to disk or partition.
Features available when used within a brunch install: - Update ChromeOS and/or Brunch. - Modify the ChromeOS start up animation.
In case you run into issues while installing / using Brunch, below are the main places where you can find support: - Discord: https://discord.gg/x2EgK2M - Telegram: https://t.me/chromeosforpc - Reddit: https://www.reddit.com/r/Brunchbook
You can install ChromeOS on a USB flash drive / SD card (16GB minimum) or as an image on your hard disk for dual booting (14GB of free space needed).
pv,
tarand
cgptpackages/binaries.
tar zxvf brunch_< version >.tar.gz
sudo bash chromeos-install.sh -src < path to the ChromeOS recovery image > -dst < your USB flash drive / SD card device. e.g. /dev/sdX >
The GRUB menu should appear, select ChromeOS and after a few minutes (the Brunch framework is building itself on the first boot), you should be greeted by ChromeOS startup screen. You can now start using ChromeOS.
ChromeOS partition scheme is very specific which makes it difficult to dual boot. One solution to circumvent that is to keep ChromeOS in a disk image on the hard drive and run it from there.
Make sure you have an ext4 (recommended) or NTFS partition with at least 14gb of free space available and no encryption or create one (refer to online resources).
tar zxvf brunch_< version >.tar.gz
mkdir -p ~/tmpmount sudo mount < the destination partition (ext4 or ntfs) which will contain the disk image > ~/tmpmount
sudo bash chromeos-install.sh -src < path to the ChromeOS recovery image > -dst ~/tmpmount/chromeos.img -s < size you want to give to your chromeos install in GB (system partitions will take around 10GB, the rest will be for your data) >
sudo cp /etc/grub.d/40_custom /etc/grub.d/99_brunch
sudo nano /etc/grub.d/99_brunch, paste the grub config at the end of the file. Save the changes and exit nano (CTRL-X).
sudo update-grub.
sudo umount ~/tmpmount
sudo mokutil --import brunch.der
The GRUB menu should appear, select "ChromeOS (boot from disk image)" and after a few minutes (the Brunch framework is building itself on the first boot), you should be greeted by ChromeOS startup screen. You can now start using ChromeOS from your HDD.
sudo apt update && sudo apt install pv tar cgpt
cd:
cd /mnt/c/Users/< username >/Downloads/
sudo tar zxvf brunch_< version >.tar.gz
sudo bash chromeos-install.sh -src < path to the ChromeOS recovery image > -dst chromeos.img
root
sudo resize-data
shellat the invite).
mkdir -p ~/tmpmount sudo mount < the destination partition (ext4 or ntfs) which will contain the disk image > ~/tmpmount
sudo bash chromeos-install -dst ~/tmpmount/chromeos.img -s < size you want to give to your chromeos install in GB (system partitions will take around 10GB, the rest will be for your data) >
sudo nano ~/tmpmount/chromeos.grub.txtand paste the config there (CTRL°SHIFT+V to paste and then CTRL-X to exit)
sudo umount ~/tmpmount
Manage Boot Menubutton, then
Add A New Entry.
submenuin the 'Type' section and input "Chrome OS" as title.
Edit Custom Codethis will open a text file. Open the chromeos.grub.txt file we saved in step 7 and copy the grub configuration in grub2win. #### Then remove the "rmmod tpm" line.
Okand
apply(It won't save your entry unless you click
okand
apply)
shellat the invite)
sudo chromeos-install -dst < your HDD device. e.g. /dev/sdX >
Note: Even if you boot from GRUB on your HDD, if you have a ChromeOS USB flash drive / SD card inserted, the initramfs will boot from it in priority.
The GRUB menu should appear, select ChromeOS and after a few minutes (the Brunch framework is building itself on the first boot), you should be greeted by ChromeOS startup screen. You can now start using ChromeOS.
The mbr_support.tar.gz patch present in the this branch (master) allows booting Brunch on BIOS/MBR devices with a few limitations: - Brunch can only be installed from linux. - The dual boot method is not supported.
Installation procedure: 1) Verify that your device cpu/gpu is supported according to the "base hardware compatibility" requirements. 2) Verify that
pv,
tar,
cgptand
sgdiskpackages/binaries are installed. 3) Extract the brunch release archive to your working directory. 4) Extract the mbr_support.tar.gz patch present in the this branch (master) of the Brunch repo in the same directory (overwriting files when requested) 5) Download the ChromeOS recovery image and extract it. 6) Follow the linux "Install ChromeOS on a USB flash drive / SD card / HDD (full disk install / single boot)" instructions from step 5.
Some options can be passed through the kernel command lines to activate specific features which might be dangerous or not work from everyone: - "enableupdates": allow native ChromeOS updates (use at your own risk: ChromeOS will be updated but not the Brunch framework/kernel which might render your ChromeOS install unstable or even unbootable), - "androidinitfix": alternative init to support devices on which the android container fails to start with the standard init, - "mountinternaldrives": allows automatic mounting of HDD partitions in ChromeOS (android media server will scan those drives which will cause high CPU usage until it has finished, it might take hours depending on your data), partition label will be used if it exists, - "broadcomwl": enable this option if you need the broadcomwl module, - "iwlwifibackport": enable this option if your intel wireless card is not supported natively in the kernel, - "rtl8188eu": enable this option if you have a rtl8188eu wireless card/adapter, - "rtl8723bu": enable this option if you have a rtl8723bu wireless card/adapter, - "rtl8723de": enable this option if you have a rtl8723de wireless card/adapter, - "rtl8812au": enable this option if you have a rtl8812au wireless card/adapter, - "rtl8814au": enable this option if you have a rtl8814au wireless card/adapter, - "rtl8821ce": enable this option if you have a rtl8821ce wireless card/adapter, - "rtl8821cu": enable this option if you have a rtl8821cu wireless card/adapter, - "rtl88x2bu": enable this option if you have a rtl88x2bu wireless card/adapter, - "rtbth": enable this option if you have a RT3290/RT3298LE bluetooth device, - "ipts": enable support for Surface devices touchscreen with kernel 5.4 / 5.10 (thanks go to the linux-surface team, especially StollD), - "oleddisplay": enable this option if you have an oled display (use with kernel 5.10), - "acpipowerbutton": try this option if long pressing the power button does not display the power menu, - "alttouchpadconfig": try this option if you have touchpad issues, - "alttouchpadconfig2": another option to try if you have touchpad issues, - "disableintelhda": some Chromebooks need to blacklist the sndhdaintel module, use this option to reproduce it, - "internalmicfix": allows to forcefully enable internal mic on some devices, - "asusc302": applies asus c302 specific firmwares and fixes, - "baytrailchromebook": applies baytrail chromebooks specific audio fixes, - "sysfstabletmode": allow to control tablet mode from sysfs (`echo 1 | sudo tee /sys/bus/platform/devices/tabletmodeswitch.0/tabletmode` to activate it or use 0 to disable it), - "forcetabletmode": same as above except tablet mode is enabled by default on boot, - "suspends3": disable suspend to idle (S0ix) and use S3 suspend instead, - "advancedals": default ChromeOS auto-brightness is very basic (https://chromium.googlesource.com/chromiumos/platform2/+/master/powermanager/docs/screenbrightness.md). This option activates more auto-brightness levels (based on the Google Pixel Slate implementation).
Add "options=option1,option2,..." (without spaces) to the kernel command line to activate them. you can add it after cros_debug and before loop.max.....
For example: booting with "options=enableupdates,advancedals" will activate both options.
Currently Brunch uses ChromiumOS kernel 5.4 by default as it is considered to be the most stable, however kernel 4.19 and an experimental kernel 5.10 are also included. If you want to try another kernel, you can replace "/kernel" in the grub configuration by "/kernel-4.19" or "/kernel-5.10".
WARNING: Changing kernel can prevent you from logging into your ChromeOS account, in which case a powerwash is the only solution (CTRL+ALT+SHIFT+R at the login screen). Therefore, before switching to a different kernel, make sure you have a backup of all your data.
Those are not options, just add them on the kernel command line after "crosdebug" and before "options=...." if any: - "enforcehyperthreading=1": improve performance by disabling a ChromeOS security feature and forcing hyperthreading everywhere (even in crositini). - "i915.enablefbc=0 i915.enablepsr=0": if you want to use crouton (needed with kernel 5.4). - "psmouse.elantechsmbus=1": fix needed for some elantech touchpads. - "psmouse.synapticsintertouch=1": enables gestures with more than 2 fingers on some touchpad models. - "console=": No text will be displayed on boot (it will not make boot faster).
like this:
shellat the invite)
cat /etc/brunch_version
It is currently recommended to only update ChromeOS when the matching version of the Brunch framework has been released.
shellat the invite)
sudo chromeos-update -r < path to the ChromeOS recovery image > -f < path to the Brunch release archive >
Note: BiteDasher created a script which updates both Brunch and ChromeOS with a single command: https://github.com/BiteDasher/brcr-update
If you chose to use the "enable_updates" option and have updated to a new ChromeOS release, you might want to update the brunch framework to match your current ChromeOS version.
shellat the invite)
sudo chromeos-update -f < path to the Brunch release archive >
mkdir /tmp/efi_part
sudo mount /dev/< partition 12 of ChromeOS device > /tmp/efi_part
sudo umount /tmp/efi_part
sudo edit-grub-config.
You can visit wiki https://github.com/sebanc/brunch/wiki
1) The instructions are difficult to follow as I am not familiar with Linux commands.
I can not go much deeper into details here for now but I will try to clarify the install process once I see the main pain points. Nevertheless, ChromeOS is based on Linux and it would probably be interesting for you to read online resources on Linux basics before attempting this.
2) My computer will not boot the created USB flash drive / SD card whereas it normally can (and I have correctly followed the instructions).
Some devices (notably Surface Go) will not boot a valid USB flash drive / SD card with secure boot on even if the shim binary is signed. For those devices, you will need to disable secure boot in your bios settings and use the legacy EFI bootloader by adding the "-l" parameter when running the chromeos-install.sh script.
3) The first boot and the ones after a framework change or an update are incredibly long.
Unfortunately, the Brunch framework has to rebuild itself by copying the original rootfs, modules and firmware files after each significant change. The time this process takes depends mostly on your USB flash drive / SD card write speed. You may try with one that has better write speed or use the dual boot method to install it on your HDD.
4) ChromeOS reboots randomly.
This can in theory be due to a lot of things. However, the most likely reason is that your USB flash drive / SD card is too slow. You may try with one that has better write speed or use the dual boot method to install it on your HDD.
5) Some apps do not appear on the playstore (Netflix...)
In order to have access to the ChromeOS shell, ChromeOS is started in developer mode by default. If you have a stable enough system, you can remove "cros_debug" from the GRUB kernel command line (see "Modify the GRUB bootloader" section) and then do a Powerwash (ChromeOS mechanism which will wipe all your data partition) to disable developer mode.
6) Some apps on the Playstore show as incompatible with my device.
Some Playstore apps are not compatible with genuine Chromebooks so it is probably normal.