WinBoat - A Container-Based Windows VM

WinBoat Installation Guide

WinBoat enables seamless execution of Windows applications on Linux by using a containerized Windows VM with Docker and KVM. This guide describes the necessary prerequisites and the individual steps for installation.

Prerequisites

Before installing WinBoat, ensure your system meets the following requirements:

• RAM: At least 4 GB available for WinBoat
• CPU: At least 2 logical threads (cores)
• Storage: At least 32 GB of free space in the /var directory (40 GB recommended)
• Virtualization: KVM must be enabled in BIOS/UEFI and /dev/kvm must be accessible
• Docker Engine: Root Docker installed (Docker Desktop is not supported)
• Docker Compose v2: For compatibility with docker-compose files
• User in Docker Group: Your user must be in the group docker to use Docker without root privileges
• FreeRDP: Version 3.x with sound support installed, for RemoteApp window composition
• Kernel Modules: iptables and iptable_nat must be loaded and available

Step 1: Prepare the System

Enable KVM Virtualization

• Enable virtualization technology (Intel VT-x or AMD-V) in BIOS/UEFI.
• Check if virtualization is recognized by the kernel with this command:

egrep -c '(vmx|svm)' /proc/cpuinfo

The result should be greater than 0.

Install Docker Engine and Docker Compose v2

Debian/Ubuntu Example:

1
2

sudo apt update
sudo apt install -y docker.io docker-compose

Ensure Docker Compose v2 (possibly additional installation depending on distribution).

Add User to Docker Group

1
2

sudo usermod -aG docker $USER
newgrp docker # Abmelden und wieder anmelden ansonsten notwendig

Install FreeRDP

FreeRDP must be at least version 3. Debian Trixie has it officially included. Linux Mint, especially the LMDE 6 variant, does not! That is annoying but not hindering, as we simply install it ourselves.

Option 1: Add Repository (Debian/Ubuntu)

1. Add repository URL as a new source:

1

echo "deb [signed-by=/usr/share/keyrings/freerdp-archive-keyring.gpg] https://packages.freerdp.com/debian stable main" | sudo tee /etc/apt/sources.list.d/freerdp.list

2. Download and authorize GPG key modernly with curl and gpg --dearmor:

1
2

curl -fsSL https://packages.freerdp.com/debian/freerdp-archive-keyring.gpg | 
sudo tee /usr/share/keyrings/freerdp-archive-keyring.gpg > /dev/null

3. Update package list and install FreeRDP 3

1
2

sudo apt update
sudo apt install freerdp3 freerdp3-dev

Option 2: Compile FreeRDP 3 from Source Code

1. Install dependencies (example Debian):

1
2
3

sudo apt install build-essential cmake git pkg-config libssl-dev libx11-dev libxext-dev libxinerama-dev libxcursor-dev libxrandr-dev libxv-dev libxi-dev
libxfixes-dev libxdamage-dev libxkbfile-dev libxkbcommon-dev libxkbcommon-x11-dev libavutil-dev libavcodec-dev libswscale-dev libusb-1.0-0-dev libpulse-dev
liblog4cplus-dev libcunit1-dev libasound2-dev libfuse3-dev libwinpr-tools-dev

2. Clone and compile source code:

1
2
3
4
5
6

git clone https://github.com/FreeRDP/FreeRDP.git
cd FreeRDP
cmake -DCMAKE_BUILD_TYPE=Release -DWITH_PULSE=ON -DWITH_X11=ON -DWITH_SSE2=ON .
make -j$(nproc)
sudo make install
sudo ldconfig

Option 3: Use Flatpak (if available)

1

flatpak install flathub com.freerdp.FreeRDP

Step 3: Download and Run WinBoat

• Download the latest WinBoat AppImage from the official website:
  https://winboat.app

• Make the file executable and start the app:

1
2

chmod +x WinBoat-.AppImage
./WinBoat-.AppImage

Step 4: Set Up Windows VM and Install Windows

• WinBoat opens a graphical setup.
• Specify how much RAM, CPU cores, and disk storage the Windows VM should receive (e.g., 4 cores, 8 GB RAM).
• Select a Windows ISO (can be downloaded automatically or specified manually).
• Start the Windows installation within the VM.
• Follow the usual Windows installation steps.

Step 5: Use Windows Applications Seamlessly in Linux

• After installation, Windows runs as a VM inside the Docker container.
• WinBoat internally sets up a “Guest Server” that passes the list of Windows applications.
• Windows applications can then be opened as native windows on the Linux desktop.
• Integration of files and folders between Linux and Windows is handled automatically via mounted directories.

Additional Notes

• Installation may take between 30 minutes and 1.5 hours depending on internet speed and hardware.
• Docker Desktop, rootless Podman, or emulations are not supported and lead to problems.
• Kernel modules iptables and iptable_nat must be loaded, otherwise the VM’s network connection will not work.
• FreeRDP Version 3 is essential for window composition and sound integration.

Sources

• Official WinBoat Website: https://winboat.app
• GitHub Repository: https://github.com/TibixDev/winboat
• FreeRDP official page: https://www.freerdp.com
• Forum posts and installation discussions

This guide focuses on Debian-based systems (such as LMDE or Debian) but should also work on other Linux distributions with necessary adjustments.