LevitateOS

Documentation

recstrap

Extract the LevitateOS base system to a target directory. Like pacstrap for Arch Linux.

Section

Overview

recstrap extracts the LevitateOS EROFS image from the live ISO to a mounted target directory. This is the equivalent of Arch Linux's pacstrap command.

recstrap is EROFS-only. Files that are not .erofs images (including .squashfs) are rejected.

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.

After running recstrap, you must manually complete the installation: generate /etc/fstab, install a bootloader, set passwords, and configure the system.

Section

Usage

Command
bash 
recstrap [OPTIONS] <TARGET>
Argument Description
TARGET Target directory (must be mounted, e.g., /mnt)

Section

Options

Option Description
--rootfs <PATH> Custom rootfs image location (must end in .erofs; auto-detected from live media if not specified)
-f, --force Allow extraction even if target is not empty or not a mount point
-q, --quiet Minimal output for scripting
-c, --check Run pre-flight validation only, do not extract
--version Show version
--help Show help

Section

Examples

Extract to mounted root partition 
recstrap /mnt
Use custom EROFS image location 
recstrap /mnt --rootfs /media/usb/filesystem.erofs
Run pre-flight checks only (no extraction) 
recstrap /mnt --check
Force extraction to non-empty directory 
recstrap /mnt --force

Section

Pre-flight Validation

Before extraction, recstrap validates critical conditions to catch problems early. Use --check to run only validation without extracting.

  1. Running as root
  2. fsck.erofs is available
  3. Target directory exists
  4. Target is a directory (not a file)
  5. Target is not a protected system path
  6. Target is writable
  7. Target is a mount point (skipped with --force)
  8. Target is empty (skipped with --force; lost+found ignored)
  9. Sufficient disk space (minimum 2GB)
  10. EROFS image exists
  11. EROFS image is a regular file
  12. Rootfs filename ends with .erofs
  13. EROFS image is readable
  14. EROFS image is not inside the target directory
  15. EROFS superblock magic is valid
  16. Kernel has EROFS support available

Section

EROFS Auto-Detection

If --rootfs is not specified, recstrap searches these paths in order:

  • /run/live-rootfs.erofs
  • /run/live-media/live/filesystem.erofs
  • /run/initramfs/live/filesystem.erofs
  • /run/archiso/bootmnt/live/filesystem.erofs
  • /mnt/cdrom/live/filesystem.erofs
  • /media/cdrom/live/filesystem.erofs

Section

Protected Paths

These paths are always blocked as extraction targets, even with --force:

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 Target directory not writable
E004 4 EROFS image not found
E005 5 EROFS extraction command failed
E006 6 Extracted system verification failed
E008 8 Must run as root
E009 9 Target directory not empty (use --force)
E010 10 Target is a protected system path
E011 11 Target is not a mount point (use --force)
E012 12 Insufficient disk space
E013 13 EROFS image is not a regular file
E014 14 EROFS image is not readable
E015 15 EROFS image is inside target directory
E016 16 Rootfs format is invalid (not a valid .erofs image)
E017 17 Kernel EROFS support is unavailable

Section

Post-Extraction

After recstrap completes, continue with the installation:

Command
bash 
# Generate fstab
recfstab /mnt >> /mnt/etc/fstab

# Copy pre-built UKIs from live media
mkdir -p /mnt/boot/EFI/Linux
cp /run/live-media/boot/uki/levitateos-system-a.efi /mnt/boot/EFI/Linux/
cp /run/live-media/boot/uki/levitateos-system-b.efi /mnt/boot/EFI/Linux/

# Enter chroot
recchroot /mnt

# Optional: apply user setup script generated by recstrap
bash /root/setup-initial-user.sh

# Or set root password directly (root is locked by default)
passwd root

# Install bootloader (auto-discovers UKI)
bootctl install

# Exit and reboot
exit
reboot

Section

Comparison with pacstrap

Feature recstrap pacstrap
Source EROFS image Package repository
Speed Fast (extract only) Slower (download + install)
Package selection Full base system Selectable packages
Offline capable Yes (from live ISO) No (needs network)

Section

See Also