LevitateOS

Documentation

recchroot

Enter a chroot environment with proper bind mounts. Like arch-chroot for Arch Linux.

Section

Overview

recchroot sets up the necessary bind mounts (/dev, /proc, /sys, /run), enters the chroot, runs your command (or an interactive shell), and cleans up on exit. This is the equivalent of Arch Linux's arch-chroot command.

WARNING

Default update model: A/B immutable (slot updates + rollback). Mutable mode is an explicit opt-in for daredevils, and is unsafe if you let an LLM author recipes without review.

The tool handles mount cleanup automatically, even if the command fails or is interrupted with Ctrl+C.

Section

Usage

Command
bash 
recchroot <CHROOT_DIR> [COMMAND]...
Argument Description
CHROOT_DIR Directory to chroot into (e.g., /mnt)
COMMAND Command to run (default: /bin/bash)

Section

Options

Option Description
--version Show version
--help Show help

Section

Examples

Enter interactive shell 
recchroot /mnt
Run single command 
recchroot /mnt passwd
Install bootloader 
recchroot /mnt bootctl install
Run multiple commands with shell 
recchroot /mnt /bin/bash -c 'passwd && bootctl install'

Section

Mount Handling

Required mounts (always created):

Source Target Purpose
/proc <chroot>/proc Process information filesystem
/sys <chroot>/sys Kernel/hardware information
/dev <chroot>/dev Device nodes
/run <chroot>/run Runtime data (udev, systemd)

Optional mounts (created if source exists):

Source Target Purpose
/sys/firmware/efi/efivars <chroot>/sys/firmware/efi/efivars EFI variables (for bootloader installation)

DNS resolution: /etc/resolv.conf is copied into the chroot so network operations work.

Section

Cleanup Behavior

Mounts are always cleaned up, even when:

  • The command exits with an error
  • The command is interrupted with Ctrl+C (SIGINT)
  • The process receives SIGTERM or SIGQUIT
  • Mount setup fails partway through

Unmounts are performed in reverse order with MNT_DETACH to handle busy filesystems. Unmount failures are warnings, not errors.

Section

Protected Paths

These paths cannot be used as chroot targets:

Command
text 
/  /bin  /boot  /dev  /etc  /home  /lib  /lib64  /opt
/proc  /root  /run  /sbin  /srv  /sys  /tmp  /usr  /var

Use a mount point like /mnt instead.

Section

Error Codes

Code Exit Description
E001 1 Target directory does not exist
E002 2 Target is not a directory
E003 3 Failed to create mount point directory
E004 4 Mount operation failed
E005 5 Unmount operation failed (warning only)
E006 6 Command execution failed
E007 7 Must run as root
E008 8 Target is a protected system path

Section

Exit Status

recchroot returns the exit status of the command run inside the chroot. If the command exits with status 0, recchroot exits with 0. If the command exits with status 5, recchroot exits with 5.

Errors from recchroot itself use the error codes in the table above.

Section

Comparison with arch-chroot

Feature recchroot arch-chroot
Bind mounts /proc, /sys, /dev, /run Same + /sys/firmware/efi/efivars
efivars mount Automatic if UEFI Automatic if UEFI
resolv.conf Copied Bind mounted
Cleanup on signal Yes Yes
Implementation Rust Bash script

Section

See Also