1. Getting Started
Iron Linux is an installable Linux distribution built directly from Debian stable (trixie) using Debian's standard live-build engine. It features a curated, opinionated Wayland desktop powered by the Labwc compositor and Waybar panel.
- No Desktop Environment bloat: GNOME, KDE, and XFCE suites are absent.
- Pure Debian APT compatibility: Zero custom packages or divergent repos.
- Native Wayland layer-shell: Direct compositing without X11 baggage.
2. Hardware Requirements
Iron Linux is built to run reliably on modern high-end machines as well as older or resource-constrained hardware:
3. Flashing USB & Boot Media
The AMD64 ISO is built as an ISO-hybrid image. It can be burned to a DVD or written directly to a raw USB thumbdrive using dd or graphical flash utilities.
sudo dd if=iron-linux-amd64.iso of=/dev/sdX bs=4M status=progress conv=fsyncOn Windows or macOS, you can use Rufus (select DD image mode) or balenaEtcher.
4. Installation with Calamares
When booting the live media, you will reach the graphical login manager (greetd). Log in using username iron and password live.
- Click Install Iron Linux on the right side of Waybar, or press Super + I.
- Select your language, region, and keyboard layout.
- Choose your target disk. Select Erase disk or use Manual partitioning.
- Enter your new username and password.
- Confirm the summary and click Install.
- Reboot once installation finishes, detach the USB media, and boot into your new disk!
5. Desktop Basics & Keybindings
Iron Linux utilizes Labwc, a lightweight stacking compositor. All core shortcuts are configured in ~/.config/labwc/rc.xml:
| Shortcut | Action | Executing Binary |
|---|---|---|
| Super + Return | Open Terminal Emulator | foot |
| Super + Space / Super + D | Launch Application Runner | fuzzel |
| Super + E | Open File Manager | pcmanfm |
| Super + B | Open Web Browser | firefox-esr |
| Super + I | Launch Calamares Installer | iron-installer |
| Super + X | Power / Logout Menu | iron-power-menu (wlogout) |
| Super + L | Lock Session | iron-lock (swaylock) |
| Alt + F4 | Close Active Window | labwc (Close) |
| Alt + Tab | Switch Between Windows | labwc (NextWindow) |
| Print / Shift+Print | Screenshot (Full / Selection) | grim + slurp |
6. Package Management
Iron Linux uses upstream Debian repositories without intermediary proxies. You can install any software directly from Debian:
# Update Debian package index
sudo apt update
# Install software
sudo apt install git vlc build-essential
# Install downloaded deb packages (e.g. Google Chrome, VS Code)
sudo apt install ./google-chrome-stable_current_amd64.deb7. Raspberry Pi 4 Setup
For complete details on flashing, config.txt options, first-boot expansion, and serial debugging on the Raspberry Pi 4, visit our dedicated Raspberry Pi Guide.
8. Virtual Machines (QEMU / KVM)
Iron Linux is tested and validated inside QEMU/KVM. You can run the live image with KVM acceleration:
qemu-system-x86_64 \
-enable-kvm \
-cpu host \
-m 4096 \
-smp 2 \
-cdrom iron-linux-amd64.iso \
-boot d9. Troubleshooting & FAQ
iron, Password: live. Once logged in, you can run sudo without restrictions.wpctl and displays an on-screen overlay via wob. If you prefer a full graphical mixer, run sudo apt install pavucontrol.nmcli dev wifi connect "SSID" password "PASSWORD" in the Foot terminal.10. Building from Source
Iron Linux uses Debian live-build. The entire configuration is reproducible from a clean clone:
# Clone the source repository
git clone https://github.com/crossainthero-lab/IronLinux.git
cd IronLinux
# Bootstrap build host on Debian 13 / Ubuntu
sudo ./scripts/bootstrap-build-host.sh
# Run full ISO build
sudo ./build.sh