Create a USB stick
The ISO is a hybrid image: write it to the whole stick, not to a partition. A stick of 8 GB or more is enough. Everything on the stick is erased. Write only an image you have verified (Download & verify).
With install.sh (Linux)
install.sh downloads the latest published release. Until the first River release is
tagged and published, there is nothing for it to fetch and this path cannot work — use
By hand below with a locally built image. See Releases for what exists.install.sh downloads and verifies the image first, then writes it:
curl -fsSL https://raw.githubusercontent.com/org-runink/river/main/install.sh | sh -s -- --write /dev/sdXIt refuses a device that is not a whole disk, is neither USB nor removable, is mounted, or
reports no serial number. Before it writes, it shows the stick’s model, size and serial and
asks you to type the serial, so a typo in /dev/sdX cannot erase the wrong disk. For a
scripted run, pass the serial you checked with --yes-i-have-checked-serial=SERIAL.
The script never runs sudo. Run as a normal user, it verifies the image and the stick, then
prints the one command that needs root, for you to run:
sudo dd if=./runink-river-<YYYYMMDD>-x86_64.iso of=/dev/sdX bs=4M conv=fsync oflag=direct status=progressAdd --dry-run to see what it would write without writing anything, and --out DIR when the
image is in, or should go to, another directory. Every flag is described on
Download & verify.
By hand (Linux)
Find the stick, check its size, model and serial, unmount anything mounted from it, then write the verified image:
lsblk -o NAME,SIZE,MODEL,SERIAL,TRAN,MOUNTPOINTS # the stick shows TRAN=usb
sudo umount /dev/sdX1 # for each mounted partition of the stick
sudo dd if=runink-river-<YYYYMMDD>-x86_64.iso of=/dev/sdX bs=4M conv=fsync oflag=direct status=progress
sync/dev/sdX is the whole device (/dev/sdb), never a partition (/dev/sdb1).
Check the stick afterwards
dd reporting success is not the same as the stick holding the image. A failing or
counterfeit stick accepts every write and returns different bytes on the next read, and
conv=fsync cannot detect that. Read it back and compare:
sudo cmp -n $(stat -c %s runink-river-<YYYYMMDD>-x86_64.iso) \
runink-river-<YYYYMMDD>-x86_64.iso /dev/sdX && echo "the stick matches the image"cmp prints nothing and exits 0 when every byte matches; it names the first differing byte
otherwise. The -n limit stops it at the image’s length, because the stick is larger than
the image and everything past the end is expected to differ.
A stick that writes without error and fails this is the one that boots to a GRUB rescue prompt or a kernel panic much later, when the cause is no longer obvious.
From Windows or macOS
Any tool that writes a raw disk image byte for byte works. Pick “write an image as-is” (dd mode) if the tool asks, and verify the image before you write it.
Boot it
Plug the stick in, open your firmware’s boot menu (often F12, F11, F8 or Esc at power-on) and pick the USB stick’s UEFI entry. Turn Secure Boot off first: the image does not boot with Secure Boot on yet (Secure Boot).
The stick’s live system then opens the installer by itself: Install. It does not start? Troubleshooting.
Reuse the stick afterwards
The installer never offers the stick as a target and never saves the recovery key to it. To
use the stick for files again, recreate a partition table and a filesystem on it with
parted or gdisk (on the installed system) or any partitioning tool.