Quick Start

Fastest path from zero to a booted Forest OS: get an image, verify it, write it to USB with dd, verify the stick, boot, and install to the internal disk. For full details see Install on Hardware and Install on a VM.

Warning: dd to the wrong device destroys data. Triple-check of= with lsblk before every write.

1. Get an image

Option A — Build from source

cd forest/fern
./conf.sh --defconfig && ./conf.sh --generate
make all
ls -lh ../foreboots/build/
# forebo.iso  # hybrid BIOS+UEFI ISO
# forebo.img  # raw BIOS disk image (MBR layout)
# esp.img     # FAT EFI System Partition

Option B — Download a release

wget https://github.com/Enclica-Forest/Forest/releases/latest/download/forebo.iso
wget https://github.com/Enclica-Forest/Forest/releases/latest/download/forebo.iso.sha256
sha256sum -c forebo.iso.sha256
# expected: forebo.iso: OK

2. Verify the image

Do this before writing anything. A corrupt image causes boot loops and stage errors.

ISO=../foreboots/build/forebo.iso
IMG=../foreboots/build/forebo.img

# MBR signature on the raw image (bytes 510-511 = 55 AA)
xxd -s 510 -l 2 "$IMG"
# expect: 55aa

# Kernel ELF magic at sector 48 (offset 48*512 = 7F 45 4C 46)
xxd -s $((48*512)) -l 4 "$IMG"
# expect: 7f45 4c46  (".ELF")

# Stage size constraints
make -C ../foreboots check
# stage1: exactly 512 B | stage2/3: <= 8192 B each

Rebuild if any check fails: make clean && make all in fern/.

3. Write the USB stick with dd

# 1. Identify the stick (NOT a partition like sdb1 — the whole disk, e.g. /dev/sdb).
lsblk -d -o NAME,SIZE,MODEL,TRAN

# 2. Unmount anything auto-mounted from it.
sudo umount /dev/sdX* 2>/dev/null; true

# 3. Write the image (hybrid ISO and raw IMG both work with dd).
sudo dd if=build/forebo.iso of=/dev/sdX bs=4M status=progress oflag=sync
sync

Replace /dev/sdX with your stick (e.g. /dev/sdb). oflag=sync + sync ensures all data is flushed before you unplug.

4. Verify the stick

# MBR signature must read back 55aa off the stick:
sudo dd if=/dev/sdX bs=512 count=1 2>/dev/null | xxd -s 510 -l 2
# expect: 55aa

# Stage2 magic 0xFEB1 (b1fe little-endian) at sector 1, offset 2:
sudo dd if=/dev/sdX bs=512 skip=1 count=1 2>/dev/null | xxd -s 2 -l 2
# expect: b1fe

# Partition table sanity:
sudo fdisk -l /dev/sdX

If either signature is wrong, rewrite per §3 with oflag=sync + sync before unplugging. A ~10 MiB image on a large stick shows mostly unallocated space — that is normal.

5. Boot and install to disk

Disable Secure Boot (unsigned BOOTX64.EFI), set SATA to AHCI, pick the USB stick from the one-time boot menu (F12/F8/F9/Esc).
At the ForeB menu pick Forest OS, confirm the live session works, then identify source vs target:
```
fdisk -l
blkid
lsblk -d -o NAME,SIZE,MODEL,TRAN
```

Copy the known-good stick to the internal disk (all data on target erased):

# sdX = USB stick, sdY = INTERNAL disk. Confirm both first.
dd if=/dev/sdX of=/dev/sdY bs=1M count=16
sync

Equivalently, from the build machine directly:

sudo dd if=build/forebo.img of=/dev/sdY bs=4M status=progress oflag=sync
sync

6. Verify the install, then reboot

# MBR signature must be 55aa:
dd if=/dev/sdY of=mbr.bin bs=512 count=1
# check bytes 510-511 == 55 AA
fdisk -l /dev/sdY
blkid /dev/sdY

# Stage2 magic check on target:
dd if=/dev/sdY bs=512 skip=1 count=1 2>/dev/null | xxd -s 2 -l 2
# expect: b1fe

sync, shut down, physically remove the USB stick.
Power on, select the internal disk — ForeB should appear from disk.
VM installs: use forinstall from the ISO instead (see Install on a VM); detach the ISO before first boot from disk.