basecamp/omarchy

Create omarchy-chroot tool

Open

#2809 opened on Oct 24, 2025

View on GitHub
 (4 comments) (7 reactions) (0 assignees)Shell (22,948 stars) (2,295 forks)batch import
enhancementhelp wanted

Description

What do you need?

In recovery situations, it's often the case that we need to be able to use chroot to access our device from a failed state. It'd be great to add a tool that could be included in the ISO that makes this process a lot more seamless to accomplish if you have the ISO available to you on a USB to aid in debug / recovery.

Below are the steps I commonly use and supply to other. The idea is we could utilize gum prompts to allow the user to select the partitions instead and then handle some of the bits in the middle so we only have to get user input where we need it.

Accessing Chroot

  1. Run lsblk and identify your drive.

    Locate the partition that contains /home, usually the 2nd partition on the drive (nvme0n1p2, sda2, vda2, etc.)

  1. Open the LUKS2 container cryptsetup open /dev/{your_partition_id} crypt-drive
  • (You'll be prompted to enter your LUKS passphrase)

  1. Confirm the device is mapped ls -l /dev/mapper/ and you should see: crypt-drive -> ../dm-0 (or similar)

  2. Mount the unlocked device

mount -o subvol=@ /dev/mapper/crypt-drive /mnt
mount -o subvol=@home /dev/mapper/crypt-drive /mnt/home
mount -o subvol=@log /dev/mapper/crypt-drive /mnt/var/log

  1. Mount the boot device (if you need it available)

    mount /dev/{boot_partition} /mnt/boot

  2. Enter the chroot environment

    arch-chroot /mnt

  3. Inside chroot, list files (example command)

    ls -l

Contributor guide

Tech stack
shell
Domain
clitooling
Issue type
feature
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
3
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-2 days
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
fresh
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
clear
Prerequisites
Shell scriptingLinux file systemsLUKS/dm cryptchroot
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
50
Research direction
Implement the omarchy chroot tool according to the detailed steps provided. Use gum prompts for partition selection, mount encrypted volumes, and enter chroot. The tool should be written in Shell and integrated into the ISO. Ensure it handles user input and error cases gracefully. Review existing scripts in the repository for consistency in style and structure.