search

LukeShortCloud / winesapOS

winesapOS - Game with Linux anywhere, no installation required!
GNU General Public License v3.0
871 stars 31 forks source link
arch-linux archlinux gamescope gaming kde kde-plasma linux mac macos manjaro manjaro-linux plasma proton steam steam-deck steamos wine winesap winesapos

readme

winesapOS

Game with Linux anywhere, no installation required!

winesapOS desktop screenshot

winesapOS makes it easy to setup Linux and play games off an internal or portable external drive.

Why use winesapOS?

Release images can be downloaded here.

Project goals:

Want to help support our work? Consider helping out with open feature and bug GitHub issues. Our CONTRIBUTING.md guide provides all of the information you need to get started as a winesapOS contributor.

TABLE OF CONTENTS

macOS Limitations

These are reasons why macOS is inferior compared to Linux when it comes to gaming.

Features

General

Additional Hardware Support

Apple Intel Macs

All Intel Macs are supported. Linux works on most Macs out-of-the-box these days. Drivers are pre-installed for newer hardware where native Linux support is missing.

For installation onto an internal drive, winesapOS must be installed as a dual-boot alongside macOS. It will not work as the only installed operating system on an Intel Mac.

Hardware Supported Third-Party Driver(s)
Keyboard Yes linux-t2 patches
Touchpad Yes linux-t2 patches
NVMe Yes linux-t2 patches
Sound Yes linux-t2 patches and apple-t2-audio-config
Fans Yes mbpfan
Bluetooth Yes linux-t2 patches and apple-bcm-firmware
Wi-Fi Yes broadcom-wl and apple-bcm-firmware
Fingerprint scanner No
Touch Bar Yes linux-t2 patches

Notes about Bluetooth and Wi-Fi support if it is not working out-of-the-box:

ASUS Laptops

Hardware Supported Third-Party Driver(s)
Keyboard Yes asusctl
Touchpad Yes
NVMe Yes
Sound Yes linux-firmware-asus
Fans Yes asusctl
Bluetooth Yes
Wi-Fi Yes
Fingerprint scanner No

ASUS ROG Ally Handhelds

We provide support for both the original ASUS ROG Ally and the newer ASUS ROG Ally X.

Hardware Supported Third-Party Driver(s)
Controller Yes kernel-fysnc patches 1, 2, 3
NVMe Yes
Sound Yes kernel-fsync patches 1 and 2
Fans Yes
Bluetooth Yes
Wi-Fi Yes
Fingerprint scanner No

AYANEO Handhelds

Hardware Supported Third-Party Driver(s)
Controller Yes ayaneo-platform-dkms-git and ayaled-updated
NVMe Yes
Sound Yes aw87559-firmware
Fans Yes
Bluetooth Yes
Wi-Fi Yes
Fingerprint scanner No

Framework Computers

All Framework computers are fully supported.

Hardware Supported Notes
Keyboard Yes
Touchpad Yes Quirk added to disable when the keyboard is in-use
NVMe Yes Power saving mode enabled for deep sleep support
Sound Yes framework-dsp used for improved audio quality
Fans Yes
Bluetooth Yes
Wi-Fi Yes Region is automatically set to enable Wi-Fi >= 5
Fingerprint scanner Yes
LED matrix Yes inputmodule-control used for managing LED matrixes

For the Framework Laptop 16, audio support for Linux needs to be enabled in the BIOS.

Lenovo Legion Go

Hardware Supported Third-Party Driver(s)
Controller Yes udev rules
NVMe Yes
Sound Yes
Fans Yes
Bluetooth Yes kernel-fsync patches
Wi-Fi Yes
Fingerprint scanner No

Microsoft Surface Laptops

Hardware Supported Third-Party Driver(s)
Keyboard Yes linux-surface pathces
Touchpad Yes
NVMe Yes
Sound Yes linux-surface patches
Fans Yes linux-surface patches
Bluetooth Yes linux-surface patches
Wi-Fi Yes linux-surface patches
Fingerprint scanner No
Touchscreen Yes IPTSD, libwacom-surface, and linux-surface patches

OneXPlayer Handhelds

Hardware Supported Third-Party Driver(s)
Controller Yes
NVMe Yes
Sound Yes
Fans Yes oxp-sensors-dkms-git
Bluetooth Yes
Wi-Fi Yes
Fingerprint scanner No

Valve Steam Decks

Both the Steam Deck LCD and OLED models are fully supported.

Hardware Supported Third-Party Driver(s)
Controller Yes
Touchpad Yes
NVMe Yes
Sound Yes kernel-fsync patches and linux-firmware-valve
Fans Yes
Bluetooth Yes kernel-fsync patches and linux-firmware-valve
Wi-Fi Yes kernel-fsync patches and linux-firmware-valve
Touchscreen Yes

Community Collaboration

We are actively working alongside these operating system projects to help provide wider Linux gaming support to the masses:

winesapOS Repository

As of winesapOS 3.1.0, we now provide our own repository with some AUR packages pre-built. This repository works on Arch Linux and Manjaro. It is enabled on winesapOS by default. Depending on what distribution you are on, here is how it can be enabled:

Enable the GPG key to be used by importing it and then locally signing the key to trust it.

sudo pacman-key --recv-keys 1805E886BECCCEA99EDF55F081CA29E4A4B01239
sudo pacman-key --init
sudo pacman-key --lsign-key 1805E886BECCCEA99EDF55F081CA29E4A4B01239

Comparison with SteamOS

Features SteamOS 3 winesapOS 4
SteamOS repositories Yes No
Arch Linux packages Old New
Boot compatibility UEFI UEFI and legacy BIOS
Graphics drivers AMD AMD, Intel, NVIDIA, Parallels, VirtualBox, and VMware
Audio server PipeWire PipeWire
Read-only file system Yes No
Encrypted file system No Yes (secure image)
File system backup type A/B partitions Btrfs snapshots
Number of possible file system backups 1 Unlimited
Package managers (CLI) flatpak and nix pacman, yay, flatpak, snap, and nix
Preferred package manager (CLI) flatpak flatpak
Package managers (GUI) Discover (flatpak) Discover (flatpak), bauh (pacman, yay/AUR, flatpak, and snap), and AppImagePool (AppImage)
Update type Image-based Package manager
Number of installed packages Small Small (minimal image) or Large (performance and secure images)
Game launchers Steam Steam, Heroic Games Launcher, Lutris, Open Gamepad UI, and Prism Launcher
Linux kernels Neptune (6.5) Linux LTS (6.6) and Linux Nobara (Latest)
Additional ASUS laptop drivers No Yes
Additional Framework Computer drivers No Yes
Additional Intel Mac drivers No Yes
Additional Microsoft Surface drivers No Yes
Desktop environment KDE Plasma 5 KDE Plasma 6
Desktop theme Vapor Breeze
AMD FSR Global Global
Gamescope Global Global
Wine Proton Proton and GE-Proton
Game controller support Large Large
exFAT cross-platform storage No Yes (16 GiB on the performance and secure images)

winesapOS 3 was the first Linux distribution to be based on SteamOS 3. Historically, here are the first forks of SteamOS 3:

Distro First Preview First Public Release
winesapOS 2022-03-06 2022-03-10
SteamOS for PS4 2022-03-09 2022-03-25
HoloISO 2022-04-21 2022-05-01

Usage

Getting Started

Hardware Requirements

Minimum:

Recommended:

Important note about external storage!

One of the founding goals of winesapOS was for it to be portable. However, most flash drives and SD/TF cards are too slow to run an operating system on and provide a good experience. For the best experience, use one of these recommended flash drives, an external USB-C >= 3.1 SSD, or a USB-C >= 3.2 docking station or hub that includes a M.2 NVMe drive slot.

Image Types

winesapOS provides 3 different image types to meet the diverse needs of our users:

Feature Minimal Performance Secure
CPU Mitigations No No Yes
Encryption No No Yes (LUKS)
Firewall No No Yes (Firewalld)
root Password Requires Reset No No Yes
16 GiB exFAT Cross-Platform Storage No Yes Yes

The minimal root file system archive (winesapos-${WINESAPOS_VERSION}-minimal-rootfs.tar.zst) is the extracted files from the minimal image. It can be used for containers or installing winesapOS in a Docker or Podman container, dual-boot, or WSL 2 scenario.

Secure Image

If using the secure image, the default LUKS encryption key is password which should be changed after the first boot. Do not do this before the first boot as the default password is used to unlock the partition for it be resized to fill up the entire storage device. Change the LUKS encryption key for the fifth partition.

$ sudo cryptsetup luksChangeKey /dev/<DEVICE>5

The user account password for winesap and root are the same as the username. The root user are set to expire immediately. Upon first login, you will be prompted to enter a new password. Here is how to change it:

  1. Enter the default password of winesap.
  2. The prompt will say "Changing password for winesap." Enter the default password of winesap again.
  3. The prompt will now say "New password". Enter a new password.
  4. The prompt will finally say "Retype new password". Enter the new password again. The password has been updated and the KDE Plasma desktop will now load.

The root user account is locked until the password is changed. It is recommended to change this immediately to allow for recovery to work.

$ sudo passwd root

Release Builds

  1. Refer to the Mac Boot and Windows Boot guides to avoid common issues.
  2. Download the latest release from here.
    • External drive
      • Download one the of the release images and then continue on with this guide.
        • Performance (recommended) = Requires 31 GiB of free space to download and extract.
        • Minimal (for users low on storage space or who want control over what is installed) = Requires 13 GiB of free space to download and extract.
        • Secure (for advanced users only) = Requires 32 GiB of free space to download and extract.
    • Internal drive
      • Entire drive (PCs only, does not work on Macs)
        • Use winesapOS to install winesapOS. Start with the minimal image and follow through the next steps (2 and 3) to extract and flash the image to an external drive. Then boot into the storage device and download the image you want to setup. Follow steps 2 and 3 again to flash the image onto an internal storage device.
          • For balenaEtcher, when you "Select target" there is an option to "Show hidden" storage devices. It will let you flash an image to any drive except the one it is physically running on.
      • Dual-boot (PCs and Intel Macs)
    • If you want even more control over the how the image is built, consider doing a custom build instead.
  3. Extract the winesapos-<VERSION>-<TYPE>.img.zip archive.

  4. Use the image...

    1. on a PC or Mac.

      • Flash the image to an internal or external storage device. WARNING: This will delete any existing data on that storage device.
        • On Linux, macOS, and Windows, use either balenaEtcher or USBImager to flash the image.
        • On Linux and macOS, the dd CLI utility can be used to flash the image.

    2. with GNOME Boxes on Linux.

      • Resize the winesapOS image to at least 32 GiB. 
        $ qemu-img resize winesapos*.img +24G
      • GNOME Boxes > + > Install from File > (select the winesapOS image file) > Open > Operating System: Arch Linux, Memory: 4.0 GiB > Create

    3. with Parallels Desktop on macOS (Intel only).

      • Convert the raw image to the VDI format. Then convert the VDI image to HDD.
        • Using the qemu-img and prl_convert CLI: 
          qemu-img convert -f raw -O vdi winesapos-<VERSION>-<TYPE>.img winesapos-<VERSION>-<TYPE>.vdi
prl_convert winesapos-<VERSION>-<TYPE>.vdi --allow-no-os --stand-alone-disk --dst=winesapos-<VERSION>-<TYPE>.hdd
      • Parallels Desktop > Install Windows or another OS from a DVD or image file > Image File > select a file... > (select the winesapOS HDD file) > Continue > Please select your operating system: > More Linux > Other Linux > OK > Name: winesapOS > Create

    4. with Virtual Machine Manager on Linux.

      • Resize the winesapOS image to at least 32 GiB. 
        $ qemu-img resize winesapos*.img +24G
      • Move the winesapOS image to /var/lib/libvirt/images/.
      • Virtual Machine Manager > File > New Virtual Machine > Import existing disk image > Forward > Browse local > (select the winesapOS image) > Open > Choose the operating system you are installing: Arch Linux (archlinux) > Forward > (if asked to fix permissions, select "Yes"), Memory: 4096, CPUs: 2 > Forward > Name: winesapOS, Customize configuration before install: yes > Finish > Overview > Firmware: "UEFI x86_64: /usr/share/edk2-ovmf/x64/OVMF_CODE.fd" > Apply > Begin Installation

    5. with VirtualBox.

      • Convert the raw image to the VDI format.
        • Using the VirtualBox CLI: 
          VBoxManage convertfromraw --format VDI winesapos-<VERSION>-<TYPE>.img winesapos-<VERSION>-<TYPE>.vdi
        • Using the qemu-img CLI: 
          qemu-img convert -f raw -O vdi winesapos-<VERSION>-<TYPE>.img winesapos-<VERSION>-<TYPE>.vdi
        • Using StarWind V2V Converter on Windows.
      • Virtual Box > New > Name: winesapOS, Type: Linux, Version: Arch Linux (64-bit) > Next > Base Memory: 4096 MB, Processors: 2, Enable EFI: Yes > Next > Use an Existing Virtual Hard Disk File > Add > Choose > Next > Finish > File > Tools > Virtual Media Manager > Size: (increase to at least 32 GB) > Apply > OK > winesapOS > Settings > General > Advanced > Shared Clipboard: Bidirectional, Drag'n'Drop: Bidirectional > OK > winesapOS > Settings > Display > Screen > Video Memory: 128 MB, Graphics Controller: VMSVGA, Extended Features: Enable 3D Acceleration
      • NOTICE: VirtualBox 3D acceleration for Linux guests does not fully work. This issue is not specific to winesapOS. Consider using VMware Fusion or VMware Workstation instead.

    6. with VMware Fusion on macOS (Intel only).

      • Convert the raw image to the VMDK format.
        • Using the VirtualBox CLI: 
          VBoxManage convertfromraw --format VMDK winesapos-<VERSION>-<TYPE>.img winesapos-<VERSION>-<TYPE>.vmdk
        • Using the qemu-img CLI: 
          qemu-img convert -f raw -O vmdk winesapos-<VERSION>-<TYPE>.img winesapos-<VERSION>-<TYPE>.vmdk
        • Using StarWind V2V Converter on Windows.
      • VMware Fusion > Virtual Machine Library > + > New... > Create a custom virtual machine > Continue > Linux > Other Linux 5.x kernel 64-bit > Continue > Specify the boot firmware: UEFI > Continue > Use an existing virtual disk > Continue > Custom Settings > Hard Disk (SCSI) > Disk size: (increase to at least 64 GB) > Apply > Show All > Processors & Memory > Processors: 2 processor cores > Memory: 4096 MB > Show All > Display > Accelerate 3D Graphis: Yes > Shared graphics memory: (set this to the highest possible value)

    7. with VMware Workstation on Linux or Windows.

      • Convert the raw image to the VMDK format.
      • VMware Workstation > Create a New Virtual Machine > Custom (advanced) > Next > Hardware compatibility: (select the latest version) > Next > I will install the operating system later. > Next > Guest Operating System: 2. Linux > Version: Other Linux 5.x kernel 64-bit > Next > Name: winesapOS > Next > Number of processors: 2 > Next > Memory for this virtual machine: 4096 MB > Next > Use network address translation (NAT) > Next > SCSI controller: LSI Logic (Recommended) > Next > Virtual Disk Type: SCSI (Recommended) > Next > Use an existing virtual disk > Next > File name: (select the winesapOS VMDK file) > Keep Existing Format > Customize Hardware... > Hard Disk (SCSI) > Expand Disk... > Maximum disk size (GB): (increase to at least 64 GB) > Expand > OK > Display > Accelerate 3D graphics: Yes > Graphics Memory: (set this to the highest possible value) > Close > Finish > Close

Default accounts have a password set that mirror the username:

Username Password
winesap winesap
root root

Upon first login, the "winesapOS First-Time Setup" wizard will launch. It will help set up graphics drivers, the locale, time zone, and more. It is highly recommended to complete this on the first boot. Then reboot before using winesapOS to provide the best experience.

Custom Builds

Instead of using a release build which is already made, advanced users may want to create a custom build. This only requires 1 GiB of free space to download the live Arch Linux environment. It also allows using environment variables to configure the build differently than the default release builds.

  1. Download and setup the latest Arch Linux ISO onto a flash drive that has at least 1 GB of storage.

    1a. We also support building winesapOS with Manjaro even though we do not provide release images for it. Download either the Plasma, Cinnamon, or GNOME desktop edition of Manjaro.

  2. Boot into the flash drive.

  3. Update the known packages cache and install git.

    pacman -S -y
pacman -S git

  4. Clone the stable branch and go to the "scripts" directory.

    git clone --branch stable https://github.com/lukeshortcloud/winesapos.git
cd ./winesapos/scripts/

  5. Configure environment variables to customize the build. At the very least, allow the build to work on bare-metal and define what /dev/<DEVICE> block device to install to. BE CAREFUL AS THIS WILL DELETE ALL EXISTING DATA ON THAT DEVICE!

    export WINESAPOS_BUILD_IN_VM_ONLY=false
lsblk
export WINESAPOS_DEVICE=<DEVICE>

  6. Run the build.

    sudo -E bash ./winesapos-install.sh

  7. Check for any test failures (there should be no output from this command).

    grep -P 'FAIL$' /winesapos/etc/winesapos/winesapos-install.log

For more detailed information on the build process, we recommend reading the entire CONTRIBUTING.md guide.

Docker or Podman Container

Configure the winesapOS version to download and the container engine to use.

export WINESAPOS_VERSION="4.1.0"
#export WINESAPOS_CONTAINER_ENGINE="docker"
export WINESAPOS_CONTAINER_ENGINE="podman"

Download, decompress, and then import the root file system. Most container engines only support Gzip compression (not Zstandard).

wget https://winesapos.lukeshort.cloud/repo/iso/winesapos-${WINESAPOS_VERSION}/winesapos-${WINESAPOS_VERSION}-minimal-rootfs.tar.zst
zstd --decompress winesapos-${WINESAPOS_VERSION}-minimal-rootfs.tar.zst
${WINESAPOS_CONTAINER_ENGINE} import winesapos-${WINESAPOS_VERSION}-minimal-rootfs.tar winesapos:${WINESAPOS_VERSION}

Verify that the container image was imported.

${WINESAPOS_CONTAINER_ENGINE} images | grep winesapos
# Example output: winesapos                        4.1.0     23b9bb5f1c26   26 seconds ago   8.79GB

Windows Subsystem for Linux

As of winesapOS 4.1.0, it is supported to be ran as a virtual machine on Windows >= 10 using WSL 2.

Passwords

Username Password
root root
winesap winesap

On the secure image, the LUKS encryption key is password. The password for LUKS and the root account should be changed immediately.

$ sudo cryptsetup luksChangeKey /dev/<DEVICE>5
$ sudo passwd root

Mac Boot

Boot the Mac into an external drive by pressing and releasing the power button. Then hold down the OPTION key (or the ALT key on a Windows keyboard) to access the Mac bootloader. Select the "EFI Boot" device.

IMPORTANT Any Mac with an Apple T2 Security Chip, which are all Macs made in and after 2018, needs to allow booting from external storage:

  1. Turn on the Mac and immediately hold both the COMMAND and r keys to enter recovery mode.
  2. Utilities > Startup Security Utility
    • Secure Boot = No Security (Does not enforce any requirements on the bootable OS.)
    • External Boot = Allow booting from external media (Does not restrict the ability to boot from any devices.)

Windows Boot

  1. Secure Boot is not supported.
    • If using Windows and BitLocker is enabled then disable it first.
    • Then disable Secure Boot in the BIOS.
  2. Disable fast startup as this causes issues with booting Linux.
    • Long-term solution:
      • Control Panel > Hardware and Sound > Power Options > Change what the power buttons do > Change settings that are currently unavailable > (uncheck "Turn on fast startup (recommended)") > Save changes
    • Short-term solution:
      • Fully shutdown Windows by holding the "SHIFT" key while selecting "Shut down", selecting to "Reboot", or by running the command shutdown /s /f /t 0.
    • Do not Hibernate in Windows.
  3. Configure Windows to use UTC for the hardware clock.

Ventoy

winesapOS release images are in a raw format which does not work out-of-the-box with Ventoy. These can be modified to work with Ventoy by using the Linux vDisk boot plugin.

  1. Create a virtual machine for winesapOS. View the getting started guide for instructions on how to use VirtualBox, VMware Fusion, or VMware Player/Workstation.
  2. Download the latest vtoyboot ISO and attach it to the virtual machine.
  3. Mount the ISO in the virtual machine and then run the vtoyboot.sh command. This will convert the operating system to be useable via Ventoy.
  4. Shutdown the virtual machine and then rename the virtual machine image to winesapos.vtoy.

The image can now be used by Ventoy.

Dual-Boot

It is recommended to follow the getting started guide to install winesapOS onto its own internal drive if also using Linux or Windows. Then use the motherboard BIOS to change the boot device. For macOS, the only way to install it to the internal drive is via dual-boot.

However, it is possible to install winesapOS onto the same drive as Linux or Windows. That is what this guide will cover in more detail.

Only UEFI is supported for dual-boot installations of winesapOS. For legacy BIOS boot, create and flash a normal portable release image such as the minimal, performance, or secure. Those all support both legacy BIOS boot and UEFI.

Install (if necessary) macOS or Windows first. Then proceed with installing winesapOS onto the same drive.

macOS Dual-Boot Preparation Guide

Only Intel Macs are supported.

  1. As of Mac OS X 10.11 El Capitan, System Integrity Protection (SIP) was added for additional boot security. It needs to be disabled for rEFInd support.
    • Enter macOS Recovery mode.
      • Shutdown the Mac.
      • Press the power button. Then hold the command and r keys until the Apple logo appears. Then let go of those two keys.
    • Utilities > Terminal
    • Run the command csrutil disable to disable SIP.
  2. Follow the Mac Boot guide.
    • Reboot when done.
      • (Select the Apple logo in the top-left) > Restart
  3. Install rEFInd. This is an alternative UEFI boot manager that has better compatibility with Linux.
    • Download and extract refind-bin-<VERSION>.zip.
    • Open the Terminal app, navigate to the extracted folder, and then run ./refind-install.
  4. SIP can optionally be re-enabled now that rEFInd is installed.
  5. Create free storage space for winesapOS.
    • Disk Utility > (select the primary drive) > Partition > + > Add Partition > Name: winesapOS, Format: ExFAT, Size: (enter the amount of space to use for winesapOS) > Apply > Partition > Continue > Done
Windows Dual-Boot Preparation Guide
  1. Follow the Windows Boot guide.
  2. Create free storage space for winesapOS.
    • Disk Management (diskmgmt.msc) > (right-click on the "(C:)" partition) > Shrink Volume... > Enter the amount of space to shrink in MB: (enter the amount of space to use for winesapOS) > Shrink
winesapOS Dual-Boot Install Guide

Semi-automated steps:

  1. Follow the winesapOS getting started guide to get the minimal image onto an external drive.
  2. Boot into winesapOS that is on the external drive.
  3. Use GParted to partition the free storage space. The labels are suffixed with the number zero "0" (not the letter "O").
    • For macOS:
      • (Right-click on the "exfat" partition) > Delete
      • (Right-click on the "unallocated" space) > New > New size (MiB): 1000, File system: fat32, Label: WOS-EFI0 > Add
    • Then for macOS and Windows:
      • (Right-click on the "unallocated" space) > New > New size (MiB): 1000, File system: ext4, Label: winesapos-boot0 > Add
      • (Right-click on the "unallocated" space) > New > File system: btrfs, Label: winesapos-root0 > Add
    • (Select the green check mark to "Apply All Operations") > Apply > Close
  4. Run the "winesapOS Dual-Boot Installer (Beta)" desktop shortcut.
  5. Turn off the computer, unplug the winesapOS external drive, and then turn on the computer.

  6. Allow booting the original operating system again.

    • macOS
      • Hold command while booting up. Once booted into macOS, run ./refind-mkdefault (requires Xcode to be installed).
    • Windows
      • Add Windows to the GRUB boot menu. 
        # Enable os-prober. It is disabled by default.
sudo crudini --ini-options=nospace --set /etc/default/grub "" GRUB_DISABLE_OS_PROBER false
sudo grub-mkconfig -o /boot/grub/grub.cfg

Manual steps:

  1. Follow the winesapOS getting started guide to get the minimal image onto an external drive.
    • This includes installer tools needed to install winesapOS onto an internal drive.
    • It also includes an exFAT partition that is accessible from any operating system.
  2. Download the latest winesapos-${WINESAPOS_VERSION}-minimal-rootfs.tar.zst release.
    • Copy it to the wos-drive.
  3. Boot into winesapOS that is on the external drive.
  4. Use GParted to partition the free storage space. The labels are suffixed with the number zero "0" (not the letter "O").
    • For macOS:
      • (Right-click on the "exfat" partition) > Delete
      • (Right-click on the "unallocated" space) > New > New size (MiB): 1000, File system: fat32, Label: WOS-EFI0 > Add
    • Then for macOS and Windows:
      • (Right-click on the "unallocated" space) > New > New size (MiB): 1000, File system: ext4, Label: winesapos-boot0 > Add
      • (Right-click on the "unallocated" space) > New > File system: btrfs, Label: winesapos-root0 > Add
    • (Select the green check mark to "Apply All Operations") > Apply > Close
  5. Mount the new partitions with winesapOS optimizaitons and features. 
    # View hints about each partition.
$ lsblk
$ sudo mount -t btrfs -o subvol=/,compress-force=zstd:1,discard,noatime,nodiratime -L winesapos-root0 /mnt
$ sudo btrfs subvolume create /mnt/.snapshots
$ sudo btrfs subvolume create /mnt/home
$ sudo mount -t btrfs -o subvol=/home,compress-force=zstd:1,discard,noatime,nodiratime -L winesapos-root0 /mnt/home
$ sudo btrfs subvolume create /mnt/home/.snapshots
$ sudo btrfs subvolume create /mnt/swap
$ sudo mount -t btrfs -o subvol=/swap,compress-force=zstd:1,discard,noatime,nodiratime -L winesapos-root0 /mnt/swap
$ sudo mkdir /mnt/boot
$ sudo mount --label winesapos-boot0 /mnt/boot
$ sudo mkdir /mnt/boot/efi
# Mount the FAT32 EFI partition.
# On macOS, use the newly created EFI partition.
# On Windows, use the existing EFI partition. This is usually the first partition and 100 MiB in size.
$ sudo mount /dev/<DEVICE>1 /mnt/boot/efi
  6. Extract the winesapOS root file system archive.
    • Select the "wos-drive" drive in the Dolphin file manager to automatically mount it.
    • Extract the archive. 
      $ sudo tar --extract --keep-old-files --verbose --file /run/media/winesap/wos-drive/winesapos-${WINESAPOS_VERSION}-minimal-rootfs.tar.zst --directory /mnt/
  7. Configure the bootloader. 
    $ grep -v -P "winesapos|WOS" /mnt/etc/fstab | sudo tee /mnt/etc/fstab
$ genfstab -L /mnt | sudo tee -a /mnt/etc/fstab
$ sudo mount --rbind /dev /mnt/dev
$ sudo mount --rbind /sys /mnt/sys
$ sudo mount -t proc /proc /mnt/proc
$ sudo chroot /mnt grub-install --target=x86_64-efi --efi-directory=/boot/efi --bootloader-id=winesapOS
$ sudo chroot /mnt grub-mkconfig -o /boot/grub/grub.cfg
$ sudo chroot /mnt mkinitcpio -P
$ sudo sync
  8. Turn off the computer, unplug the winesapOS external drive, and then turn on the computer.

  9. Allow booting the original operating system again.

    • macOS
      • Hold command while booting up. Once booted into macOS, run ./refind-mkdefault (requires Xcode to be installed).
    • Windows
      • Add Windows to the GRUB boot menu. 
        # Enable os-prober. It is disabled by default.
$ sudo crudini --ini-options=nospace --set /etc/default/grub "" GRUB_DISABLE_OS_PROBER false
$ sudo grub-mkconfig -o /boot/grub/grub.cfg

First-Time Setup

After logging in for the first time as the winesap user, the first-time setup for winesapOS will appear. Users have the option to manually select their choices or go with the recommended defaults below.

Setup Recomended Default
Broadcom proprietary Wi-Fi driver Automatic
Rotate screen No
Older version of winesapOS Stop and prompt user
Select your desired mirror region Automatic (GeoIP)
Graphics driver Mesa
Swap method zram
Locale en_US.UTF-8 UTF-8
Time zone Automatic (GeoIP)
Nix package manager Yes
Recommended producitvity apps Yes
Recommended gaming apps Yes
Waydroid Yes
GE-Proton Yes
Xbox controllers drivers Yes
Enable ZeroTier Yes
Change user password Yes
Change root password Yes
Enable autologin Yes (minimal and performance) and No (secure)
Hide GRUB boot menu Yes
Upgrade firmware Yes

Upgrades

Minor Upgrades

Upgrades are supported and recommended between all minor releases of winesapOS. For example, it is supported to go from 3.0.0 to 3.2.1.

Where it makes sense, features are backported from newer versions of winesapOS. Bug and security fixes are also included to fix problems either with winesapOS itself or with upstream changes in Arch Linux. Even if a user never upgrades winesapOS, users will continue to get regular system upgrades from Arch Linux.

Before upgrading, please read the full UPGRADE.md notes. This showcases what updates will happen automatically and what updates may need to be manually applied.

Development builds do not support upgrades. Here are the releases that we do support upgrades on:

Release Upgrades Supported
Stable Yes
Release Candidate (RC) Yes
Beta No
Alpha No

Here is how to upgrade winesapOS:

Major Upgrades

Uninstall

If desired, it is possible to remove winesapOS specific files and configuration and switch back to upstream Arch Linux using an uninstall script. It will not remove anything that is related to improved hardware compatibility.

curl https://raw.githubusercontent.com/LukeShortCloud/winesapOS/stable/scripts/winesapos-uninstall.sh | sudo -E bash

Convert to winesapOS

It is possible to get an experience similar to winesapOS but on a different Linux distribution by installing applications that winesapOS provides.

What this conversion script does:

What it does NOT do:

Run this script to convert to winesapOS:

curl https://raw.githubusercontent.com/LukeShortCloud/winesapOS/stable/scripts/winesapos-convert.sh | bash

Tips

Getting Started

Steam Deck Game Mode

On the SDDM login screen for the "winesap" user, the "Session" drop-down menu in the top-left can be used to change the session from "Plasma (Wayland)" to "Steam Big Picture (Wayland)". This provides the same experience as having a Steam Deck in "Game Mode" by launching Steam with Gamescope Session. Using this on devices that are not the Steam Deck will have varied results. For example, configuring TDP for other devices will not work as the Steam client is hardcoded to only work on the Steam Deck.

Known issues:

Alternatively, Steam can be launched from KDE Plasma using the "Steam (Runtime)" desktop shortcut. Then it can be changed to be in the new Big Picture Mode.

There is also a session for Open Gamepad UI as an open source alternative front-end. Select the "OpenGamepadUI (Wayland)" session on the SDDM login screen. It has plugins for Steam, Lutris, and more.

No Sound (Muted Audio)

When Mac hardware is detected, all sound is muted on boot because on, newer Macs, the experimental sound driver is extremely loud. This means that any volume changes will be reset on the next boot. Disable and stop the user (not system) mute service to allow the sound volume to be saved:

systemctl --user disable --now winesapos-mute.service

Btrfs Backups

Snapper creates 6 monthly snapshots of the /home directory. snap-pac creates a snapshot of the root / directory before and after using pacman. Both the root and home configurations are set to only use a maximum of 50 GiB each.

During boot, GRUB will have a "winesapOS snapshots" section that will allow booting from a root directory snapshot. This will not appear on first boot because no backups have been taken yet. After a backup has been taken, the GRUB configuration file needs to be regenerated to scan for the new backups.

Manually rebuild the GRUB configuration file to load the latest snapshots:

$ sudo grub-mkconfig -o /boot/grub/grub.cfg

View the available backups:

$ sudo snapper -c root list
$ sudo snapper -c home list

Manually create a new backup:

$ sudo snapper -c <CONFIG> create

Manually delete a backup:

$ sudo snapper -c <CONFIG> delete <BACKUP_NUMBER>

VPN (ZeroTier)

A VPN is required for LAN gaming online. Use the free and open source ZeroTier VPN service for this.

Host

  1. Only one person needs to create a ZeroTier account.
  2. They must then create a ZeroTier network.
    1. Log into ZeroTier Central.
    2. Select "Networks".
    3. Select "Create A Network".
    4. Select the "Network ID" or "Name" of the new network to modify the settings.
      • Either (1) set the "Access Control" to "Public" or (2) use this settings page to manually authorize connected clients to be able to communicate on the network.
      • Take note of the "Network ID". Send this string to your friends who will connect to the VPN.

Clients

  1. Start the ZeroTier VPN service.

    $ sudo systemctl enable --now zerotier-one

  2. Connect to the ZeroTier network.

    $ sudo zerotier-cli join <NETWORK_ID>

Troubleshooting

Release Image Zip Files

Challenge: the release image fails to be extracted from the zip file.

Solutions:

  1. Verify the integrity of the downloaded zip files.

    • Linux:

      sha512sum --check winesapos-<VERSION>-<TYPE>.sha512sum.txt

    • Windows (open Command Prompt as Administrator):

      C:\Windows\system32>CertUtil.exe -hashfile C:\Users\<USER>\Downloads\winesapos-<VERSION>-<TYPE>.sha512sum.txt SHA512

  2. Not enough free space. Ensure you have 13 GiB (minimal image), 31 GiB (performance image), or 33 GiB (secure image) of free space before downloading the zip files.

  3. If using PeaZip, it sometimes fails to extract to the current directory. Try extracting to a different directory.

winesapOS Not Booting

There are many different reasons why winesapOS may not be booting.

Root File System Resizing

Challenge: the root file system does not resize itself to use all available space on the storage device.

Solution:

  1. Re-enable the resize service, reboot, and then view the service log. Open up a GitHub Issue with the full log output.

    sudo systemctl enable winesapos-resize-root-file-system
sudo reboot
    sudo journalctl --unit winesapos-resize-root-file-system

Read-Only File System

If using an external USB drive, it is possible to get errors about a Read-only file system. This is a hardware issue and indicates that the USB drive has been disconnected even if only for a fraction of a second. Short-term, reboot winesapOS to fix these errors. Long-term, try using a different USB port and/or drive and make sure that the drive does not move while in use. For the best experience, we recommend using an internal drive.

Wi-Fi or Bluetooth Not Working

Challenge: If Wi-Fi or Bluetooth is not working and Windows is installed, it could be from fast startup being enabled and/or Windows Hibernating.

Solutions:

Available Storage Space is Incorrect

Challenge: the amount of reported free space seems too small or large.

Solutions:

  1. Btrfs is used as the root file system on winesapOS. The most reliable way to view the amount of storage in-use on Btrfs is with this command.

    sudo btrfs filesystem df /

  2. Snapper is used to take Btrfs snapshots (1) every time Pacman installs, upgrades, or removes a package and (2) every month. Refer to the Btrfs Backups section for more information on how to manage those snapshots.

First-Time Setup Log Files

If the first-time setup fails or needs debugging, the last log file can be found and copied to the desktop by running these two commands:

$ sudo cp "/etc/winesapos/$(sudo ls -1 /etc/winesapos/ | grep setup | tail -n 1)" /home/winesap/Desktop/
$ sudo chown winesap:winesap "/home/winesap/Desktop/$(ls -1 ~/Desktop/ | grep setup_)"

Two or More Set Ups of winesapOS Cause an Unbootable System

Challenge: winesapOS uses labels for file system mounts which confuses the system if more than one label is found.

Solution:

  1. Change the file system label of at least the root file system on one of the winesapOS drives. It is recommended to change all of the labels on that same drive. This can cause an unbootable system. Manually review the contents of /etc/fstab to ensure it is correct.

    # Labels can be changed on mounted file systems.
lsblk -o name,label
export DEVICE=vda
sudo -E exfatlabel /dev/${DEVICE}2 wos-drive0
sudo -E fatlabel /dev/${DEVICE}3 WOS-EFI0
sudo sed -i s'/LABEL=WOS-EFI/LABEL=WOS-EFI0/'g /etc/fstab
sudo -E e2label /dev/${DEVICE}4 winesapos-boot0
sudo sed -i s'/LABEL=winesapos-boot/LABEL=winesapos-boot0/'g /etc/fstab
sudo btrfs filesystem label / winesapos-root0
sudo btrfs filesystem show /
sudo sed -i s'/LABEL=winesapos-root/LABEL=winesapos-root0/'g /etc/fstab
lsblk -o name,label
    # GRUB needs to be updated with the new /etc/fstab information.
sudo chroot <MOUNTED_ROOT_AND_BOOT_DIRECTORY> grub-mkconfig -o /boot/grub/grub.cfg

Snapshot Recovery

Challenges:

  1. winesapOS upgrade fails.
  2. Old files need to be recovered.

Solution:

  1. At the GRUB boot menu select "Arch Linux snapshots" and then the desired backup to load. The filesystem will be read-only by default. It can be set to enable writes with this command:

    $ sudo btrfs property set -ts /.snapshots/<BTRFS_SNAPSHOT_ID> ro false

For more advanced recovery using overlayfs on-top of a read-only filesystem, refer to this grub-btrfs GitHub issue.

Reinstalling winesapOS

Reinstalling winesapOS on-top of an existing winesapOS installation of the same exact version and image type can cause issues. This is because the partitions are perfectly aligned which leads to overlapping data. Even wiping the partition table is not enough. For the best results, it is recommended to completely wipe at least the first 25 GiB of the storage device. WARNING: This will delete any existing data on that storage device.

dd if=/dev/zero of=/dev/<DEVICE> bs=1M count=25000

Bad Performance on Battery

When using a portable device such as a laptop or gaming handheld, the operating system goes into a battery saver mode by default. This can be disabled to get maximum performance.

sudo systemctl disable --now auto-cpufreq

Frequently Asked Questions (FAQ)

Contributors

Here are community contributors who have helped the winesapOS project.

Founder:

Code:

Financial:

User Surveys

These are anonymous surveys done with Linux gaming community members. Most, but not all, are winesapOS users.

Favorite (non-Valve) handheld PC brand:

6 votes.

There were no comments about what the "Other" brand is so that is unknown.

https://twitter.com/LukeShortCloud/status/1649078025634598912

Favorite desktop environments:

25 votes.

"Other" included specific mentions from the community about Cinnamon (for its similarity to Windows) and Sway (for its tiling features).

https://twitter.com/LukeShortCloud/status/1659279345926516737

History

Release Version/Tag Project Name Operating System Desktop Environment Release Images
4.1.0 winesapOS Arch Linux KDE Plasma Performance, Secure, Minimal, and Minimal Root File System
4.0.0 winesapOS Arch Linux KDE Plasma Performance, Secure, and Minimal
3.2.0 winesapOS SteamOS 3 KDE Plasma Performance, Secure, and Minimal
3.0.0 winesapOS SteamOS 3 KDE Plasma Performance and Secure
2.2.0 Mac Linux Gaming Stick Manjaro Cinnamon Performance and Secure
2.0.0 Mac Linux Gaming Stick Manjaro Cinnamon Performance
1.0.0 Mac Linux Gaming Stick Ubuntu 20.04 Cinnamon None

License

GPLv3