CURRENT STATE: Works on dedede; board testing needed

Check progress and obstacles for current progress on this branch.

Note

This is a 'vibecoded' Proof-of-Concept project

The majority of this codebase were generated by Large-Language Models.
|
Consider creating a fork for reference.

Contributions and feedbacks are welcome by opening a discussion or an issue on the main branch. :3

To get started, follow the quickstart guide. (assuming you are in a linux environment)

NixOS Shimboot

This project was started since no one else released NixOS shimboot until now. This repository took place with flake approach over the existing scripts from ading2210/shimboot, which is mostly incompatible to build with a non-FHS distro like NixOS.

Before this repository, a bunch of attempts were made initially from nixos-shimboot-legacy, which also derived from shimboot-nixos.

This repository was initialized from scratch after nixos-shimboot-legacy due to inherited contributers and commits from ading2210/shimboot. Considering the amounts of change that's been made compared to the original repo, a clean repo was initialized to avoid potential misconceptions. The original GPLv3 license is kept except for proprietary/unfree chromeos artifacts that's used to shimboot NixOS.

Why NixOS?

While NixOS isn't the fastest nor the most minimal linux distribution to run on low-end hardware, it can be one of the most stable, up-to-date, and reproducible distros with proper configurations.

NixOS follows differently from the usual Filesystem Hierarchy Standard, where almost everything is configured and stored within /nix and /nix/store directories, including various Nix and systemd utilities that make NixOS configurations reproducible and usable.

In turn, users who've only used FHS compliant linux distributions (like Debian for example) will need to familiarize configuring Nix configurations to install packages, configure services and eventually build a custom, reproducible NixOS machine configuration.

If interested, strongly recommend trying NixOS in a VM first (or try the Nix package manager for distribution, if preferring to learn Nix first) following: https://nixos.org/download/
|
You may need to look up several online documentations, videos, or even Reddit and optional Large Language Model guidance (better suited if said LLM supports Model Context Protocols like context7) to learn what you'd wish to achieve with Nix/NixOS. Exploring someone else's NixOS configurations can also help reason and understand NixOS via first/second-hand experience.
|
Helpful sources like https://mynixos.com/ can show definitions, options, and available Nix packages.

What's shimboot?

A helpful excerpt from ading2210/shimboot's README:

Shimboot is a collection of scripts for patching a Chrome OS RMA shim to serve as a bootloader for a standard Linux distribution. It allows you to boot a full desktop Debian install on a Chromebook, without needing to unenroll it or modify the firmware.

Chrome OS RMA shims are bootable disk images which are designed to run a variety of diagnostic utilities on Chromebooks, and they'll work even if the device is enterprise enrolled. Unfortunately for Google, there exists a security flaw where the root filesystem of the RMA shim is not verified. This lets us replace the rootfs with anything we want, including a full Linux distribution.

Simply replacing the shim's rootfs doesn't work, as it boots in an environment friendly to the RMA shim, not regular Linux distros. To get around this, a separate bootloader is required to transition from the shim environment to the main rootfs. This bootloader then runs pivot_root to enter the rootfs, where it then starts the init system.

Another problem is encountered at this stage: the Chrome OS kernel will complain about systemd's mounts, and the boot process will hang. A simple workaround is to apply a patch to systemd, and then it can be recompiled and hosted at a repo somewhere.

After copying all the firmware from the recovery image and shim to the rootfs, we're able to boot to a mostly working XFCE desktop.

The main advantages of this approach are that you don't need to touch the device's firmware in order to run Linux. Simply rebooting and unplugging the USB drive will return the device to normal, which can be useful if the device is enterprise enrolled. However, since we are stuck with the kernel from the RMA shim, some features such as audio and suspend may not work.

TLDR: Gnu/Linux on common (enterprise-configured) chromebooks. It runs from a persistent USB, which can run linux distributions like Arch Linux

Why vibecode?

• Sunk cost fallacy.
• To explore how the models perform at specified tasks.
• Lack of programming background.

Why flake?

nixos-shimboot-legacy barely worked to build a bootable NixOS with frankenstein scripts running on hopes and dreams, yet it wasn't functional enough to even get past LightDM.

A minimal liveiso image under qemu environment was also considered to create a working ROOTFS that most likely has a working user environment came alight. It'd painful and inefficient.

Resorted back to nixos-generators, but this time using nix flakes with raw-efi image config. In the end, it made configurations more reliable.

Progress and obstacles

Flake status and roadmap (not a spec) for the current branch:

• Builds without flake errors
• Builds current NixOS configuration via nixos-generators
• Patches RMA shim's initramfs with shimboot bootloader and partitions into p2
• Partitions in ChromeOS format
• Builds bootable shim bootloader
• Builds bootable NixOS
• Builds bootable NixOS with running kill-frecon service (allowing graphics within shim)
• Builds functional NixOS with running greeter (LightDM)
• Builds functional NixOS with running user environment
• Builds functional NixOS with running hyprland
• Have functional networking
• nix-shell -p firefox works (note limited space without expand_rootfs)
• Builds functional NixOS with nixos-rebuild support (requires appending --option sandbox false on shim kernels below 5.6 due to missing kernel namespaces)
• Setup minimal base_configuration
• Setup initial main_configuration for hyprland and home-manager
• Implement multi-board compatibility in flake and build derivations (untested)
• Configure base_configuration to have zram
• Resolve firewall issues at boot
• Configure local cloned repo to have origin remote to sync from during assembly
• Configure base_configuration to be minimal whilst keeping lightdm and hyprland to achive lower image size
• Utilize systemd cachix store on local nixos-rebuild to avoid an eternal compilation on potato hardware (hardware r/w speed bottleneck)
• Functional GitHub build CI workflows with caching
• Show battery SoC in bootstrap menu
• Implement NixOS generation selector within bootstrapper
• Fix XDG redirect issues
• SDDM greeter support
• Utilize nixosModules to modularize various userland options, such as themes and WM/DE.
• Refine main_configuration [support bwrap/steam and refine nixos_setup]
• Create minimal main_configuration template
• Refine and cleanup scripts and helpers
• Refine and cleanup base and main configurations
• Build functional NixOS with LUKS2 support

Current obstacles:

• SDDM greeter support: previous attempts resulted in a blank backlit screen after kill-frecon. Need to evaluate logs and understand if SDDM can be supported declaratively.
• bwrap/steam: shim kernel limitations; need to understand how and if this can be patched safely. Workaround implemented: See BWRAP-LSM-WORKAROUND.md for details on using bwrap-safe wrapper.

Binary cache

This project has a Cachix binary cache for the patched systemd and nixos-shimboot closures:

• Substituter: https://shimboot-systemd-nixos.cachix.org
• Trusted public key:

shimboot-systemd-nixos.cachix.org-1:vCWmEtJq7hA2UOLN0s3njnGs9/EuX06kD7qOJMo2kAA=

If you wish to use this cache in your own configuration, add:

  nix.settings.substituters = [ "https://shimboot-systemd-nixos.cachix.org" ];
  nix.settings.trusted-public-keys = [ "shimboot-systemd-nixos.cachix.org-1:vCWmEtJq7hA2UOLN0s3njnGs9/EuX06kD7qOJMo2kAA=" ];

Source

Originally, the bootloader and systemd patches as well as the reference for bootstrapping, partitioning, and workarounds are sourced from: ading2210/shimboot and ading2210/chromeos-systemd

Miscellaneously, current dev enviroment consists of:

• NixOS+Hyprland
• VSCodium
  • Kilo Code

Credits:

• ading2210 - for creating the original shimboot repository
• ading2210/shimboot - bootloader/ source
• ading2210/chromeos-systemd - systemd mount_nofollow patch source to resolve/workaround Failed to mount API filesystems error
• discussion thread - useful feedbacks from this idea
• nixos-generators - builds nixos image from a configuration for use in ROOTFS (this became deprecated in favor of upstream methods instead)

License

Project Code

All original and shimboot derived code in this repository is licensed under GPLv3 (see LICENSE).

This includes:

• Nix flake configurations (flake.nix, flake_modules/)
• NixOS system modules (shimboot_config/)
• Build and utility scripts (tools/build/assemble-final.sh, etc.)
• Bootloader integration code (bootloader/ - originally derived from upstream shimboot)

Proprietary Components

The following components are NOT covered by GPLv3 and remain proprietary:

• ChromeOS RMA shims
• ChromeOS recovery images
• Extracted kernel modules, firmware blobs, and drivers

Nix Derivation Handling

Derivations that extract or process ChromeOS artifacts are marked with:

meta.license = lib.licenses.unfree;

And are allowed via:

config.allowUnfreePredicate = pkg:
  builtins.elem (lib.getName pkg) [
    "chromeos-shim"
    "chromeos-recovery"
    "extracted-kernel"
    "initramfs-extraction"
    "initramfs-patching"
  ];