crouton: Chromium OS Universal Chroot Environment

crouton is a set of scripts that bundle up into an easy-to-use, Chromium OS-centric chroot generator. Ubuntu, Debian, and Kali are supported (using debootstrap behind the scenes), but "Chromium OS Debian and Ubuntu (plus one distro) EOL'd Chroot Environment" doesn't acronymize as well (crodupodece is admittedly pretty fun to say, though).

🪦 crouton is now end-of-life 🪦

All good things must come to an end, and considering

• Chromium OS's introduction of increasingly strict shell safeguards,
• the change in cras's build tools,
• the removal of manifest v2 extensions,
• the removal of PNaCl, breaking xiwi,
• oh, and Chromium OS being replaced by Android

there's really not much to gain from continued development. Put another way, the proverbial mixed salad is just about out of tasty crunchy bits, and the remaining morsels have gone a bit stale. And for some reason someone's about to swap all the lettuce out for onion rings? Point is, it's time to stop mixing dressings. Unless it's ranch, I guess, since that goes with just about anything. But this is crouton, not some Ready-for-Android Native Chroot Host, alas.

Anyway, this means that:

• The repo is now locked, and no further changes will be considered.
• Eventually someone will want the latest Ubuntu added to the release list. See this commit for an example of how to do it on your own copy.
• Sometime around July 2025, the GitHub project will be archived, making the issue tracker, discussions, and wiki read-only.
• For the safety of users and stability of crouton's functionality for those on EOL devices, offers to take over the dnschneid/crouton repo or extension will be declined, and requests to change link destinations will be rejected.

If you have an EOL device, though, crouton is still a great match for you!

• Chromium OS version 110 and earlier, everything should work! Breathe new life into your old devices!!
• Starting 111, crouton can't compile cras, so audio devices cannot be shared with Chromium OS
• Starting 117, sudo in crosh is disabled and you'll need to use VT-2
• Starting 133 (139 for enterprise devices), manifest v2 is disabled and you won't be able to run the extension (easy switching, clipboard sync, xiwi)
• Also starting 133 (139 for enterprise devices), pnacl is disabled, so even if you somehow got the extension working, xiwi won't function
• Beyond that, it's anybody's guess as to what will break

Moving right along...

:warning: Steps to install crouton have changed! :warning:

Chromium OS has introduced several security features over the years that impede the installation and usage of crouton. If your device is no longer receiving updates, the steps below will likely work for you. However, if you are still having trouble, please try the community-maintained instructions.

In addition, goo.gl is going away! That means the goo.gl/fd3zc you know and love has been replaced with git.io/JZEs0. That's a zero at the end, if you were wondering. Both just point to github, so you can always just memorize the full link instead, which (fun fact) does not include any numbers at all!

"crouton"...an acronym?

It stands for ChRomium Os Universal chrooT envirONment ...or something like that. Do capitals really matter if caps-lock has been (mostly) banished, and the keycaps are all lower-case?

Moving on...

Who's this for?

Anyone who wants to run straight Linux on their Chromium OS device, and doesn't care about physical security. You're also better off having some knowledge of Linux tools and the command line in case things go funny, but it's not strictly necessary.

What's a chroot?

Like virtualization, chroots provide the guest OS with their own, segregated file system to run in, allowing applications to run in a different binary environment from the host OS. Unlike virtualization, you are not booting a second OS; instead, the guest OS is running using the Chromium OS system. The benefit to this is that there is zero speed penalty since everything is run natively, and you aren't wasting RAM to boot two OSes at the same time. The downside is that you must be running the correct chroot for your hardware, the software must be compatible with Chromium OS's kernel, and machine resources are inextricably tied between the host Chromium OS and the guest OS. What this means is that while the chroot cannot directly access files outside of its view, it can access all of your hardware devices, including the entire contents of memory. A root exploit in your guest OS will essentially have unfettered access to the rest of Chromium OS.

...but hey, you can run TuxRacer!

What about dem crostinis though?

Crostini is an official project within Chromium OS to bring the Linux shell and apps to the platform in verified mode with clean integration, multi-layered security, and all the polish you expect from Chromium OS proper.

That means compared to crouton, Crostini has official support, competent engineers, and code that looks a little less like ramen. crouton, in its defense, has wider device compatibility, enables direct hardware access, and is named after an objectively tastier bread-based food item.

There's a solid community on Reddit if you'd like to try Crostini out. If it works for you -- great! No hard feelings. If in the end you decide that crouton suits you better, read on!

Note: you can't get the best of both worlds by installing crouton inside of Crostini. The technology (and life itself) just doesn't work that way. Not to mention a crouton Crostini would look ridiculous and be impossible to eat without getting bits everywhere.

Prerequisites

You need a device running Chromium OS that has been switched to developer mode.

For instructions on how to do that, go to this Chromium OS wiki page, click on your device model and follow the steps in the Entering Developer Mode section.

Note that developer mode, in its default configuration, is completely insecure, so don't expect a password in your chroot to keep anyone from your data. crouton does support encrypting chroots, but the encryption is only as strong as the quality of your passphrase. Consider this your warning.

It's also highly recommended that you install the crouton extension, which, when combined with the extension or xiwi targets, provides much improved integration with Chromium OS.

That's it! Surprised?

Usage

crouton is a powerful tool, and there are a lot of features, but basic usage is as simple as possible by design.

If you're just here to use crouton, you can grab the latest release from https://git.io/JZEs0. Download it, pop open a shell (Ctrl+Alt+T, type shell and hit enter), make the installer executable with sudo install -Dt /usr/local/bin -m 755 ~/Downloads/crouton, then launch it with sudo crouton to see the help text. See the "examples" section for some usage examples.

If you're modifying crouton, you'll probably want to clone or download the repo into a subdirectory of /usr/local and then either run installer/main.sh directly, or use make to build your very own crouton. You can also download the latest release, install it as above and run crouton -x to extract out the juicy scripts contained within, but you'll be missing build-time stuff like the Makefile. You also need to remember to place the unbundled scripts somewhere in /usr/local in order to be able to execute them.

crouton uses the concept of "targets" to decide what to install. While you will have apt-get in your chroot, some targets may need minor hacks to avoid issues when running in the chrooted environment. As such, if you expect to want something that is fulfilled by a target, install that target when you make the chroot and you'll have an easier time. Don't worry if you forget to include a target; you can always update the chroot later and add it. You can see the list of available targets by running crouton -t help.

Once you've set up your chroot, you can easily enter it using the newly-installed enter-chroot command, or one of the target-specific start* commands. Ta-da! That was easy.

Examples

The easy way (assuming you want an Ubuntu LTS with Xfce)

1. Download crouton
2. Open a shell (Ctrl+Alt+T, type shell and hit enter)
3. Copy the installer to an executable location by running sudo install -Dt /usr/local/bin -m 755 ~/Downloads/crouton
4. Now that it's executable, run the installer itself: sudo crouton -t xfce
5. Wait patiently and answer the prompts like a good person.
6. Done! You can jump straight to your Xfce session by running sudo enter-chroot startxfce4 or, as a special shortcut, sudo startxfce4
7. Cycle through Chromium OS and your running graphical chroots using Ctrl+Alt+Shift+Back and Ctrl+Alt+Shift+Forward.
8. Exit the chroot by logging out of Xfce.

With encryption!

1. Add the -e parameter when you run crouton to create an encrypted chroot or encrypt a non-encrypted chroot.
2. You can get some extra protection on your chroot by storing the decryption