> ## Documentation Index
> Fetch the complete documentation index at: https://docs.boat.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Windows Apps

> Run Windows-only desktop software in a sandbox with Wine, let an agent drive it, and fork the set-up machine.

<video controls playsInline preload="metadata" poster="/videos/windows-apps.jpg" src="https://mintcdn.com/ariana-1e97e6c3/ffLejs9iPR0iSVss/videos/windows-apps.mp4?fit=max&auto=format&n=ffLejs9iPR0iSVss&q=85&s=4fe763936ad348922ff57be6663d55dc" className="w-full aspect-video rounded-xl" data-path="videos/windows-apps.mp4" />

A sandbox runs Windows programs on its Linux desktop through [Wine](https://www.winehq.org). The programs open as normal windows on the [desktop stream](/desktop-streaming), so you can watch them and the sandbox's agents can click, type, and read them with the built-in [`computer` tools](/integrated-agents#computer-use). Install once, then [fork](/snapshots) the set-up sandbox as many times as you need.

## What we tested

Every app below ran on a Boat sandbox with the set-up on this page. "Extra step" lists what the app needs beyond that set-up.

| App | What it is | Extra step |
| - | - | - |
| Notepad++, HxD, WinMerge, Everything | Editors, hex, diff, file search | None |
| WinRAR, 7-Zip, WinDirStat | Archives, disk usage | None |
| HeidiSQL | Database client | None |
| Winamp, foobar2000, MPC-HC, IrfanView, FastStone, XnView | Media and image viewers | None |
| LTspice | Circuit simulator | None |
| FORScan | Car diagnostics | None |
| x64dbg | Debugger | None |
| Process Explorer, Autoruns | Microsoft Sysinternals | [Accept the licence first](#sysinternals) |
| MicroDicom, RadiAnt | Medical image (DICOM) viewers | RadiAnt asks you to start its free trial |
| Steam | Game store client | [Steam](#steam) |
| Paint.NET 5.2 | Image editor | [Paint.NET](#paintnet) |
| Spelunky, Cave Story | Games | None. Direct3D runs through DXVK. |
| ImgBurn | Disc image tool | None |

These did not work, and no set-up fixes them:

| App | Why |
| - | - |
| CPU-Z | Opens with a driver error. It loads a Windows kernel driver, and Wine cannot load kernel drivers. |
| Paint.NET 5.1 and older | Needs a Windows system file that Wine does not have. Use 5.2. |
| CCleaner | Starts, then opens no window. |
| SkiFree and other 16-bit Windows 3.1 programs | They run, but their emulator slows every other Wine window. Run them alone. |
| SketchUp Make 2017 | Discontinued. Trimble removed the download. |

## Install Wine

Run this script once inside the sandbox. It takes about 5 minutes. Send it with `boat ssh bx_f7k2q9hd 'bash -s' < install-wine.sh`, or pass it as the `command` of [`POST /sandboxes/{sandboxId}/commands`](/api/reference/agent/execute-sandbox-command) or the SDK `command` call with `detached: true`. Without `detached`, the command stops after its 30-second default timeout and leaves Wine half-installed. Poll the command status until it finishes.

```bash install-wine.sh theme={null}
set -e
sudo dpkg --add-architecture i386
sudo mkdir -pm755 /etc/apt/keyrings
sudo wget -qO /etc/apt/keyrings/winehq-archive.key https://dl.winehq.org/wine-builds/winehq.key
sudo wget -qNP /etc/apt/sources.list.d/ https://dl.winehq.org/wine-builds/ubuntu/dists/noble/winehq-noble.sources
printf 'Package: libgd3\nPin: release o=Ubuntu\nPin-Priority: 1001\n' | sudo tee /etc/apt/preferences.d/wine-libgd3
sudo apt-get update -qq
sudo DEBIAN_FRONTEND=noninteractive apt-get install -y -qq --allow-downgrades --no-install-recommends \
  winehq-staging mesa-vulkan-drivers mesa-vulkan-drivers:i386 cabextract p7zip-full
sudo wget -qO /usr/local/bin/winetricks https://raw.githubusercontent.com/Winetricks/winetricks/master/src/winetricks
sudo chmod +x /usr/local/bin/winetricks
export DISPLAY=:0
WINEDLLOVERRIDES="mscoree,mshtml=" wineboot -i
winetricks -q corefonts vcrun2022 dxvk d3dcompiler_47
wine --version
```

What each part does:

* **WineHQ staging.** Ubuntu's own Wine is version 9. Steam, Paint.NET 5.2, and Direct3D games need Wine 11 or newer.
* **The `libgd3` pin.** The sandbox ships a PHP repository whose `libgd3` exists only for 64-bit. 32-bit Wine needs the same version for both. The pin selects Ubuntu's version. PHP's `gd` extension is removed as a side effect.
* **`mesa-vulkan-drivers`.** A sandbox has no GPU. This software Vulkan driver lets DXVK run Direct3D 8 to 11 on the CPU.
* **`WINEDLLOVERRIDES="mscoree,mshtml="`.** A new Wine set-up opens a "Wine Mono Installer" window and waits for a click. This skips it. Apps that need .NET get Microsoft's runtime from winetricks instead.
* **winetricks.** Installs Microsoft's free redistributables: core fonts, the Visual C++ 2015 to 2022 runtime, DXVK, and the Direct3D shader compiler.

## Run an app

Download the official installer or portable archive in the sandbox, install it, and start it on the desktop. Every GUI command needs `DISPLAY=:0`. This example installs the MicroDicom medical image viewer and opens a CT scan:

```bash theme={null}
export DISPLAY=:0
curl -fsSL -o /tmp/microdicom.exe https://www.microdicom.com/downloads/Software/MicroDicom-2026.4-Setup.exe
wine /tmp/microdicom.exe /S
curl -fsSL -o ~/CT_small.dcm https://github.com/pydicom/pydicom/raw/main/src/pydicom/data/test_files/CT_small.dcm
cd "$HOME/.wine/drive_c/Program Files/MicroDicom"
wine mDicom.exe 'Z:\home\user\CT_small.dcm' &
```

On the first start, MicroDicom asks to become the default viewer and does not open the file. Press Escape, close MicroDicom, and run the last command again. From then on, the scan opens at once.

* Use `wine start /unix <path>` to start a program. Programs written in Python (Blender, FreeCAD) and many others crash without it, because `start` gives them normal Windows console handles.
* Most installers have a silent switch: `/S` (NSIS), `/VERYSILENT` (Inno Setup), `msiexec /i app.msi /qn` (MSI).
* To find an official download link, open the app's manifest in [winget-pkgs](https://github.com/microsoft/winget-pkgs/tree/master/manifests). The `InstallerUrl` field is the vendor's own link.
* Windows paths map to Linux paths: `C:\` is `~/.wine/drive_c`, and `Z:\` is the Linux root `/`.

## Recipes for harder apps

### Steam

Steam needs the Arial font and must not use Wine's DirectWrite. Its web view must not use a GPU.

```bash theme={null}
export DISPLAY=:0
winetricks -q arial
wine reg add 'HKCU\Software\Wine\AppDefaults\steam.exe\DllOverrides' /v dwrite /t REG_SZ /d '' /f
curl -fsSL -o /tmp/SteamSetup.exe https://cdn.cloudflare.steamstatic.com/client/installer/SteamSetup.exe
wine /tmp/SteamSetup.exe /S
wine start 'C:\Program Files (x86)\Steam\steam.exe' -no-dwrite -cef-disable-gpu -cef-disable-sandbox
```

The first start updates Steam and takes about 2 minutes. Then the sign-in window opens.

### Paint.NET

Paint.NET 5.2 ships a separate [build for Wine](https://github.com/paintdotnet/Paint.NET-on-Wine). It needs Wine 11.15 or newer, which the set-up above installs. Its installer makes its own Wine set-up and needs Wine Mono, so it opens the "Wine Mono Installer" window. The `xdotool` loop presses **Install** for you.

```bash theme={null}
export DISPLAY=:0
mkdir -p ~/apps/paintnet && cd ~/apps/paintnet
curl -fsSL -o pdn.zip "$(curl -s https://api.github.com/repos/paintdotnet/Paint.NET-on-Wine/releases \
  | grep -o '"browser_download_url": *"[^"]*x64[^"]*\.zip"' | cut -d'"' -f4 | head -1)"
unzip -q pdn.zip
( for i in $(seq 1 120); do
    w=$(wmctrl -l | grep 'Wine Mono Installer' | awk '{print $1}')
    [ -n "$w" ] && { wmctrl -i -a $w; sleep 0.5; xdotool key Return; break; }
    sleep 2
  done ) &
./install.sh
./paintdotnet.sh &
```

Pick the `x64` file. The release also has an `arm64` file that does not run on a sandbox. The Wine build is experimental and expires 12 weeks after its build date. Download a new one when it expires. Paint.NET 5.1 and older do not run.

### Sysinternals

Process Explorer and Autoruns show a licence window on the first start. Accept it ahead of time so an agent does not have to. Autoruns rejects the `/accepteula` flag, so set the registry value for both:

```bash theme={null}
export DISPLAY=:0
curl -fsSL -o /tmp/procexp.zip https://download.sysinternals.com/files/ProcessExplorer.zip
curl -fsSL -o /tmp/autoruns.zip https://download.sysinternals.com/files/Autoruns.zip
mkdir -p ~/apps/sysinternals && cd ~/apps/sysinternals
unzip -qo /tmp/procexp.zip && unzip -qo /tmp/autoruns.zip
wine reg add 'HKCU\Software\Sysinternals\Process Explorer' /v EulaAccepted /t REG_DWORD /d 1 /f
wine reg add 'HKCU\Software\Sysinternals\Autoruns' /v EulaAccepted /t REG_DWORD /d 1 /f
wine start /unix ~/apps/sysinternals/procexp64.exe
```

### Direct3D games

DXVK from the set-up runs Direct3D 8, 9, 10, and 11 games on the software Vulkan driver. Simple 2D and older 3D games run at playable speed. Modern 3D games are too slow without a GPU.

Old games that switch the screen resolution can leave a full-screen window over the desktop. Stop Wine from changing the resolution:

```bash theme={null}
wine reg add 'HKCU\Software\Wine\X11 Driver' /v UseXRandR /t REG_SZ /d N /f
wine reg add 'HKCU\Software\Wine\X11 Driver' /v UseXVidMode /t REG_SZ /d N /f
```

## Let an agent drive it

The Windows windows are ordinary windows on the sandbox desktop. A prompt is enough:

<CodeGroup>
  ```bash CLI theme={null}
  boat prompt bx_f7k2q9hd --provider claude "Open HeidiSQL, connect to the MySQL server on localhost, and export the users table to CSV"
  ```

  ```bash curl theme={null}
  curl -sS -X POST "$BOAT_API_BASE/sandboxes/bx_f7k2q9hd/prompt" \
    -H "Authorization: Bearer $BOAT_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"provider":"claude","prompt":"Open HeidiSQL, connect to the MySQL server on localhost, and export the users table to CSV"}'
  ```

  ```ts TypeScript theme={null}
  await sandbox.prompt({
    sandboxId: "bx_f7k2q9hd",
    provider: "claude",
    prompt: "Open HeidiSQL, connect to the MySQL server on localhost, and export the users table to CSV",
  });
  ```

  ```python Python theme={null}
  sandbox.prompt("bx_f7k2q9hd", PromptRequest(
      provider="claude",
      prompt="Open HeidiSQL, connect to the MySQL server on localhost, and export the users table to CSV",
  ))
  ```
</CodeGroup>

For scripted steps, `xdotool` and `wmctrl` are installed. For example, `wmctrl -l` lists the open windows and `wmctrl -a HeidiSQL` brings one to the front. Record the run with [`ascii-record-desktop`](/desktop-streaming#record-what-happens-on-screen).

## Set up once, fork many times

The Wine set-up lives in `~/.wine` and the system packages. Stop, resume, and fork keep both. In our test, a sandbox with Wine and 40 Windows apps (16 GB) did this:

| Action | Time | Result |
| - | - | - |
| Fork | about 2 minutes until the desktop accepts windows | Every app starts. Notepad++ keeps its unsaved text. |
| Stop | 4 seconds | |
| Resume | 20 to 32 seconds, on a different host | Every app starts. |

Make one sandbox with the apps your agents need, then fork it for each task. See [Snapshots & Copies](/snapshots). Running Windows programs do not survive a stop or a fork. Start them again after a resume.

## Troubleshooting

| Symptom | Cause | Fix |
| - | - | - |
| `apt-get` says `libgd3:i386` "is not going to be installed" | The PHP repository's `libgd3` | Add the `libgd3` pin from [Install Wine](#install-wine) |
| `wineboot` never finishes | The "Wine Mono Installer" window waits for a click | `WINEDLLOVERRIDES="mscoree,mshtml=" wineboot -i` |
| `Cannot open display` | The command does not know the desktop | `export DISPLAY=:0` |
| A Python-based app exits at once with `init_sys_streams` | No Windows console handles | Start it with `wine start /unix` |
| `unimplemented function msvcp140.dll...` | Old Visual C++ runtime | `winetricks -q vcrun2022` |
| Windows go blank and show "Not Responding" | A window was closed from Linux with `wmctrl -c` or the title bar while it held a modal dialog | Answer dialogs with keys (`xdotool key Return`). Do not close them from outside. |
| Every Wine window is slow | A 16-bit Windows 3.1 program is running. Its emulator keeps Wine busy. | Close it. Run 16-bit programs on their own. |
| A game covers the whole desktop | It changed the screen resolution | Set `UseXRandR` and `UseXVidMode` to `N`, see [Direct3D games](#direct3d-games) |

## Licences

Install only software you have the right to use. Download it from the vendor, as on this page. Do not copy Windows system files into Wine: Microsoft's licence does not allow it, and Wine does not need them for the apps above. The winetricks components on this page are Microsoft's free redistributables.

## Related

* [Desktop Streaming](/desktop-streaming)
* [Computer use](/integrated-agents#computer-use)
* [Snapshots & Copies](/snapshots)
* [Long-Running Tasks](/long-running-tasks)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.