OpenClaw-pterodactyl-wine-gui-egg/README.md

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_latest image.
• 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:

1. Start an Xvfb virtual display.
2. Create a D-Bus session.
3. Launch PulseAudio (if available).
4. Start an XFCE desktop environment.
5. Optionally start x11vnc.
6. Optionally start noVNC/websockify.
7. Initialize the Wine prefix (first launch only).
8. Hand execution back to the official Wine yolk.
9. 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:

1. Import egg-wine-desktop.json.
2. Select the Wine Desktop Docker image.
3. Create a server.
4. Allocate ports for VNC and/or noVNC if desired.
5. Upload your Windows application.
6. 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_EXECUTABLE points to the correct file.
• The application is compatible with Wine.

---

Wine prefix issues

The Wine prefix is persistent.

If it becomes corrupted:

1. Stop the server.
2. Back up .wine.
3. Delete or repair the prefix.
4. 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.