DHIVA LABS · LEARN

Appearance

Use the Windows VM for apps and USB devices ​

The Windows VM that builds Flutter apps can do two more jobs: show an app that Wine cannot run as a window on your Linux desktop, and take over a USB device that needs Windows-only software.

Both need the VM from Build Flutter apps on a Windows VM set up first.

When to use the VM instead of Wine ​

Try winbridge run first. It needs no VM and starts faster.

Some software does not run under Wine: tools that depend on a Windows driver, or apps that lean on parts of Windows that Wine does not provide. With winbridge vm app, the program runs on real Windows inside the VM, and only its window, the clipboard and optionally its sound come across to Linux.

Show a VM app as a window ​

winbridge vm app starts a FreeRDP client in RemoteApp mode. FreeRDP is an open-source client for Remote Desktop (RDP), the protocol Windows uses to show its screen on another computer. RemoteApp mode shows one program's window instead of the whole desktop.

WARNING

The WinBridge project describes this feature as not verified end to end: its tests check the command it builds, not a real session. Expect to do some troubleshooting, and read the limits below before you start.

  1. Install a FreeRDP client on Linux. On Debian and Ubuntu:

    bash
    sudo apt install freerdp3-x11

    On an older release the package is freerdp2-x11. WinBridge looks for xfreerdp, xfreerdp3, wlfreerdp and sdl-freerdp, in that order.

  2. Install the Windows program inside the VM, through the VM's web console or a Remote Desktop session. winbridge vm app starts software that is already there; it does not install anything.

  3. Install it to a path without spaces, for example C:\apps\App. Paths with spaces, including anything under C:\Program Files, are rejected.

  4. Start it from Linux, writing the path with forward slashes.

    bash
    winbridge vm app "C:/apps/App/app.exe"

    Add --sound to hear the app's audio on your Linux machine.

Limits in version 0.4.0 ​

  • No password prompt. WinBridge never puts a password on a command line and cannot pass one typed at the keyboard to FreeRDP. vm app works only when FreeRDP can sign in without asking: an account without a password, or credentials FreeRDP already has. Otherwise run the FreeRDP client yourself.
  • The port comes from vm.json. vm app connects to the host, port and user in your VM config. That port is normally the SSH port, while Remote Desktop listens on its own port (3389 by default). If the two differ on your setup, keep a second config file whose port is the Remote Desktop port and select it for this command with the WINBRIDGE_VM_CONFIG environment variable.
  • Certificates are trusted on first use. The first certificate the VM presents is accepted and remembered. A certificate that later changes is flagged. There is no option to change this.
  • A clean exit is not proof. Exit code 0 means FreeRDP connected and ran the command. The first time you try an app, check in the VM that it really opened.
  • No launcher entry. winbridge desktop add is for apps run through Wine, not for VM apps.

Hand a USB device to the VM ​

Passthrough gives the VM direct control of one USB device, as if it were plugged into the Windows machine. This is for hardware whose setup or maintenance tool exists only for Windows.

Most hardware works on Linux natively. Check that first.

  1. List the USB devices on your machine. This needs the lsusb command (the usbutils package).

    bash
    winbridge vm usb list

    The first column, VENDOR:PRODUCT, is the device's ID, two groups of four characters such as 1462:7c95. Hubs are hidden; add --all to include them.

  2. Ask WinBridge for the VM configuration for that device.

    bash
    winbridge vm usb passthrough 1462:7c95

  3. Apply the printed configuration yourself. WinBridge prints two versions and changes nothing:

    • a fragment for the Docker Compose file used in the Flutter VM guide. After editing the file, recreate the container with docker compose up -d --force-recreate.
    • an XML fragment and a virsh command for a VM managed by libvirt.

  4. Install the vendor's driver inside the VM, as on any Windows PC.

Good to know

While a device is passed through, Windows in the VM controls it. A USB 3 device attached to a VM with a USB 2 virtual controller runs at USB 2 speed.

Next steps ​