KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #ai-agents #developer-tools #typescript #codex #claude-code #mcp #rust #deepseek-harness #ai-agent #cli

winesapOS

★ 1,056 Open GitHub ↗

winesapOS - Game with Linux anywhere, no installation required!

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# winesapOS <img src="https://user-images.githubusercontent.com/10150374/158224898-bdb4ad3a-ad09-478c-a09d-d313feeb8713.png" width=15% height=15%>

***Game with Linux anywhere, no installation required!***

> [!IMPORTANT]
> Downloads for winesapOS can be found on [our GitHub Releases page](https://github.com/winesapOS/winesapOS/releases).

Minimal image type:

![winesapOS minimal image type desktop screenshot](https://raw.githubusercontent.com/winesapOS/winesapOS/main/winesapos-desktop-minimal.jpg)

Minimal and performance image types with first-time setup recommended defaults installed:

![winesapOS minimal image type set up desktop screenshot](https://raw.githubusercontent.com/winesapOS/winesapOS/main/winesapos-desktop-minimal-setup.jpg)

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

Why use winesapOS?

- Portable. Useful for gaming or recovery purposes while traveling.
- Enhanced hardware support for Apple Macs with Intel processors, ASUS ROG Ally handhelds, AYANEO handhelds, Framework Computer, Microsoft Surface laptops, and Valve Steam Deck handhelds.
- Upgrades are fully automated and supported for minor and major versions.
- All of the features of winesapOS are listed [here](#features).

Project goals:

- **Readability.** Anyone can learn how to install and maintain Arch Linux.
- **Upstream.** Stay as vanilla and upstream as possible.
- **Portability.** Be the most portable and modern x86_64 operating system.

Want to help support our work? Report any bugs or feature requests to our [GitHub Issues](https://github.com/winesapOS/winesapOS/issues). For developers, our [CONTRIBUTING.md](CONTRIBUTING.md) guide provides all of the information you need to get started as a winesapOS contributor. If you are a Go developer, we need the most help with the [archupgrade-go](https://github.com/winesapOS/archupgrade-go) project.

**TABLE OF CONTENTS**

* [winesapOS](#winesapos)
   * [Features](#features)
       * [General](#general)
       * [Additional Hardware Support](#additional-hardware-support)
           * [Apple Intel Macs](#apple-intel-macs)
           * [ASUS Laptops](#asus-laptops)
           * [ASUS ROG Ally Handhelds](#asus-rog-ally-handhelds)
           * [AYANEO Handhelds](#ayaneo-handhelds)
           * [Framework Computer](#framework-computer)
           * [Lenovo Legion Go](#lenovo-legion-go)
           * [Microsoft Surface Laptops](#microsoft-surface-laptops)
           * [MSI Claw Handhelds](#msi-claw-handhelds)
           * [OneXPlayer Handhelds](#onexplayer-handhelds)
           * [Valve Steam Decks](#valve-steam-decks)
       * [Community Collaboration](#community-collaboration)
       * [winesapOS Repository](#winesapos-repository)
       * [Comparison with SteamOS](#comparison-with-steamos)
   * [Usage](#usage)
      * [Getting Started](#getting-started)
          * [Hardware Requirements](#hardware-requirements)
          * [Image Types](#image-types)
              * [Secure Image](#secure-image)
          * [Release Builds](#release-builds)
          * [Custom Builds](#custom-builds)
          * [Docker or Podman Container](#docker-or-podman-container)
          * [Windows Subsystem for Linux](#windows-subsystem-for-linux)
          * [Passwords](#passwords)
          * [Mac Boot](#mac-boot)
          * [Windows Boot](#windows-boot)
          * [Ventoy](#ventoy)
          * [Installer](#installer)
              * [macOS Dual-Boot Preparation Guide](#macos-dual-boot-preparation-guide)
              * [SteamOS Dual-Boot Preparation Guide](#steamos-dual-boot-preparation-guide)
              * [Windows Dual-Boot Preparation Guide](#windows-dual-boot-preparation-guide)
              * [winesapOS Install Guide](#winesapos-install-guide)
      * [First-Time Setup](#first-time-setup)
      * [Upgrades](#upgrades)
          * [Minor Upgrades](#minor-upgrades)
          * [Major Upgrades](#major-upgrades)
      * [Uninstall](#uninstall)
      * [Convert to winesapOS](#convert-to-winesapos)
   * [Tips](#tips)
      * [Windows Games on Steam](#windows-games-on-steam)
      * [Steam Deck Game Mode](#steam-deck-game-mode)
      * [No Sound (Muted Audio)](#no-sound-muted-audio)
      * [Btrfs Backups](#btrfs-backups)
      * [VPN (ZeroTier)](#vpn-zerotier)
   * [Troubleshooting](#troubleshooting)
       * [Release Image Zip Files](#release-image-zip-files)
       * [winesapOS Not Booting](#winesapos-not-booting)
       * [Access Boot Menu](#access-boot-menu)
       * [Root File System Resizing](#root-file-system-resizing)
       * [Read-Only File System](#read-only-file-system)
       * [Wi-Fi or Bluetooth Not Working](#wi-fi-or-bluetooth-not-working)
       * [Available Storage Space is Incorrect](#available-storage-space-is-incorrect)
       * [First-Time Setup Log Files](#first-time-setup-log-files)
       * [Two or More Instances of winesapOS Cause an Unbootable System](#two-or-more-instances-of-winesapos-cause-an-unbootable-system)
       * [Snapshot Recovery](#snapshot-recovery)
       * [Reinstalling winesapOS](#reinstalling-winesapos)
       * [Bad Performance on Battery](#bad-performance-on-battery)
       * [Bad Performance on NVIDIA](#bad-performance-on-nvidia)
   * [Frequently Asked Questions (FAQ)](#frequently-asked-questions-faq)
   * [Contributors](#contributors)
   * [History](#history)
   * [License](#license)

## Features

### General

- **Any computer with a modern AMD or Intel processor can run winesapOS.**
- **Portability.**
    - A drive is bootable on both BIOS and UEFI systems.
    - Lots of [boot optimizations](https://rootpages.lukeshort.cloud/storage/bootloaders.html#usb-installation-with-both-legacy-bios-and-uefi-support) are made to make winesapOS more portable than most live Linux distributions.
    - Applications are installed using Flatpaks, a universal package manager for Linux, where possible.
- **Persistent storage.** Unlike traditional Linux live media, all storage is persistent and kept upon reboots.
    - Upon the first boot, the root partition is expanded to utilize all available space.
- **Supportability.** Linux is easy to troubleshoot remotely.
    - Access:
        - SSH can be accessed via clients on the same [ZeroTier VPN](https://www.zerotier.com/) network.
        - [tmate](https://tmate.io/) makes sharing SSH sessions without VPN connections easy.
    - Tools:
        - [ClamAV](https://www.clamav.net/), and the GUI front-end [Clamtk](https://github.com/dave-theunsub/clamtk), is an open source anti-virus scanner.
        - [QDirStat](https://github.com/shundhammer/qdirstat) provides a graphical user interface to view storage space usage.
- **Usability.** Software for typical day-to-day use is provided.
    - [asusctl](https://gitlab.com/asus-linux/asusctl) = for managing ASUS computers.
    - [Balena Etcher](https://www.balena.io/etcher/) for an image flashing utility.
    - [Blueman](https://github.com/blueman-project/blueman) for a Bluetooth pairing client.
    - [Bottles](https://usebottles.com/) for installing any Windows program.
    - [Calibre](https://calibre-ebook.com/) for managing ebooks.
    - [CDEmu](https://cdemu.sourceforge.io/) for virtualizing disc drives.
    - [CoolerControl](https://gitlab.com/coolercontrol/coolercontrol) for managing computer fans.
    - [Discord](https://discord.com/) for a gaming chat client.
    - [Discover](https://apps.kde.org/discover/) for a GUI Flatpak package manager.
    - [Distrobox](https://github.com/89luca89/distrobox) for managing containers.
    - [Dolphin](https://apps.kde.org/dolphin/) (KDE Plasma), [Nemo](https://github.com/linuxmint/nemo) (Cinnamon), [cosmic-files](https://github.com/pop-os/cosmic-files) (COSMIC), or [Nautilus](https://wiki.gnome.org/action/show/Apps/Files?action=show&redirect=Apps%2FNautilus) (GNOME) for a file manager.
    - [FileZilla](https://filezilla-project.org/) for a FTP client.
    - [Firefox ESR](https://support.mozilla.org/en-US/kb/switch-to-firefox-extended-support-release-esr) for a stable web browser.
    - [Firewall](https://firewalld.org/) (secure image) provides a GUI for managing firewalld.
    - [Flatseal](https://github.com/tchx84/Flatseal) for managing Flatpaks.
    - [GIMP](https://www.gimp.org/) for photo editing.
    - [GNOME Camera](https://apps.gnome.org/Snapshot/) for a webcam software.
    - [Google Chrome](https://www.google.com/chrome/) for a newer web browser.
    - [GParted](https://gparted.org/) for managing storage partitions.
    - [Gwenview](https://apps.kde.org/gwenview/) (KDE Plasma), [Pix](https://community.linuxmint.com/software/view/pix) (Cinnamon), [cosmic-files](https://github.com/pop-os/cosmic-files) (COSMIC), or [Eye of GNOME](https://wiki.gnome.org/Apps/EyeOfGnome) (GNOME) for an image gallery application.
    - [Kalk](https://apps.kde.org/kalk/) for a calculator.
    - [KeePassXC](https://keepassxc.org/) for a cross-platform password manager.
    - [LibreOffice](https://www.libreoffice.org/) provides an office suite.
    - [Modem Manager GUI](https://sourceforge.net/projects/modem-manager-gui/) for using cellular modems.
    - [mpv](https://mpv.io/) for HDR video playback.
    - [Open Broadcaster Software (OBS) Studio](https://obsproject.com/) for a recording and streaming utility.
    - [PeaZip](https://peazip.github.io/) for an archive/compression utility.
    - [qBittorrent](https://www.qbittorrent.org/) for a torrent client.
    - [KMSCON](https://github.com/kmscon/kmscon) for a modern virtual console.
    - [Shelly](https://www.seafoam-labs.org/shelly-alpm/) for a GUI package manager for AppImage, Flatpak, Pacman, and AUR packages.
    - [Spectacle](https://apps.kde.org/spectacle/) for a screenshot utility.
    - [usbmuxd](https://github.com/libimobiledevice/usbmuxd) with backported patches to properly support iPhone file transfers and Internet tethering on T2 Macs.
    - [Waydroid](https://waydro.id/) for Android app and gaming support.
    - [VeraCrypt](https://www.veracrypt.fr/en/Home.html) for a cross-platform encryption utility.
    - [VLC](https://www.videolan.org/) for a media player.
    - [ZeroTier GUI](https://github.com/tralph3/ZeroTier-GUI) for a VPN utility for online LAN gaming.
- **Distro-agnostic package managers** for installing a large variety of software.
    - [Flatpak](https://flatpak.org/)
    - [Homebrew](https://brew.sh/)
    - [Nix](https://nixos.org/)
    - [Snap](https://snapcraft.io/)
- **Gaming support** out-of-the-box.
    - Game launchers:
        - [Steam](https://store.steampowered.com/).
        - [Heroic Games Launcher](https://github.com/Heroic-Games-Launcher/HeroicGamesLauncher) for Epic Games Store games.
        - [Lutris](https://lutris.net/) for all other games.
        - [Open Gamepad UI](https://github.com/ShadowBlip/OpenGamepadUI) for an open source video game console experience.
        - [Prism Launcher](https://prismlauncher.org/) for vanilla and modded Minecraft: Java Edition.
        - [Bottles](https://usebottles.com/) for all Windows programs.
        - [EmuDeck](https://www.emudeck.com/) for video game console emulators.
        - [NVIDIA GeForce Now](https://www.nvidia.com/en-us/geforce-now/) for streaming games from NVIDIA servers.
        - [Xbox Cloud Gaming](https://www.xbox.com/en-US/cloud-gaming) for streaming Xbox games.
    - Wine:
        - [Proton](https://github.com/ValveSoftware/Proton) is installed along with Steam for playing Windows games on Linux.
        - [GE-Proton](https://github.com/GloriousEggroll/proton-ge-custom) is installed along with the ProtonUp-Qt package manager for it. This provides better Windows games compatibility.
        - [umu-launcher](https://github.com/Open-Wine-Components/umu-launcher) for running non-Steam games with Proton.
    - [dmemcg-booster](https://pixelcluster.github.io/VRAM-Mgmt-fixed/) for allocating more VRAM to games in Gamescope and Plasma sessions.
    - [Chiaki](https://github.com/streetpea/chiaki-ng) for PS4 and PS5 game streaming.
    - [ckb-next](https://github.com/ckb-next/ckb-next) for supporting RGB on Corsair keyboards and mice.
    - [dmesg-booster](https://pixelcluster.github.io/VRAM-Mgmt-fixed/) for improving VRAM allocation to games in KDE Plasma and Gamescope sessions.
    - [DOSBox](https://www.dosbox.com/) for running 16-bit DOS and Windows (via Wine) applications.
    - [GameImage](https://github.com/gameimage/gameimage) for creating portables games.
    - [GameMode](https://github.com/FeralInteractive/gamemode) is available to be used to speed up games.
    - [Gamescope](https://github.com/OpenGamingCollective/gamescope) from the Open Gaming Collective (OGC) for helping play older games with frame rate or resolution issues.
    - [GOverlay](https://github.com/benjamimgois/goverlay) is a GUI for managing Vulkan overlays including MangoHud and vkBasalt.
    - [LACT](https://github.com/ilya-zlobintsev/LACT) for overclocking and/or undervolting the GPU.
    - [Ludusavi](https://github.com/mtkennerly/ludusavi) is a game save files manager.
    - [MangoHud](https://github.com/flightlessmango/MangoHud) for benchmarking OpenGL and Vulkan games.
    - [Moonlight](https://github.com/moonlight-stream/moonlight-qt) and [Sunshine](https://github.com/LizardByte/Sunshine) for game streaming.
    - [Nexus Mods app](https://github.com/Nexus-Mods/NexusMods.App) for managing mods.
    - [NonSteamLaunchers](https://github.com/moraroy/NonSteamLaunchers-On-Steam-Deck) to manage other game launchers.
    - [ProtonUp-Qt](https://github.com/DavidoTek/ProtonUp-Qt) for managing Steam Play compatibility tools.
    - [RemotePlayWhatever](https://github.com/m4dEngi/RemotePlayWhatever) for streaming non-Steam games with Steam Remote Play.
    - [RetroDECK](https://retrodeck.net/) for supporting various emulators.
    - [ZeroTier VPN](https://www.zerotier.com/) can be used to play LAN-only games online with friends.
    - Open source OpenGL and Vulkan drivers are installed for AMD, Intel, NVIDIA, VirtualBox, and VMware graphics.
- **Controller support** for most controllers.
    - All official PlayStation and Xbox controllers are supported.
    - All generic DirectInput and XInput controllers are supported.
    - [AntiMicroX](https://github.com/AntiMicroX/antimicrox) is provided for configuring controller input for non-Steam games.
    - [game-devices-udev](https://codeberg.org/fabiscafe/game-devices-udev) is provided for more controller support.
    - [InputPlumber](https://github.com/ShadowBlip/InputPlumber) for supporting handheld PC controllers.
    - [OpenRazer](https://openrazer.github.io/) and [Polychromatic](https://polychromatic.app/) are provided for Razer accessories.
    - [Oversteer](https://github.com/berarma/oversteer) is provided for managing racing wheels and related accessories.
- **Steam Deck look and feel**.
    - [Gamescope Session](https://github.com/ChimeraOS/gamescope-session) is provided to replicate the "Game Mode" from the Steam Deck.
    - KDE Plasma desktop environment is used.
- **Minimize writes** to the drive to improve its longevity.
    - Root file system is mounted with the options `noatime` and `nodiratime` to not write the access times for files and directories.
    - Temporary directories with heavy writes (`/tmp/` and `/var/log/`) are mounted as temporary file systems. `/var/tmp` is no longer mounted with a temporary file system due to issues with Podman and other programs.
    - [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) is configured to use volatile (RAM-only) storage for all system logs.
    - zram with lz4 compression is used for swap to maximize performance and avoid writing data to a swap file on the storage device.
        - Alternatively, a swap file can be used instead for hibernation support.
        - For a swap file, the swappiness level is set to 0.5% (down from the default of 30%) as recommended by CryoByte33's [CryoUtilities](https://github.com/CryoByte33/steam-deck-utilities).
    - Writes are heavily cached in RAM for faster performance.
    - Commit file system writes every 300 seconds (5 minutes) to minimize wear and tear.
    - libeatmydata is used for Firefox ESR and Google Chrome to improve performance and minimize writes.
        - Despite the name, all data (including bookmarks, history, signed-in profiles, etc.) are kept after exiting the application.
- **Full backups** via Btrfs.
    - [Snapper](https://github.com/openSUSE/snapper) takes 6 monthly snapshots of the `/home/` directory.
    - [snap-pac](https://github.com/wesbarnett/snap-pac) takes a snapshot whenever the `pacman` package manager is used.
    - [grub-btrfs](https://github.com/Antynea/grub-btrfs) automatically generates a GRUB menu entry for all of the Btrfs backups.
- **No automatic operating system updates.** Updates should always be intentional and planned.
- **Most file systems supported.** Access any storage device, anywhere.
    - APFS
    - Bcachefs
    - Boot File System (BFS)
    - Btrfs
    - CephFS
    - CIFS/SMB
    - eCryptFS
    - EROFS
    - ext2, ext3, and ext4
    - exFAT
    - F2FS
    - FAT12, FAT16, and FAT32
    - FATX16 and FATX32
    - GFS2
    - GlusterFS
    - HFS and HFS+
    - JFS
    - MinIO
    - MINIX file system
    - MooseFS
    - NFS
    - NILFS2
    - NTFS
    - OverlayFS
    - pifs (πfs)
    - ReiserFS = Use [winesapOS 4.5.0](https://github.com/winesapOS/winesapOS/releases/tag/4.5.0).
    - SquashFS
    - s3fs
    - SSDFS
    - SSHFS
    - UDF
    - Virtiofs
    - XFS
    - ZFS = Only works with Linux LTS.
- **Battery optimizations.**
    - The [TLP](https://github.com/linrunner/TLP) service provides automatic power management.
- **Fully automated installation.**

### 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](#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 | |
| Touchpad | Yes | [linux-t2 patches](https://github.com/Nobara-Project/rpm-sources/tree/main/baseos/kernel) |
| NVMe | Yes |  |
| Sound | Yes | [linux-t2 patches](https://github.com/Nobara-Project/rpm-sources/tree/main/baseos/kernel) and [apple-t2-audio-config](https://github.com/kekrby/t2-better-audio) |
| Fans | Yes | [mbpfan](https://github.com/linux-on-mac/mbpfan) |
| Bluetooth | Yes | [linux-t2 patches](https://github.com/Nobara-Project/rpm-sources/tree/main/baseos/kernel) and [apple-bcm-firmware](https://github.com/NoaHimesaka1873/apple-bcm-firmware) |
| Wi-Fi | Yes | [broadcom-wl](https://github.com/antoineco/broadcom-wl) and [apple-bcm-firmware](https://github.com/NoaHimesaka1873/apple-bcm-firmware) |
| Fingerprint scanner | No | |
| Touch Bar | Yes | [linux-t2 patches](https://github.com/Nobara-Project/rpm-sources/tree/main/baseos/kernel) |

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

-  Macs with the Apple T2 Security Chip (>= 2017)
    - Follow the t2linux [wiki](https://wiki.t2linux.org/guides/wifi-bluetooth/) for instructions on how to copy firmware files from macOS to Linux.
-  Macs without the Apple T2 Security Chip (< 2017)
    -  During the winesapOS First-Time Setup, select "Yes" when asked "Do you want to install the Broadcom proprietary Wi-Fi driver?"

#### ASUS Laptops

As of winesapOS 4.3.0, all drivers are now upstream. No third-party drivers are needed.

#### ASUS ROG Ally Handhelds

We provide support for the ASUS ROG Ally, ROG Ally X, ROG Xbox Ally, and ROG Xbox Ally X.

| Hardware | Supported | Third-Party Driver(s) |
| -------- | --------- | --------- |
| Controller | Yes | |
| NVMe | Yes | |
| Sound | Yes | |
| Fans | Yes | [linux-nobara patches](https://github.com/Nobara-Project/rpm-sources/blob/41/baseos/kernel/6.12.8/ROG-ALLY-NCT6775-PLATFORM.patch) |
| Bluetooth | Yes | |
| Wi-Fi | Yes | |
| Fingerprint scanner | No | |

#### AYANEO Handhelds

| Hardware | Supported | Third-Party Driver(s) |
| -------- | --------- | --------- |
| Controller | Yes | |
| NVMe | Yes | |
| Sound | Yes | [aw87559-firmware](https://aur.archlinux.org/packages/aw87559-firmware) |
| Fans | Yes | |
| Bluetooth | Yes | |
| Wi-Fi | Yes | |
| Fingerprint scanner | No | |

#### Framework Computer

[Framework Computer](https://frame.work/) desktop and laptops are supported. winesapOS has been tested on the Framework Laptop 13, Framework Laptop 16, and Framework Desktop. The Framework Laptop 12 is untested but should also work.

| 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](https://github.com/cab404/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](https://github.com/FrameworkComputer/inputmodule-rs/blob/main/ledmatrix/README.md) used for managing LED matrixes |

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

- (Boot into the BIOS by pressing "F2" when turning the device on) > Setup Utility > Advanced > Linux Audio Compatibility: Linux > (Save and exit by pressing "F10")

#### Lenovo Legion Go

As of winesapOS 4.3.0, all drivers are now upstream. No third-party drivers are needed.

#### Microsoft Surface Laptops

| Hardware | Supported | Third-Party Driver(s) |
| -------- | --------- | --------- |
| Keyboard | Yes | [linux-surface pathces](https://github.com/Nobara-Project/rpm-sources/tree/main/baseos/kernel) |
| Touchpad | Yes | |
| NVMe | Yes | |
| Sound | Yes | [linux-surface patches](https://github.com/Nobara-Project/rpm-sources/tree/main/baseos/kernel) |
| Fans | Yes | [linux-surface patches](https://github.com/Nobara-Project/rpm-sources/tree/main/baseos/kernel) |
| Bluetooth | Yes | [linux-surface patches](https://github.com/Nobara-Project/rpm-sources/tree/main/baseos/kernel) |
| Wi-Fi | Yes | [linux-surface patches](https://github.com/Nobara-Project/rpm-sources/tree/main/baseos/kernel) |
| Fingerprint scanner | No | |
| Touchscreen | Yes | [IPTSD](https://github.com/linux-surface/iptsd), [libwacom-surface](https://github.com/linux-surface/libwacom), and [linux-surface patches](https://github.com/Nobara-Project/rpm-sources/tree/main/baseos/kernel) |

#### MSI Claw Handhelds

As of winesapOS 4.4.0, no third-party drivers are needed besides using InputPlumber. The MSI Claw A1M, 7 AI+ A2VM, 8 AI+ A2VM, and BZ2EM are all supported.

A quirk is used to stop the Intel Wi-Fi driver before sleep and start it back when waking up. This fixes a driver bug that prevents MSI Claw devices from sleeping.

#### OneXPlayer Handhelds

As of winesapOS 4.3.0, all drivers are now upstream. No third-party drivers are needed.

#### 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 | [linux-nobara patches](https://github.com/Nobara-Project/rpm-sources/tree/main/baseos/kernel) and [linux-firmware-valve](https://aur.archlinux.org/packages/linux-firmware-valve) |
| Fans | Yes | |
| Bluetooth | Yes | [linux-nobara patches](https://github.com/Nobara-Project/rpm-sources/tree/main/baseos/kernel) and [linux-firmware-valve](https://aur.archlinux.org/packages/linux-firmware-valve) |
| Wi-Fi | Yes | [linux-nobara patches](https://github.com/Nobara-Project/rpm-sources/tree/main/baseos/kernel) and [linux-firmware-valve](https://aur.archlinux.org/packages/linux-firmware-valve) |
| Touchscreen | Yes | |

### Community Collaboration

We are a proud member of the [Open Gaming Collective (OGC)](https://opengamingcollective.org/). Our goal is to provide a unified gaming experience across various different Linux distributions.

### winesapOS Repository

- ![winesapOS rolling Pacman repository build](https://github.com/winesapOS/winesapOS/actions/workflows/repo-rolling.yml/badge.svg)

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:

-  Arch Linux and Manjaro:
    ```
    sudo sed -i s'/\[core]/[winesapos-rolling]\nServer = https:\/\/winesapos.lukeshort.cloud\/repo\/$repo\/$arch\n\n[core]/'g /etc/pacman.conf
    sudo pacman -S -y -y
    ```

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, Intel, and QEMU/KVM (VirtIO-GPU Venus) | AMD, Intel, NVIDIA, Parallels, QEMU/KVM (VirtIO-GPU Venus), 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 | flatpak, homebrew, nix, pacman, paru and yay (AUR), and snap |
| Preferred package manager (CLI) | flatpak | flatpak |
| Package managers (GUI) | Discover (flatpak) | Discover (flatpak) and Shelly (AppImage, flatpak, pacman, and AUR) |
| 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, NVIDIA GeForce Now, Open Gamepad UI, Prism Launcher, and Xbox Cloud Gaming |
| Linux kernels | Neptune (6.16) | Linux LTS (6.18) and Linux Nobara (Latest) |
| Additional Apple Intel Mac drivers | No | Yes |
| Additional ASUS laptop drivers | No | Yes |
| Additional ASUS ROG Ally handheld drivers | Yes | Yes |
| Additional AYANEO handheld drivers | No | Yes |
| Additional Framework Computer drivers | No | Yes |
| Additional Microsoft Surface laptop drivers | No | Yes |
| Desktop environment | KDE Plasma 6 | KDE Plasma 6 |
| Desktop theme | Vapor | Breeze |
| AMD FSR 1 | Global | Global |
| Gamescope | Nested and Embedded | Nested and Embedded |
| Wine | Proton | Proton and GE-Proton |
| Game controller support | Medium | Large |
| exFAT cross-platform storage | No | Yes (16 GiB by default, optional on all image types) |

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](https://github.com/winesapOS/winesapOS) | [2022-03-06](https://github.com/winesapOS/winesapOS/commit/2488cf702084d414ec5319a55cfbee1b86e2b05b) | [2022-03-10](https://github.com/winesapOS/winesapOS/tree/3.0.0-beta.0) |
| [SteamOS for PS4](https://wololo.net/2022/03/28/release-steamos-3-0-for-ps4-unofficial/) | [2022-03-09](https://twitter.com/NazkyYT/status/1501670690453438471?cxt=HHwWjoC-oa3igNcpAAAA) | [2022-03-25](https://twitter.com/NazkyYT/status/1507284235765182465?cxt=HHwWgsCjhdnB-eopAAAA) |
| [HoloISO](https://github.com/HoloISO/holoiso) | [2022-04-21](https://github.com/HoloISO/holoiso/commit/b04bccfb78567c9958f376659703b58e87ecd359) | [2022-05-01](https://github.com/HoloISO/holoiso/releases/tag/beta0) |

## Usage

### Getting Started

#### Hardware Requirements

Minimum:

- Processor = Single-core AMD or Intel processor.
- RAM = 2 GiB.
- Graphics = AMD, Intel, NVIDIA, Parallels Desktop, VirtualBox, or VMware Fusion/Workstation virtual graphics device.
- Storage
    - Minimal image = 16 GB USB 3.2 Gen 1 (USB 3.0) flash drive.
    - Performance image = 64 GB USB 3.2 Gen 1 (USB 3.0) flash drive.

Recommended:

- Processor = Quad-core AMD or Intel processor.
- RAM = 8 GiB.
- Graphics = AMD discrete graphics card.
- Storage
    - Internal = 512 GB NVMe SSD.
    - External = 512 GB USB 3.2 Gen 2 (USB 3.1) SSD.

**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](https://www.tomshardware.com/best-picks/best-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. SSD and NVMe drives have a longer life-span, more storage, and faster speeds compared to traditional flash storage.

Here are drives that our team has specifically tested and recommends.

| Use-case | Drive |
| -------- | ----- |
| Desktop PC | ASUS ROG Strix Arion Drive Enclosure\* |
| Desktop PC | SanDisk Extreme Portable SSD |
| Handheld PC | Genki SavePoint\* |
| USB Type-A Flash Drive | Samsung FIT Plus Flash Drive |
| USB Type-C Flash Drive | Samsung Type-C USB Blue Flash Drive |
| Framework Computer | Framework Computer Storage Expansion Card |

\*NVMe drive not included.

#### Image Types

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

- **Minimal** = A small variant of the performance image.
- **Performance** =  Everything but the kitchen sink, speed, and ease-of-use.
- **Secure** = Locked down and recommended for advanced Linux users only.
    - There are no release builds for the secure image. Use a [custom build](#custom-builds) to generate a unique LUKS container encryption key.

| Feature | Minimal | Performance | Secure |
| ------- | ------- | ----------- | ------ |
| CPU Mitigations | No | No | Yes |
| Encryption | No | No | Yes (LUKS) |
| Firewall | No | No | Yes (Firewalld) |
| Persistent `/var/log/` | No | No | Yes |
| `root` Password Requires Reset | No | No | Yes |
| Pre-built release image | Yes | Yes | No |

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](#docker-or-podman-container), [dual-boot](#dual-boot), or [WSL 2](#windows-subsystem-for-linux) scenario.

##### Secure Image

The user account password for `winesap` and `root` are the same as the username. Both users are set to have their passwords 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.
5. The first-time setup will eventually prompt to enter a new `root` password.

Automatic TPM unlock for LUKS  is not used because it is not a portable solution.

#### Release Builds

0. Refer to the [Mac Boot](#mac-boot) and [Windows Boot](#windows-boot) guides to avoid common issues.
1. Download the latest release from [here](https://github.com/winesapOS/winesapOS/releases).
    - External drive
        - Download one the of the release images and then continue on with this guide.
            - Performance (recommended) = Requires 32 GiB of free space to download and extract.
            - Minimal (for users low on storage space or who want control over what is installed) = Requires 14 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 Balena Etcher, 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)
            - Refer to the [Dual-Boot](#dual-boot) guide.
    - If you want even more control over the how the image is built, consider doing a [custom build](#custom-builds) instead.
2. Extract the `winesapos-<VERSION>-<TYPE>.img.zip` archive.
3. 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 [Balena Etcher](https://www.balena.io/etcher/) or [USBImager](https://bztsrc.gitlab.io/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.
        - Add at least 32 GiB.
            ```
            $ qemu-img resize winesapos*.img +32G
            ```
        - GNOME Boxes > + > Install from File > (select the winesapOS image file) > Open > Operating System: Arch Linux, Memory: 4.0 GiB > Create
    3. with QEMU/KVM and VirtIO-GPU Venus for Vulkan pass-through support.
        - Install the OVMF package to get the variables file.
            - Arch Linux:
                ```
                $ sudo pacman -S edk2-ovmf
                $ cp /usr/share/OVMF/x64/OVMF_VARS.4m.fd ./OVMF_VARS.fd
                ```
            - Debian:
                ```
                $ sudo apt update
                $ sudo apt install ovmf
                $ cp /usr/share/OVMF/OVMF_VARS_4M.fd ./OVMF_VARS.fd
                ```
            - Fedora:
                ```
                $ sudo dnf install edk2-ovmf
                $ cp /usr/share/OVMF/OVMF_VARS.fd ./OVMF_VARS.fd
                ```
        - Add at least 32 GiB of storage. Use a recommended minimum of 8 GiB of system RAM and 4 GiB of VRAM.
            ```
            $ qemu-img resize winesapos*.img +32G
            $ qemu-system-x86_64 \
               -enable-kvm \
               -machine q35 \
               -smp 4 \
               -m 8G \
               -drive if=pflash,format=raw,readonly=on,file=/usr/share/OVMF/OVMF_CODE.fd \
               -drive if=pflash,format=raw,file=OVMF_VARS.fd \
               -drive file=winesapos-<VERSION>-<TYPE>.img,format=raw,if=virtio \
               -netdev user,id=vmnic,hostfwd=tcp::2222-:22 \
               -device virtio-net,netdev=vmnic \
               -vga none \
               -device virtio-vga-gl,hostmem=4G,blob=true,venus=true \
               -display gtk,gl=on
            ```
    4. 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
    5. 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
    6. 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](https://www.starwindsoftware.com/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.

7. 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](https://www.starwindsoftware.com/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 Graphics: Yes > Shared graphics memory: (set this to the highest possible value)
    8. 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.

If using the recommended defaults of the first-time setup and after rebooting, press the enter/return key (on a handheld with a touchscreen, tap the "Password" field to display the virtual keyboard) on the login screen for passwordless login.

#### Custom Builds

- ![Image build status for Arch Linux](https://github.com/winesapOS/winesapOS/actions/workflows/image-arch-linux.yml/badge.svg)
- ![Image build status for Manjaro](https://github.com/winesapOS/winesapOS/actions/workflows/image-manjaro.yml/badge.svg)

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](https://archlinux.org/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](https://manjaro.org/download/) either the Plasma, Cinnamon, or GNOME desktop edition of Manjaro.
    - 1b. For Ventoy support, use a virtual machine with one virtual drive and the Arch Linux ISO mounted as a virtual DVD. Otherwise, `vtoyboot` will fail to install if more than one drive is detected.

2. Boot into the flash drive.
3. Update the known packages cache and install git.

```
    pacman -S -y
    pacman -S git
    ```

4. Clone the winesapOS repository and go to the "scripts" directory.

```
    git clone https://github.com/winesapos/winesapos.git
    cd ./winesapos/scripts/
    ```

5. Configure [environment variables](https://github.com/winesapOS/winesapOS/blob/main/CONTRIBUTING.md#environment-variables-for-installation) 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. By default, the performance image will be built. Alternatively, source the environment variables to configure the build to make the minimal or secure image instead.

```
    . ./env/winesapos-env-minimal.sh
    ```

```
    . ./env/winesapos-env-secure.sh
    ```

7. Run the build.

```
    sudo -E bash ./winesapos-install.sh
    ```

8. 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](CONTRIBUTING.md) guide.

#### Docker or Podman Container

winesapOS 4.0.0 and newer minimal images are extracted, archived, and then uploaded as container images to a [Quay.io container registry](https://quay.io/repository/lukeshortcloud/winesapos?tab=tags). Select older versions are also available. For versions that did not have a minimal image, the performance image was used instead.

#### 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.

- [Install](https://learn.microsoft.com/en-us/windows/wsl/install) WSL 2.
- Download the [winesapos-wsl.ps1](https://raw.githubusercontent.com/winesapOS/winesapOS/stable/scripts/winesapos-wsl.ps1) script.
- Open PowerShell and navigate to the downloaded location.
- Allow and run the PowerShell script.

```
    PS C:\Users\user\Downloads> powershell -ExecutionPolicy Bypass -File .\winesapos-wsl.ps1
    ```

- Verify that a new "winesapOS" virtual machine appears.

```
    PS C:\Users\user\Downloads> wsl --list
    ```

- Enter the virtual machine.

```
    PS C:\Users\user\Downloads> wsl --distribution winesapOS
    ```

- Verify that it is winesapOS.

```
    cat /usr/lib/os-release-winesapos
    ```

#### Passwords

| Username | Password |
| -------- | -------- |
| root | root |
| winesap | winesap |

On the secure image, the `winesap` user and the `root` user are forced changed as part of the first-time setup.

#### Mac Boot

**IMPORTANT** Any [Mac with an Apple T2 Security Chip](https://support.apple.com/en-us/HT208862), which are all Macs made in and after 2018, needs to [allow booting from external storage](https://support.apple.com/en-us/HT208198):

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.)
3. Reboot the Mac.
    - (Select the Apple logo in the top-left) > Restart

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.

#### Windows Boot

1. Secure Boot is not supported.
    - Disable BitLocker first if using a Windows edition that supports BitLocker and it is enabled.
        - Control Panel > System and Security > BitLocker Drive Encryption > Turn off BitLocker > Turn off BitLocker
    - Then disable Secure Boot in the BIOS.
2. Disable fast startup and hibernation as these cause 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)" and "Hibernate") > 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``.
3. Configure Windows to use [UTC](https://wiki.archlinux.org/title/System_time#UTC_in_Microsoft_Windows) for the hardware clock by running this in an Administrator Command Prompt.
    ```
    C:\Windows\System32>reg add "HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\TimeZoneInformation" /v RealTimeIsUniversal /d 1 /t REG_DWORD /f
    ```

#### Ventoy

As of winesapOS 4.2.0, [Ventoy](https://www.ventoy.net/en/index.html) is supported. It only works with UEFI boot (not legacy BIOS boot).

0. Install Ventoy v1.0.98 or newer onto an external drive.
1. Rename the `winesapos-<VERSION>-<TYPE>.img` raw image to `winesapos.vtoy`.
2. Resize the root partition.
    ```
    # This example increases the size by 40 GiB.
    # Any size can be used.
    $ qemu-img resize winesapos.vtoy +40G
    $ sudo losetup --find --partscan --show winesapos.vtoy
    $ lsblk | grep loop
    # Grow the root partition which is always partition "4".
    $ sudo growpart /dev/loop0 4
    $ sudo losetup --detach /dev/loop0
    $ sync
    ```
3. Copy the `winesapos.vtoy` image to the Ventoy drive.

#### Installer

winesapOS was originally designed to be a portable operating system. Due to popular demand, an installer was added to easily install it to an internal drive or dual-boot alongside an existing operating system.

Only UEFI is supported for dual-boot installations of winesapOS. For legacy BIOS boot, [create and flash](#getting-started) a normal portable [release](https://github.com/winesapOS/winesapOS/releases) image. Those all support both legacy BIOS boot and UEFI.

##### 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.
    - Terminal > Quit Terminal
2. Follow the [Mac Boot](#mac-boot) guide.
    - Reboot the Mac 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](https://sourceforge.net/projects/refind/) 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 from macOS. This is much safer than using Linux tools.
    - 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

##### SteamOS Dual-Boot Preparation Guide

1. Update to SteamOS 3.8 or newer.
2. Secure Boot is not supported.
    - Secure Boot is already disabled on "Powered by SteamOS" devices.
    - Other devices will need to have Secure Boot disabled in the BIOS.

##### Windows Dual-Boot Preparation Guide

1. Follow the [Windows Boot](#windows-boot) guide.
2. Create free storage space for winesapOS from Windows. This is much safer than using Linux tools.
    - 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 Install Guide

0. For dual-boot only, Install (if necessary) Linux, macOS, or Windows first.
1. Follow the winesapOS [getting started](#getting-started) guide to flash a winesapOS image onto an external drive.
2. Boot into winesapOS that is on the external drive.
3. The "winesapOS First-Time Setup" starts automatically on the first login. Answer "Yes" when it asks whether to install winesapOS onto an internal drive.
    - The first-time setup exits once the installer is done. It runs again after booting the new installation. That is when the system should be configured.
    - Answer "No" to skip the installer and configure this as a live drive instead.
4. On the "Welcome" page, select your language.
5. On the "Partitions" page, first "Select storage device" to install onto.
    - For a dual-boot installation on the same drive as another Linux operating system, select "Install alongside".
        - Click on the largest partition in "Current". Then drag the new partition in "After" to the desired size.
    - For a dual-boot installation on the same device as macOS, select "Replace a partition".
        - Click on the exFAT partition in "Current".
    - For a dual-boot installation on the same device as Windows, select "Replace a partition".
        - Click on the "Free Space" partition in "Current".
    - For a single drive that will only have winesapOS, select "Erase disk".
        - **DO NOT DO THIS ON A MAC!** This will wipe the rEFInd bootloader and macOS which is required for extracting firmware.
6. On the "Keyboard" page, select the "Keyboard model".
7. On the "Summary" page, there is an overview to confirm the installation details. If everything looks correct, select "Install" to perform an offline installation.
8. Shutdown the computer, unplug the winesapOS external drive, and then turn the computer back on.
9. For dual-boot, boot into the original operating system again.
    - macOS
        - Use the GRUB boot menu.
            - Select "rEFInd Boot Manager" and then "Boot macOS from Preboot".
        - Alternatively, use the Mac bootloader.
            - Press and release the power button.
            - Hold down the `option` key (or the `Alt` key on a Windows keyboard) to access the Mac bootloader.
            - Select "Macintosh HD".
    - Other operating systems
        - 0. By default, most operating systems will appear in the GRUB boot menu.
        - 1. If not, then enable `os-prober` to add boot entries to the GRUB boot menu.
            ```
            sudo crudini --ini-options=nospace --set /etc/default/grub "" GRUB_DISABLE_OS_PROBER false
            sudo grub-mkconfig -o /boot/grub/grub.cfg
            ```
        - 2. If `os-prober` does not work, use the GRUB boot menu to select the "UEFI Firmware Settings" option. A BIOS boot menu will be available there.

### 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 | Recommended Default |
| --- | --- |
| exFAT Cross-platform storage | 16 GiB |
| Broadcom proprietary Wi-Fi driver | Automatic |
| Rotate screen | No |
| Older version of winesapOS | Stop and prompt user |
| Pacman mirror region | Automatic (GeoIP) |
| Graphics driver | Mesa |
| Swap method | zram |
| Time zone | Automatic (GeoIP) |
| Additional desktop environments | No |
| Recommended productivity apps | Yes |
| Recommended gaming apps | Yes |
| Automatic file system backups | No |
| Passwordless login\* | Yes (minimal and performance) and No (secure) |
| Hide GRUB boot menu | No |
| Upgrade firmware | No |
| Change user password | Yes |
| Change root password | Yes |
| Locale | Ask |

\*Press the enter/return key (on a handheld with a touchscreen, tap the "Password" field to display the virtual keyboard) on the login screen for passwordless login.

### Upgrades

#### Minor Upgrades

- ![winesapOS upgrade from 4.0.0 to latest status badge](https://github.com/winesapOS/winesapOS/actions/workflows/upgrade-4.0.0.yml/badge.svg)
- ![winesapOS upgrade from 4.1.0 to latest status badge](https://github.com/winesapOS/winesapOS/actions/workflows/upgrade-4.1.0.yml/badge.svg)
- ![winesapOS upgrade from 4.2.0 to latest status badge](https://github.com/winesapOS/winesapOS/actions/workflows/upgrade-4.2.0.yml/badge.svg)
- ![winesapOS upgrade from 4.3.0 to latest status badge](https://github.com/winesapOS/winesapOS/actions/workflows/upgrade-4.3.0.yml/badge.svg)
- ![winesapOS upgrade from 4.4.0 to latest status badge](https://github.com/winesapOS/winesapOS/actions/workflows/upgrade-4.4.0.yml/badge.svg)
- ![winesapOS upgrade from 4.5.0 to latest status badge](https://github.com/winesapOS/winesapOS/actions/workflows/upgrade-4.5.0.yml/badge.svg)

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](https://github.com/winesapOS/winesapOS/blob/main/UPGRADES.md) notes. This showcases what updates will happen automatically and what updates may need to be manually applied.

Do **NOT** use "Pamac", "Applications (bauh)", or "Shelly" for upgrades, only for package installations.

Instructions:

- GUI = Launch the "winesapOS Upgrade" desktop shortcut.
- CLI = Launch the winesapOS upgrade script from the main branch.

```
    # winesapOS 4.0.0 only.
    #curl https://raw.githubusercontent.com/winesapOS/winesapOS/main/scripts/winesapos-upgrade.sh | sudo -E bash
    # winesapOS 4.1.0 and newer.
    tmux new-session -d -s winesapos-upgrade 'curl https://raw.githubusercontent.com/winesapOS/winesapOS/main/scripts/winesapos-upgrade.sh | sudo -E bash'
    ```

#### Major Upgrades

- ![winesapOS upgrade from 2.2.0 to latest status badge](https://github.com/winesapOS/winesapOS/actions/workflows/upgrade-2.2.0.yml/badge.svg)
- ![winesapOS upgrade from 3.0.0 to latest status badge](https://github.com/winesapOS/winesapOS/actions/workflows/upgrade-3.0.0.yml/badge.svg)
- ![winesapOS upgrade from 3.2.1 to latest status badge](https://github.com/winesapOS/winesapOS/actions/workflows/upgrade-3.2.1.yml/badge.svg)
- ![winesapOS upgrade from 3.4.0 to latest status badge](https://github.com/winesapOS/winesapOS/actions/workflows/upgrade-3.4.0.yml/badge.svg)

Instructions:

- Open `Terminator` and run the command `screen` or `tmux` to open a virtual console.
    - If neither of those are installed, open a new console by pressing `CTRL`, `ALT`, and `F4` at the same time.
    - This is required if the desktop environment and/or display manager temporarily crash during the upgrade.
- Run a major upgrade of winesapOS.
    - Mac Linux Gaming Stick 2 to winesapOS 4:
        ```
        echo stick > /tmp/winesapos_user_name.txt
        export WINESAPOS_UPGRADE_FILES=false
        curl https://raw.githubusercontent.com/winesapOS/winesapOS/main/scripts/winesapos-upgrade.sh | sudo -E bash
        ```
    - winesapOS 3 to winesapOS 4:
        - GUI = Launch the "winesapOS Upgrade" desktop shortcut.
        - CLI:
            ```
            curl https://raw.githubusercontent.com/winesapOS/winesapOS/main/scripts/winesapos-upgrade.sh | sudo -E bash
            ```
- Before rebooting, it is highly recommended to run the major upgrade one more time.
- Reboot.

### 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/winesapOS/winesapOS/main/scripts/winesapos-uninstall.sh | sudo -E bash
```

### Convert to winesapOS

- ![Convert Arch Linux to winesapOS](https://github.com/winesapOS/winesapOS/actions/workflows/convert-arch-linux.yml/badge.svg)
- ![Convert Manjaro to winesapOS](https://github.com/winesapOS/winesapOS/actions/workflows/convert-manjaro.yml/badge.svg)

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:

- For Arch Linux and Manjaro only:
    - Add winesapOS and Chaotic AUR repositories.
    - Install all AUR packages from winesapOS.
- For all Linux distributions:
    - Install all Flatpak packages from winesapOS.

What it does NOT do:

- Install all system packages from winesapOS (coming soon).
- Install support for specific computer hardware.
- Install desktop environments or tiling window managers.
- Modify the bootloader.

Run this script to convert to winesapOS:

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

## Tips

### Windows Games on Steam

Enable Proton on Steam to allow installing Windows games on Linux. For more information about Proton, [read this starter guide](https://www.gamingonlinux.com/2019/07/a-simple-guide-to-steam-play-valves-technology-for-playing-windows-games-on-linux). Check the compatibility rating for games on Steam by using [ProtonDB](https://www.protondb.com/).

```
Settings > Steam Play > Enable Steam Play for Support Titles > Use this tool instead of game-specific selections from Steam > Compatibility tool: > (select the latest "Proton" version available) > OK
```

### Steam Deck Game Mode

On the Plasma Login Manager (PLM) login screen for the "winesap" user, the "Desktop Session" drop-down menu in the top-left can be used to change the session from "Plasma (Wayland)" to "Steam Big Picture". This provides the same experience as having a Steam Deck in "Game Mode" by launching Steam with Gamescope Session running in embedded mode.

Switch from Game Mode to Desktop Mode:

- In Steam, select the "Power" menu and then select "Switch to Desktop".
- On the PLM login page, use the top-left drop-down to select the desired session.
- Tap the password field to open the virtual keyboard.
- Press the enter key in the bottom-right of the virtual keyboard to login.

Known issues:

- A user must first login to the KDE Plasma desktop environment session and go through the winesapOS first-time setup. This will automatically download the Steam client bootstrap files required for the new Big Picture mode. Otherwise, install `steam` and then run "Steam (Runtime)" at least once to download the required files.
- Using this on devices that are not "Powered by SteamOS" certified will have varied results.
    - For example, configuring TDP for other devices may not work.
- NVIDIA support is still a work-in-progress. Mesa does not work yet. The NVIDIA open kernel module works but it is extremely slow.

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" session on the PLM login screen. It has plugins for Lutris, Steam, 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 volume level to be saved on reboots:

```
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>
```

Remove the quota limit on backups (50 GiB by default):

```
$ sudo btrfs qgroup show / | grep -P "\ \.snapshots$"
$ sudo btrfs qgroup limit none <QGROUP_ID_ROOT> /
$ sudo btrfs qgroup show / | grep -P "\ home\/\.snapshots$"
$ sudo btrfs qgroup limit none <QGROUP_ID_HOME> /
```

Disable all Btrfs quotas to prevent the `btrfs-cleaner` program from running. Then check to ensure it is actually disabled. Otherwise, it can cause [major performance issues](https://www.suse.com/support/kb/doc/?id=000020696).

```
$ sudo btrfs quota disable /
$ sudo btrfs qgroup show /
```

### 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](https://my.zerotier.com/).
2. They must then create a [ZeroTier network](https://clover.coex.tech/en/zerotier_vpn.html).
    1. Login to [ZeroTier Central](https://my.zerotier.com/).
    2. Select "[Networks](https://my.zerotier.com/network)".
    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 14 GiB (minimal image) or 32 GiB (performance 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.

- Refer to the [Mac Boot](#mac-boot) and [Windows Boot](#windows-boot) guides to avoid common issues.
- USB mode.
    - If using a USB Type-C cable, try flipping it upside down (180 degrees).
        - If using a USB Type-C to Type-A adapter, only one of the USB Type-C sides is full speed so orientation does matter.
    - If using an external drive, set the USB mode to xHCI instead of DRD in the BIOS.
    - The USB cable or port may be loose. Try a different cable and port.
- SATA mode.
    - If using an internal drive, set the SATA mode to AHCI instead of RAID in the BIOS.
        - Some NVMe drives use a SATA (not PCIe) connector and also need this setting change.
- Legacy BIOS boot.
    - Older motherboards that do not support GPT partition layouts will not be able to boot winesapOS.
    - Manually converting winesapOS from GPT to MBR and re-installing the GRUB bootloader does not fix this issue.

### Access Boot Menu

If the recommended defaults of the first-time setup are used, then the GRUB boot menu will be hidden. It can still be accessed by using these keyboard shortcuts:

- UEFI = `SHIFT` + `F1`
- Legacy BIOS boot = `ESC[APE]` + `F1`

### Root File System Resizing

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

**Solution:**

The root file system is resized by the first-time setup, not automatically on boot, because it needs
to know if an exFAT partition for cross-platform storage should be reserved at the end of the storage
device and how big it should be.

1. Re-run the "winesapOS First-Time Setup" shortcut on the desktop.
2. Alternatively, run the resize script manually. The argument is the size, in GiB, to reserve at the
end of the storage device for the exFAT partition. Use `0` to grow the root partition to use the
entire storage device.

```
    sudo /usr/bin/winesapos-resize-root-file-system.sh 16
    ```

Open up a [GitHub Issue](https://github.com/winesapOS/winesapOS/issues) with the full output if
it fails. The output is also saved in the first-time setup log in `/var/winesapos/`.

### 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:**

- Macs
    - Refer to the [Apple Intel Macs](#apple-intel-macs) guide to install the correct driver and/or firmware.
- Windows
    - Refer to the [Windows Boot](#windows-boot) guide to disable fast startup and hibernation.

### 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](#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 Instances of winesapOS Cause an Unbootable System

**Challenge: more than one instance of winesapOS on the same computer leads to both being unbootable.**

**Solutions:**

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 fatlabel /dev/${DEVICE}2 WOS-EFI2
    sudo sed -i s'/LABEL=WOS-EFI/LABEL=WOS-EFI2/'g /etc/fstab
    sudo -E e2label /dev/${DEVICE}3 winesapos-boot2
    sudo sed -i s'/LABEL=winesapos-boot/LABEL=winesapos-boot2/'g /etc/fstab
    sudo btrfs filesystem label / winesapos-root2
    sudo btrfs filesystem show /
    sudo sed -i s'/LABEL=winesapos-root/LABEL=winesapos-root2/'g /etc/fstab
    # Only required if the optional exFAT partition was created during the first-time setup.
    sudo -E exfatlabel /dev/${DEVICE}5 wos-drive2
    lsblk -o name,label
    ```

```
    # GRUB needs to be updated with the new /etc/fstab information.
    $ sudo sed -i 's/linux_root_device_thisversion=LABEL=winesapos-root$/linux_root_device_thisversion=LABEL=winesapos-root2/g' /etc/grub.d/10_linux
    $ sudo sed -i 's/winesapos-root\//winesapos-root2\//'g /usr/share/libalpm/hooks/winesapos-etc-grub.d-10_linux.hook
    $ sudo sed -i 's/--label winesapos-root /--label winesapos-root2 /g' /usr/share/grub/grub-mkconfig_lib
    $ sudo sed -i 's/--label winesapos-root /--label winesapos-root2 /g' /usr/share/libalpm/hooks/winesapos-usr-share-grub-grub-mkconfig_lib.hook
    $ sudo grub-mkconfig -o /boot/grub/grub.cfg
    ```

2. **Use a different version of winesapOS.** Changing the labels from the first solution is always required. However, UUIDs may also need to be different. The easiest way to do this is to use a different version of winesapOS, a different image variant of winesapOS, or to use a [custom build](#custom-builds). These will all have different UUIDs.
3. **Set a unique hostname.** If using winesapOS 4.5.0 or older, the hostname will be the same. It is recommended to use the "winesapOS Upgrade" desktop shortcut. One of the upgrade steps is to set a unique hostname if a generic one is detected.

### Snapshot Recovery

**Challenges:**

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

**Solution:**

1. At the GRUB boot menu select "winesapOS 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](https://github.com/Antynea/grub-btrfs/issues/92).

### Reinstalling winesapOS

Reinstalling winesapOS on-top of an existing winesapOS installation of the same exact version and image type can cause issues. The partition table needs to be cleared. **WARNING:** This will delete any existing data on that storage device.

```
sudo wipefs --all /dev/<DEVICE>
```

### Bad Performance on NVIDIA

The recommended defaults for the first-time setup configure NVIDIA to use the open source Mesa drivers. Performance on older NVIDIA cards is bad due to running at lower clock speeds. For Kepler through Maxwell architectures, use the following commands to run the GPU as higher clock speeds.

```
nvidia_performance_state="$(sudo cat /sys/kernel/debug/dri/0/pstate | tail -n 2 | head -n 1 | cut -d: -f1)"
echo "${nvidia_performance_state}" | sudo tee -a /sys/kernel/debug/dri/0/pstate
```

This higher performance state for NVIDIA is not enabled in winesapOS by default because (1) it does not always work and (2) it is not portable across different NVIDIA graphics cards. Newer NVIDIA cards are unaffected.

## Frequently Asked Questions (FAQ)

- **Is this the Mac Linux Gaming Stick project?**
    - Yes. Version 1 and 2 of the project were called Mac Linux Gaming Stick. In version 3, we rebranded to winesapOS.
- **How do you pronounce winesapOS?**
    - `wine`-`sap`-`o`-`s`.
- **What is the relevance of the word "winesap" in winesapOS?**
    - It is a type of apple which signifies how we were originally developing for Intel Macs. It also has the word "wine" in it which is the [name](https://www.winehq.org/) of the project used to enable Windows gaming on Linux.
- **What makes this different than adding persistent storage to a live CD with [Universal USB Installer or YUMI](https://www.pendrivelinux.com/)?**
    - Having persistent storage work via these hacky methods can be hit-or-miss depending on the distribution. winesapOS was built from the ground-up to have persistent storage. It also features automatic backups, various gaming tools, has support for Intel Macs, and more.
- **Are Arm Macs supported?**
    - No. We recommend using [Asahi ALARM](https://github.com/asahi-alarm/asahi-alarm) (Arch Linux), [Fedora Asahi Remix](https://asahilinux.org/fedora/) (recommended for the best support), or [Ubuntu Asahi](https://ubuntuasahi.org/) instead.
- **Is legacy PC hardware supported?**
    - No. If your PC is too old and winesapOS does not boot on it, we recommend to use [Slax](https://www.slax.org/) instead. Use the Slackware variant for x86 PCs and the Debian variant for x86_64 PCs.
- **Is winesapOS a Linux distribution?**
    - Yes. We provide customized packages, a package repository, various optimizations, and our own upgrade process. winesapOS is based on Arch Linux with optional support for Manjaro.
- **Do I have to install winesapOS?**
    - No. No installation is required. Flash a [release image](https://github.com/winesapOS/winesapOS/releases) to a drive and then boot from it. Everything is already installed and configured.
- **What if winesapOS was abandoned?**
    - We have no intentions on ever abandoning winesapOS. Even if that happened, since this is an opinionated installation of an Arch Linux distribution, it will continue to get normal operating system updates. The [uninstall](#uninstall) script can also be used to switch back to upstream Arch Linux.
- **Can anyone build winesapOS?**
    - Yes. Refer to the [CONTRIBUTING.md](CONTRIBUTING.md) documentation.
- **Can winesapOS be built with a different Linux distribution?**
    - Yes. We support Arch Linux and Manjaro as build targets. As of winesapOS 4, Arch Linux is the default target that is used for our releases.
- **Is winesapOS affiliated with Valve?**
    - No. We are an independent project.

## Contributors

Here are community contributors who have helped the winesapOS project.

**Founder:**

- [LukeShortCloud](https://github.com/LukeShortCloud)

**Code:**

- [Mohamed A. Said](https://github.com/SrcEngGuy)
- [mtkennerly](https://github.com/mtkennerly)
- [ohaiibuzzle](https://github.com/ohaiibuzzle)
- [soredake](https://github.com/soredake)
- [Thijzer](https://github.com/Thijzer)
- [wallentx](https://github.com/wallentx)

**Financial:**

- Companies:
    - [Intel](https://www.intel.com/) = Intel Optane drives for builds
- Individuals:
    - Mark Dougherty = Patreon
    - Mike Artz = Patreon

## History

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

## License

[GPLv3](LICENSE)

winesapOS

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README