How tibixdev/winboat works
1. Overall shape: WinBoat is a desktop application, not a service or web app. The runtime is split between an Electron shell on the Linux host, a Vue/TypeScript renderer UI, a Go-based Windows guest server, and the container runtime that hosts the Windows VM.
2. Host application boundary: src/main/main.ts is the Electron main-process entry point. Its role is to create the app window, load the renderer bundle, and act as the native desktop wrapper around the rest of the system.
3. Renderer/UI layer: src/renderer contains the full user-facing app: setup, home/dashboard, apps, configuration, migration, and about views. The UI uses Vue components plus shared styling/assets, with a small utility layer for events, logging, port handling, and window/desktop behaviors.
4. Application orchestration in the renderer: Most product logic lives in src/renderer/lib. This layer handles config, install/setup flows, migration, launching, and domain-specific helpers. It is the bridge between UI actions and the underlying host/guest infrastructure.
5. Container-runtime abstraction: WinBoat supports Docker and Podman through a shared container layer in src/renderer/lib/containers, with runtime-specific implementations for each. This is a key architectural boundary: the app does not directly manage a bare VM; it manages a Windows VM running inside a container.
6. VM/control plane: src/renderer/lib/qmp.ts indicates QEMU/QMP-based control of the VM lifecycle. The host app uses this channel to coordinate startup, status, and low-level VM operations separate from the UI and separate from the guest OS.
7. Windows guest agent: The guest_server/ directory is a separate Go project built for the Windows VM. It is installed and run as a Windows service using the provided scripts/tools, and it exposes guest-side capabilities such as system data, app management, icon retrieval, time sync, update-related actions, and secure key handling.
8. Remote desktop and app presentation: WinBoat uses FreeRDP and Windows RemoteApp to render Windows applications as native-looking Linux windows. The renderer’s container/app modules and helpers are responsible for discovering apps, launching them, and connecting the UI to the RDP session.
9. Device and file integration: The repository includes explicit support for USB handling (usbmanager.ts and data/usb.ids) and filesystem integration via the host/guest bridge. This is part of the “make Windows feel native” layer rather than a separate subsystem.
10. Configuration, install, and migration flow: First-run setup and subsequent upgrades are handled by dedicated flows in SetupUI, Migration, and related libraries. Configuration is a central piece of state that determines container runtime, VM resources, app exposure, and integration behavior.
11. Build and packaging boundary: The project is built with Bun/TypeScript for the Electron app and Go for the guest server. vite.config.ts, electron-builder.json, scripts/build.ts, and the GitHub release workflow define packaging into AppImage/deb/rpm/unpacked formats, while build-guest-server.sh produces the guest-side binary.
12. External dependencies that shape the architecture: The repo depends on Linux virtualization/container infrastructure (Docker or Podman, KVM, optionally iptables/nftables) and on a working FreeRDP 3.x install. These are not optional implementation details; they are core parts of the system boundary WinBoat sits on top of.
Main entry points: lib Orchestration · App.vue Renderer app · main.go Guest server · containers Container layer
Components 22
Linux host app
Electron shell and renderer running on the Linux desktop.
- Electron main · Creates the desktop window and loads the renderer bundle.
src/main/main.ts - Renderer app · Top-level Vue application and route composition for the desktop UI.
src/renderer/App.vue - App views · Setup, home, apps, config, migration, and about screens.
src/renderer/views - UI components · Reusable interface components and menus used across the app.
src/renderer/components - UI utilities · Shared event, logging, port, RDP, and browser/window helpers.
src/renderer/utils - Orchestration · Configuration, setup, install, migration, and launch coordination.
src/renderer/lib - WinBoat core · Central runtime state and high-level app coordination.
src/renderer/lib/winboat.ts - USB manager · USB device handling and host/guest passthrough integration.
src/renderer/lib/usbmanager.ts - Config flow · Central configuration model used by setup, runtime, and integration features.
src/renderer/lib/config.ts - Migration flow · Upgrade and state migration logic for existing installations.
src/renderer/lib/migrate.ts - Install flow · Initial provisioning and environment preparation logic.
src/renderer/lib/install.ts
Windows guest
Go service and scripts that run inside the Windows VM.
- Guest server · Windows-side agent exposing guest capabilities and integration endpoints.
guest_server/main.go - Guest scripts · PowerShell and batch scripts for apps, icons, time sync, and updates.
guest_server/scripts - Secure key · Guest-side secure key and auth helper logic.
guest_server/securekey.go - RemoteApp bridge · Windows app discovery and RemoteApp registration for FreeRDP presentation.
guest_server/RDPApps.reg
Container/VM runtime
Container and VM control boundaries used to host the guest.
- Container layer · Shared container-runtime interface for managing the Windows VM host.
src/renderer/lib/containers - Docker backend · Docker-specific container integration.
src/renderer/lib/containers/docker.ts - Podman backend · Podman-specific container integration.
src/renderer/lib/containers/podman.ts - QMP control · QEMU/QMP channel for VM lifecycle and low-level host control.
src/renderer/lib/qmp.ts
Build & packaging
Tooling and release pipeline for the desktop app and guest server.
- Build tooling · Bun/TypeScript build pipeline and app packaging configuration.
scripts/build.ts - Guest build · Build script for producing the Windows guest-server binary.
build-guest-server.sh - Release pipeline · GitHub Actions release automation for packaged desktop artifacts.
.github/workflows/release.yml
Connections 24
- Electron main → Renderer app: loads UI · Electron shell creates the desktop window and loads the renderer bundle.
- Renderer app → App views: routes to · Top-level app composes the product screens.
- Renderer app → UI components: renders · Views are built from reusable interface components.
- Renderer app → UI utilities: uses · The UI depends on shared helper utilities.
- App views → Orchestration: drives · User actions in setup, home, config, and migration flow into orchestration logic.
- Orchestration → Config flow: reads/writes · Configuration is the central state for runtime behavior and integrations.
- Orchestration → Install flow: bootstraps · Initial setup provisions the application environment.
- Orchestration → Migration flow: upgrades · Migration handles changes between installed versions.
- Orchestration → WinBoat core: coordinates · Product logic delegates shared runtime orchestration to the core state layer.
- WinBoat core → Container layer: uses · Core runtime control is built on the container abstraction.
- Container layer → Docker backend: backend · Docker is one supported container runtime.
- Container layer → Podman backend: backend · Podman is the other supported container runtime.
- WinBoat core → QMP control: controls VM · QMP provides lifecycle and low-level VM control.
- Container layer → Guest server: hosts · The container/VM environment runs the Windows guest agent.
- Guest server → Guest scripts: invokes · Guest-side capabilities are exposed through service scripts and tools.
- Guest server → Secure key: auth · Secure key logic protects guest-side interactions.
- Guest server → RemoteApp bridge: publishes · Guest app registration feeds RemoteApp presentation.
- Orchestration → USB manager: integrates · USB passthrough is managed as part of the host/guest bridge.
- Orchestration → UI utilities: uses · Orchestration reuses utility helpers for ports, events, and process handling.
- Build tooling → Electron main: packages · Build tooling bundles the Electron desktop app.
- Build tooling → Renderer app: bundles · Renderer code is compiled and packaged as part of the desktop app.
- Guest build → Guest server: builds · Shell build script produces the guest-server binary.
- Release pipeline → Build tooling: automates · CI release workflow drives app packaging and publishing.
- Release pipeline → Guest build: includes · Release automation includes the guest-server artifact.