Skip to content
DOCUMENTATION

Quick start

This page takes you from a downloaded ISO to a running desktop. If you only want to try UFLinux, stop after Explore the live session — nothing is written to your disk until you run the installer.

Grab the ISO for your machine from the latest release together with its SHA256SUMS file, then check it:

Terminal window
sha256sum -c SHA256SUMS

If you have the gh CLI, you can also verify the build attestation:

Terminal window
gh attestation verify uflinux-0.1.0-x86_64.iso --repo UFlinux-project/uflinux3

See Downloads and verification for the full list of files.

Most desktop machines want the x86_64 ISO. It is the only image that has been boot-tested, on both legacy BIOS and UEFI firmware.

Write the ISO to a USB stick — GNOME Disks, dd, or pnpm-style writers all work:

Terminal window
doas dd if=uflinux-0.1.0-x86_64.iso of=/dev/sdX bs=4M oflag=sync status=progress

Boot from it. The live desktop starts automatically and logs you in as live. On a serial console, use live / live. The live image also provides a user / user account with password-authenticated sudo and doas, the same one the board and VM disk images ship.

The live session runs entirely from the media and does not need a network connection to reach the desktop. Two things to know:

  • The live account can run doas without a password. The root account is locked.
  • SSH is not enabled, so the machine is not reachable from the network by default.

The live image loads its root filesystem into RAM and includes Alpine’s full linux-firmware collection, so it needs noticeably more memory than an installed system. Plan for at least 4 GiB.

Networking is handled by ConnMan with iwd as its Wi-Fi backend. There is no wpa_supplicant, no NetworkManager, and no ntpd/chronyd — ConnMan’s own SNTP client keeps the clock.

Pick Network in the taskbar, or open Settings → Network, select your access point, and enter the passphrase. From a console, connmanctl works as usual. The same flyout has Bluetooth and WireGuard VPN tabs when the hardware is present.

The taskbar holds the Start menu, the pinned and running-window buttons, the quick-settings flyout, and the clock, which opens a calendar with a notification centre. The basics:

Keys Action
Super Open the Start menu
Super + Space Application launcher
Super + Enter Terminal (Foot)
Super + E Files (UFLinux Files)
Super + I Settings
Super + D Show the desktop
Print Screen Screenshot and recording tool

Installed applications include Foot, UFLinux Files, Loupe, htop, Firefox with uBlock Origin, Mako, Transmission, Celluloid, GNOME Disks and File Roller. UFLinux Files comes from the apps repository and is not published for every architecture. See Desktop overview for the full picture and Keyboard shortcuts for every binding.

The graphical installer opens automatically in the live desktop; you can also start Install UFLinux from the application menu.

Before you do, check your partitioning plan. UFLinux never partitions and never formats anything on your behalf in the “prepared” mode, and the guided mode erases a whole disk. The installed root must be XFS with a separate /boot.

Installation walks through both modes and the command-line installer.

Derived from README.md inUFlinux-project/uflinux3(b4f4817). Report documentation problems inUFlinux-project/docs.