Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/S-PScripts/chromebook-utilities/llms.txt

Use this file to discover all available pages before exploring further.

There are two fundamentally different approaches to running Linux on a managed Chromebook. The first is running Linux inside ChromeOS — this is what Crostini (the official Linux container feature) does, and it normally requires the admin to enable it. The second approach is replacing or bypassing ChromeOS at boot, using a modified shim image, a USB boot, or a root exploit to get a full Linux shell. The methods on this page all fall into the second category: they operate outside ChromeOS and give you a real Linux distro or root shell. Most require a USB drive, a separate Linux or Windows PC to build the image, and in some cases a physical write-protect bypass — read the requirements for each method carefully before proceeding.
These methods may require enabling developer mode, unenrolling your device, or flashing firmware. Developer mode will powerwash your Chromebook and erase all local data. Unenrolling a school-managed device may be a policy violation with serious consequences. Firmware flashing carries a risk of bricking your device. Proceed at your own risk.

​
Shimboot — Debian Linux via RMA Shim

Shimboot patches a Chrome OS RMA shim to act as a bootloader for a standard Debian Linux installation. It lets you boot a full Debian desktop without unenrolling your Chromebook or modifying firmware. Credits: ading2210 — github.com/ading2210/shimboot | shimboot.ading.dev

​
Requirements

  • A separate Linux PC for the build process (preferably Debian-based)
    • WSL2 on Windows is supported
    • GitHub Codespaces is not supported
  • A USB drive at least 8 GB in size
  • At least 20 GB of free disk space on the build machine
  • An x86-based Chromebook

​
Build the Image (Automated)

1

Find your board name

Search for your Chromebook model name at cros.download to find the correct board name.
2

Clone the repository

git clone https://github.com/ading2210/shimboot
cd shimboot
3

Build the disk image

sudo ./build_complete.sh <board_name>
Replace <board_name> with your Chromebook’s board name. This downloads the required data and builds everything automatically.

​
Build the Image (Manual Steps)

If you prefer to run each step yourself:
1

Obtain an RMA shim

Find a Chrome OS RMA shim for your board. Most have been publicly leaked and are searchable online.
2

Download a recovery image

Download a ChromeOS recovery image for your board from chromiumdash.appspot.com/serving-builds?deviceCategory=ChromeOS. Unzip both the shim and the recovery image.
3

Create the rootfs directory

mkdir -p data/rootfs
4

Build the base rootfs

sudo ./build_rootfs.sh data/rootfs bookworm
5

Patch the rootfs

sudo ./patch_rootfs.sh path_to_shim path_to_recovery data/rootfs
6

Generate the disk image

sudo ./build.sh image.bin path_to_shim data/rootfs

​
Boot Shimboot

1

Get a shimboot image

Either use your built image.bin or download a prebuilt image from github.com/ading2210/shimboot/releases.
2

Flash to USB

Flash the image to a USB drive or SD card using Chromebook Recovery Utility or dd on Linux.
3

Enable developer mode

Enable developer mode on your Chromebook. If enrolled, follow the sh1mmer instructions at sh1mmer.me (see “Executing on Chromebook”).
4

Boot from USB

Plug the USB into your Chromebook and enter recovery mode. Shimboot should auto-detect the USB and launch.
5

Log in to Debian

Log in with the username and password you configured. Prebuilt image defaults: username user, password user.
6

Expand the filesystem

sudo growpart /dev/sdX 4
sudo resize2fs /dev/sdX4
Replace sdX with the block device for your USB drive. This expands the partition to fill the full disk.
7

Change your password

passwd user
The root user is disabled by default.

​
TerraOS — Multiple Linux Distros via RMA Shim

TerraOS boots Linux distros from an RMA shim without modifying your existing ChromeOS installation. It supports x86_64 Chromebooks and experimentally supports jacuzzi board Chromebooks. Credits: r58Playz — github.com/r58Playz/terraos

​
Requirements

  • A separate build machine (Linux)
  • An RMA shim for your board
  • A ChromeOS recovery image for your board
  • A Chrome OS Flex recovery image of the same version

​
Build and Install

1

Clone the repository

git clone https://github.com/r58Playz/terraos.git
2

Create a build directory

Inside the cloned directory, create a build subdirectory:
mkdir build && cd build
3

Build Stage 1

bash ../scripts/build_stage1.sh <defconfig>
Use terraos as the defconfig for x86_64 Chromebooks. Use terraos_jacuzzi for jacuzzi board Chromebooks (experimental).
4

Build AUR packages

bash ../scripts/build_aur_packages.sh
5

Build the full image

bash ../scripts/build_all.sh <shim.bin> <board_recovery.bin> <reven_recovery.bin>
Replace <shim.bin>, <board_recovery.bin>, and <reven_recovery.bin> with the paths to your shim, board recovery image, and Chrome OS Flex recovery image respectively.
The build outputs a bootloader image, SquashFS, arch RootFS tarballs, and combined images (arch RootFS + TerraOS ChromeOS). The default arch RootFS credentials are username terraos, password terraos.

​
Root ChromeOS with Tunety

Tunety is a patched exploit that used tune2fs to mark a partition as corrupt and trigger a kernel panic in a specific way to obtain a VT2 root shell — without unenrolling or replacing ChromeOS. The root shell persists until closed.
This exploit has been patched by Google. It involved multiple race conditions and required up to 50 reboots in rare cases. It is documented here for reference only.
Credits: Crystal — omada.cafe/contact/crystals/blog/article/2024/12/11/

​
How It Worked

1

Download tunety.bin

Download tunety.bin from omada.cafe/contact/crystals/blog/assets/tunety.bin.
2

Flash to USB or SD card

Flash it using ChromeOS Recovery Utility, Fedora Media Writer, Etcher, Rufus, or any other flashing tool.
3

Sign in to your Chromebook

Sign in normally on your Chromebook.
4

Plug in the USB

Plug in the flashed USB drive or SD card.
5

Wait for the root shell

Wait to be automatically rebooted into a root shell. If it doesn’t work, try up to 25 times — the exploit relies on race conditions and is not deterministic.

​
Boot from USB (USBoot)

The simplest method for running an alternative OS: enable developer mode, set the USB boot flag, and press Ctrl+U at the OS verification screen to boot from any bootable USB.

​
Requirements

  • Developer mode enabled on your Chromebook

​
Instructions

1

Enter recovery mode to enable developer mode

Hold Esc + Power + Refresh simultaneously to enter recovery mode, then follow the prompts to enable developer mode. This will powerwash your device.
2

Boot to internal disk

On the OS verification screen, select Boot from internal disk.
3

Open a VT2 shell

Press Ctrl + Alt + F2 to switch to a terminal.
4

Enable USB boot

sudo crossystem dev_boot_usb=1
5

Boot from USB

Return to the OS verification screen and press Ctrl + U to boot from the plugged-in USB drive.
Credits: JackWagon885 — the-wagonization.github.io/The-Wagon-Site/
Some Linux install methods (particularly full firmware replacement approaches) require disabling hardware write protect first. See the Hardware Write Protect page for instructions specific to your Chromebook model.
The Chromebook modding community maintains extensive documentation and support channels. Two key resources are Titanium Network (docs.titaniumnetwork.org) and Mercury Workshop (mercurywork.shop), both of which cover ChromeOS exploits, shim booting, and Linux installs in detail.

Build docs developers (and LLMs) love

Get started for freeTalk to us