6.2 KiB
Wine Desktop
Wine Desktop is a Docker image and Pterodactyl/Pelican Egg that enables Windows desktop applications to run inside a fully featured Linux desktop environment powered by Wine.
Unlike the official Wine yolk, which is primarily intended for command-line or dedicated server applications, Wine Desktop provides a persistent virtual XFCE desktop running on Xvfb, allowing graphical Windows software to run as if it were on a normal desktop system. Applications can be accessed remotely through a traditional VNC client or directly from a web browser using noVNC.
The project was originally developed while bringing OpenClaw to Pterodactyl, but it is completely application-agnostic. It can be used for virtually any Windows program that runs under Wine, including launchers, editors, utilities, game tools, and other GUI applications.
Features
- Based on the official
ghcr.io/ptero-eggs/yolks:wine_latestimage. - Persistent virtual XFCE desktop.
- Hardware-independent X11 desktop powered by Xvfb.
- Optional direct VNC access.
- Optional browser-based noVNC access.
- Persistent Wine prefix stored inside the server volume.
- Built-in PulseAudio support.
- Mesa OpenGL libraries for hardware-independent rendering.
- Includes Winetricks, Gecko, Mono, Winbind, common fonts, and archive utilities.
- Preserves the official Wine yolk's startup behavior, SteamCMD support, Winetricks integration, and automatic dependency handling.
How it works
When the container starts, Wine Desktop prepares a complete graphical Linux session before your application launches.
The startup sequence is:
- Start an Xvfb virtual display.
- Create a D-Bus session.
- Launch PulseAudio (if available).
- Start an XFCE desktop environment.
- Optionally start x11vnc.
- Optionally start noVNC/websockify.
- Initialize the Wine prefix (first launch only).
- Hand execution back to the official Wine yolk.
- Launch your Windows application using the Egg startup command.
Because the original Pterodactyl Wine entrypoint is still used, all existing functionality—including Steam updates, Winetricks installation, Gecko/Mono installation, and startup handling—continues to work exactly as expected.
Why this exists
Many Windows applications require a graphical desktop even if they are ultimately managed through Pterodactyl.
Examples include:
- Game launchers
- Dedicated server tools
- Level editors
- Configuration utilities
- Asset management software
- Legacy Windows applications
- Programs that require an interactive desktop
Wine Desktop makes these applications feel much closer to running on a normal Windows machine while still benefiting from containerization and Pterodactyl's management features.
Installation
Clone the repository:
git clone https://git.lexian.dev/Lexian-droid/OpenClaw-pterodactyl-wine-gui-egg.git WineDesktop
cd WineDesktop
Build the image:
docker build -t wine-desktop:latest .
If running directly with Docker:
docker run \
--rm \
-it \
-p 5900:5900 \
-p 6080:6080 \
-e STARTUP="wine /home/container/application.exe" \
wine-desktop:latest
For Pterodactyl or Pelican:
- Import
egg-wine-desktop.json. - Select the Wine Desktop Docker image.
- Create a server.
- Allocate ports for VNC and/or noVNC if desired.
- Upload your Windows application.
- Start the server.
Configuration
Startup
The default startup command is:
wine {{SERVER_EXECUTABLE}}
By default:
SERVER_EXECUTABLE=application.exe
You can change this to any executable inside /home/container.
Examples:
Launcher.exe
Game/Server.exe
Tools/Editor.exe
Environment Variables
| Variable | Default | Description |
|---|---|---|
| SERVER_EXECUTABLE | application.exe | Windows executable to launch |
| DISPLAY_WIDTH | 1280 | Desktop width |
| DISPLAY_HEIGHT | 720 | Desktop height |
| DISPLAY_DEPTH | 24 | Color depth |
| WINEPREFIX | /home/container/.wine | Persistent Wine installation |
| ENABLE_VNC | true | Enable x11vnc |
| ENABLE_NOVNC | true | Enable browser-based noVNC |
| VNC_PORT | 5900 | x11vnc listening port |
| NOVNC_PORT | 6080 | noVNC listening port |
| VNC_PASSWORD | (blank) | Optional VNC password |
| WINEDEBUG | -all | Wine debug output |
| WINEDLLOVERRIDES | (blank) | DLL overrides |
| LANG | en_US.UTF-8 | Locale |
| TZ | UTC | Container timezone |
Connecting
VNC
Connect using any VNC client to:
SERVER_IP:5900
If a password is configured, enter the value of VNC_PASSWORD.
noVNC
Open your browser:
http://SERVER_IP:6080/vnc.html
The browser interface connects to the running desktop without requiring a standalone VNC client.
Troubleshooting
Black screen
Check:
/tmp/wine-desktop-xfce.log/tmp/wine-desktop-x11vnc.log
Application will not start
Verify:
- The executable exists.
SERVER_EXECUTABLEpoints to the correct file.- The application is compatible with Wine.
Wine prefix issues
The Wine prefix is persistent.
If it becomes corrupted:
- Stop the server.
- Back up
.wine. - Delete or repair the prefix.
- Restart the server.
noVNC won't connect
Verify:
- VNC is enabled.
- noVNC is enabled.
- Port 5900 is reachable internally.
- Port 6080 is allocated externally.
FAQ
Is this a replacement for the official Wine yolk?
No.
Wine Desktop extends the official Wine yolk while preserving its startup behavior and update mechanisms.
Does this only work with OpenClaw?
No.
OpenClaw was simply the application used during development and testing.
Wine Desktop is designed to run any Windows GUI application that works under Wine.
Can I disable VNC?
Yes.
Set:
ENABLE_VNC=false
Can I disable noVNC?
Yes.
Set:
ENABLE_NOVNC=false
When VNC is disabled, noVNC is automatically disabled as well.
Is the Wine prefix persistent?
Yes.
The Wine prefix is stored inside your server's data volume and survives restarts and container rebuilds.
License
This project is licensed under the MIT License.
Wine Desktop builds upon the official Pterodactyl Wine yolk. All third-party software included in the image remains subject to its respective licenses.