feat: add desktop shortcuts for Windows applications #417

enXov · 2025-10-26T10:44:14Z

Overview

Implements Linux desktop shortcuts (.desktop files) for Windows applications, allowing users to launch apps directly from their desktop environment (GNOME, KDE, etc.).

Closes #121

What's New

Context Menu Integration: Right-click any app → "Add/Remove Shortcut"
Smart Executable Detection: Auto-detects WinBoat location, prompts user if not found
Loading Overlay: Shows progress when launching apps from shortcuts (Start Container → Wait → Launch)
Reactive UI: Shortcut badges update immediately, persist across navigation
Single-Instance Fix: Second instances exit silently without error dialogs

Technical Details

Creates .desktop files in ~/.local/share/applications/
Stores app icons in ~/.local/share/winboat/icons/
Uses --launch-app="AppName" format for IPC communication
Config persistence for executable path and shortcut list
Port manager integration for dynamic port handling

Known Limitations

Loading overlay uses 3-second static delay (could be made dynamic by detecting RDP window appearance)

Testing

Tested with:

Container running and stopped states
Dev mode (npm run dev) and production builds
KDE launcher integration

Note: I want everyone who sees this pull request to test these changes. Yes, I tested them and everything works fine for me, but that doesn't mean it will work fine for everyone.

Implement Linux .desktop file integration allowing users to launch Windows apps directly from their desktop environment. - Add context menu option to create/remove shortcuts - Auto-detect WinBoat executable location with user fallback - Display loading overlay during app launch from shortcuts - Fix single-instance lock to prevent duplicate instance dialogs - Add reactive shortcut badges in Apps view Closes TibixDev#121

enXov · 2025-10-26T11:24:36Z

output.webm

If I were to talk about the video in a moment,

as I mentioned earlier, the loading bars are currently static for one second and then close immediately.

Normally, when you click to create a shortcut, it searches for where WinBoat is installed, and if it can't find it, it asks you. However, since I run WinBoat with npm run dev, it automatically switches to the dev-swapper.sh file.

info Using custom WinBoat executable from config: /home/enxov/.local/bin/winboat-dev-wrapper.sh

You can find all the detailed logs in the console.

If you have any other questions, feel free to ask. I'll try to answer them all because this is really a huge update 😭

svein298 · 2025-11-26T20:40:17Z

Skärmsändning_20251124_220430.webm
it do not work on Debian 13

Levev · 2025-12-01T10:58:55Z

src/main/main.ts

+    // Another instance is already running, exit silently
+    // The second-instance handler in the first instance will receive our command line args
+    app.quit();


We should still display the dialog in case WinBoat wasn't invoked with the --launch-app argument

Updated the single-instance lock logic to only exit silently when launched with --launch-app-name or --launch-app-path flags. Otherwise, shows an error dialog informing the user that WinBoat is already running.

Levev · 2025-12-01T11:07:10Z

src/main/main.ts

+
+        // Check if we're launching an app from a desktop shortcut
+        // Look for --launch-app=AppName format to avoid conflicts with Electron's internal flags
+        const launchAppArg = commandLine.find(arg => arg.startsWith("--launch-app="));


We should come up with a way that lets us launch a program by both it's name and path, as migrating later on will be hard.

Something like --launch-app-name or --launch-app-path could work, but can be confusing

Or we could also go with a launch subcommand, accepting either a --path or --name

Implemented support for launching apps by both name and path:

--launch-app-name="AppName" - Launch by application name (used by shortcuts)

--launch-app-path="C:\path\to\app.exe" - Launch by executable path (future feature)
This provides flexibility for future enhancements while keeping the current implementation simple. Desktop shortcuts currently use --launch-app-name.

Levev · 2025-12-01T11:22:10Z

src/main/main.ts

 let mainWindow: BrowserWindow | null = null;

-function createWindow() {
-    if (!app.requestSingleInstanceLock()) {


If not present, we need to store the realpath of the current argv[0] (or the ARGV0 envvar if it exists) somewhere, so later on we can invoke WinBoat through that path.

WinBoat isn't guaranteed to be present in PATH, so this will solve us a lot of headache later on.

WinBoat now stores the realpath of its executable (argv[0] or ARGV0 env var) on startup in the electron-store config. This ensures desktop shortcuts can invoke WinBoat even when it's not in PATH.

The path is resolved using fs.promises.realpath() to handle symlinks correctly.

@Levev

- Fix single-instance lock to show dialog when not launched with app flags - Add support for dual launch methods: --launch-app-name and --launch-app-path - Store WinBoat executable realpath on startup for reliable invocation Addresses review comments from @Levev: 1. Single instance now only exits silently when invoked with launch flags 2. Implemented --launch-app-name and --launch-app-path for future flexibility 3. Store argv[0] realpath to ensure shortcuts work without PATH dependency

enXov · 2025-12-01T15:14:03Z

im still dont test these btw somehow my winboat is broken and have to reinstall i think

…ST_API_PORT

enXov · 2025-12-02T06:22:25Z

conflict resolved, merged with main, and that fix needs to be otherwise its giving just gray screen

…esolution for desktop shortcuts

enXov · 2025-12-02T07:05:08Z

and these fixes needs to be first one is resolve the 'npm run dev' issue, if you run the winboat with 'npm run dev' its somehow open the original winboat not dev-wrapper. Second one is resolve the loading issues, again somehow if you open a program from shortcuts its stuck on messagebox loading bar. Its very hard to resolve bug/fixes 1 month old pr 😭

enXov · 2025-12-02T07:25:33Z

all works good on cachy os plasma desktop(kde)

but bear in mind before merge with main. Loading overlay uses 3-second static delay (could be made dynamic by detecting RDP window appearance). And maybe add that desktopshortcuts info in cached apps because the if a app have shortcut the icon loading lately

Kunstbanause · 2025-12-03T16:39:35Z

I build the pr locally, right click to shortcut works, but when I run a shortcut I got hit with the "Please start Winboat in development mode first (npm run dev) " as a toast popup in fedora42 kde plasma. I tried npm run dev and also the appImage in the ditr directory.

No output in the log.

Any tipps?

enXov · 2025-12-03T17:28:27Z

I build the pr locally, right click to shortcut works, but when I run a shortcut I got hit with the "Please start Winboat in development mode first (npm run dev) " as a toast popup in fedora42 kde plasma. I tried npm run dev and also the appImage in the ditr directory.

No output in the log.

Any tipps?

thanks for trying! the latest should be fix but i dont sure, can you try that one? have to recreate shortcut btw

Kunstbanause · 2025-12-04T08:28:59Z

Works with the fix: 637d68f

Winboat needs to run from npm run dev though. The shortcut did not work when no winboat or appimage winboat was running

enXov · 2025-12-04T09:11:51Z

Works with the fix: 637d68f

Winboat needs to run from npm run dev though. The shortcut did not work when no winboat or appimage winboat was running

Thanks! is theres any log? should be log the winboat from... here

Kunstbanause · 2025-12-05T18:58:53Z

Thanks! is theres any log? should be log the winboat from...

I have a log from the npm run dev build, started in vs code's terminal, but I don't know where the log would be, when it fails to start after using the short-cuts with winboat NOT running beforehand or even the AppImage running. Any idea?

enXov · 2025-12-06T08:34:46Z

Thanks! is theres any log? should be log the winboat from...

I have a log from the npm run dev build, started in vs code's terminal, but I don't know where the log would be, when it fails to start after using the short-cuts with winboat NOT running beforehand or even the AppImage running. Any idea?

Thanks for the feedback and the screenshot showing the log location (~/.winboat/winboat.log)!

This behavior is by design for development mode. When running via npm run dev, the shortcuts use a wrapper script that requires Winboat to already be running. This is because in dev mode, we can't easily spawn a full npm run dev process from a shortcut - it needs the Vite dev server running.

For production/AppImage users: The shortcuts should work independently - they should start Winboat from the AppImage if it's not running. Could you confirm:

When you created the shortcuts, were you running the AppImage or npm run dev?
Can you check the .desktop file content (in /.local/share/applications/) to see what executable path it points to?
If the shortcut was created while running npm run dev, it will point to the dev wrapper (/.local/bin/winboat-dev-wrapper.sh). You'll need to delete and recreate the shortcuts while running the AppImage for them to work standalone.

The log file at ~/.winboat/winboat.log should help debug production mode issues if the AppImage shortcuts aren't working.

Previously, shortcuts would incorrectly use the dev wrapper script when either app.isPackaged was false OR NODE_ENV was 'development'. This caused shortcuts to fail in unpacked production builds. Now both conditions must be true for dev mode, and saved dev wrapper paths are ignored when running in production mode.

enXov · 2025-12-06T09:34:25Z

Sorry about that! My previous explanation was theoretically correct, but there was actually a bug in the code XD

The issue was in the dev mode detection logic - it was using || (OR) instead of && (AND):

// Before (buggy):
if (!app.isPackaged || process.env.NODE_ENV === "development")
// After (fixed):
if (!app.isPackaged && process.env.NODE_ENV === "development")

This meant shortcuts would incorrectly use the dev wrapper whenever either condition was true, instead of only when both are true.

I've pushed a fix now. Could you please:

Pull the latest changes and rebuild
Delete the existing shortcuts
Recreate them from the production build
They should now work independently without requiring Winboat to already be running. Let me know if it works!

Kunstbanause · 2025-12-06T15:56:53Z

When winboat is not running:

Log file has no messages from the time the shortcut was used (makes sense, since winboat does not seem to start at all)

I manually changed the .desktop shortcut with the KDE Menu Editor to point to the app image, then it works as I would have expected (starts winboat, runs the app)

enXov · 2025-12-06T16:01:59Z

thanks for testing but interesting, i check all types of winboat(npm run dev, appimage, unpacked) all of them working, what you change from desktop file?

why shortcuts try to find program on /tmp/ you install winboat there?

Kunstbanause · 2025-12-06T16:09:39Z

Could very well be user error on my side. Here again what I did:

Switch to your branch
Build the guest server, build winboat
Start the app image and remove the old short cuts
restart pc
Start the app image and create shortcut
Close winboat
Press the shortcut -> doesn't work!
edit the shortcut (.desktop file) to point to the right application (that is: the appimage instead of the /.mount stuff)
Use shortcut -> works well

enXov · 2025-12-06T16:12:05Z

thansk! somehow on your side try to find program on /tmp/.mount hmmm thanks! lemme quick look now

enXov · 2025-12-06T16:20:48Z

okay thanks for your amazing testing, i understand the problem the problem was:

i run the appimage with:

./winboat-0.9.0-x86_64.AppImage --appimage-extract
./squashfs-root/AppRun

because appimages requires a kind of tool named 'fuse' and i dont want to intsall it and run it from ^ commands, but you probably run the appimage normally

When running from an AppImage, the app was using the temporary mount path (e.g., /tmp/.mount_winboa*/winboat) for desktop shortcuts. This path becomes invalid after the AppImage is closed, causing shortcuts to fail. Now the code checks for the APPIMAGE environment variable first, which contains the actual AppImage file path. This ensures shortcuts work even after Winboat is closed and reopened. Fixes issue where shortcuts would show 'Could not find the program' error on systems running AppImage directly (e.g., Fedora with KDE).

enXov · 2025-12-06T16:27:05Z

that should be 100% working,

can you test now???

Kaan88 · 2025-12-14T07:19:51Z

Works great, this was much needed after switching from WinApps.
I edited the PKGBUILD to include this PR and ran it right after installing. Shortcuts were created successfully, and apps launch without any issues.
Do you plan to add support for launching files directly from the home directory with Windows apps?

enXov · 2025-12-14T11:15:13Z

Thank you very much for testing it—I’m glad to hear it works well for you. As for your question, that would indeed be a very nice feature to have; however, in my opinion, it isn’t directly related to this PR. So if you post this idea as a suggestion in the Issues section, I’m sure there will be people who will work on it in the future.

right click a .docx file => open with => winboat(word or whatever) => should be word opened with file in winboat

Kaan88 · 2025-12-14T11:23:09Z

right click a .docx file => open with => winboat(word or whatever) => should be word opened with file in winboat

You only wrote that as a suggestion, right? Currently that does not work.

enXov · 2025-12-14T11:32:03Z

right click a .docx file => open with => winboat(word or whatever) => should be word opened with file in winboat

You only wrote that as a suggestion, right? Currently that does not work.

Yes i write that as a suggestions, like a summary of what you want. But again its really good future

Kaan88 · 2025-12-14T12:09:12Z

Found an issue.

If the container is paused, shortcuts can't unpause it. However, everything works fine if the container is stopped instead of paused.

I think this log makes it pretty clear why.

2025-12-14 12:06:45 | INFO | Starting WinBoat container...
2025-12-14 12:06:45 | ERROR | There was an error performing the container action.
2025-12-14 12:06:45 | ERROR | Error: Command failed: docker container start WinBoat
Error response from daemon: cannot start a paused container, try unpause instead

enXov · 2025-12-14T13:36:03Z

Thank you very much (if you hadn’t mentioned it, I wouldn’t have known there was such a thing as “pause” XD)

TDS700 · 2025-12-23T16:33:34Z

This works great and is a really handy feature to start apps from terminal
Flags like: --launch-app-name="Notepad" or using a path seem to have no issues.
Im curious if theres a way to start a whole "Windows Desktop" thing.
In apps tab of winboat gui i can see that windows desktop uses "WINDOWS_DESKTOP" path however --launch-app-path="WINDOWS_DESKTOP" doesnt seem to start it and just launches winboat gui. I know its not a regular windows application but if there was a way to launch it from terminal id appreciate it.

This enables launching apps by path from terminal, including internal apps like WINDOWS_DESKTOP. Previously, --launch-app-path flag was ignored because there was no IPC handler for it in the renderer. Fixes launching WINDOWS_DESKTOP from terminal via: --launch-app-path="WINDOWS_DESKTOP"

enXov · 2025-12-24T09:32:58Z

@TDS700 should be fix, can you try again, thanks

enXov mentioned this pull request Oct 28, 2025

Linux shortcut support and related changes #430

Open

bloopybae mentioned this pull request Oct 28, 2025

[Feature] Apps tab: a quicker and simpler access to daily used apps #435

Open

2 tasks

senekor mentioned this pull request Nov 15, 2025

[Feature] A command to start apps directly through the CLI #225

Open

2 tasks

baseely mentioned this pull request Nov 28, 2025

[Feature] App shortcuts in Linux application launcher #121

Open

2 tasks

Levev requested changes Dec 1, 2025

View reviewed changes

enXov force-pushed the feat/add-shortcuts branch from 67490cb to 6392dde Compare December 1, 2025 14:49

style: format code with prettier

f16fa53

enXov added 2 commits December 2, 2025 05:40

Merge branch 'main' into feat/add-shortcuts

d6a55cf

fix: resolve build errors by exporting ContainerStatus and adding GUE…

bcc1f7f

…ST_API_PORT

enXov added 2 commits December 2, 2025 10:00

refactor: Extract dev wrapper creation and simplify executable path r…

eb8399c

…esolution for desktop shortcuts

fix: run app from shortcuts loading issue

cdcbeed

fix: pgrep check winboat running

637d68f

fix: container pause

7042392

MuhammadUsamaMX mentioned this pull request Dec 21, 2025

Add CLI Support and Desktop Integration for Windows Applications #593

Open

Uh oh!

feat: add desktop shortcuts for Windows applications #417

Are you sure you want to change the base?

feat: add desktop shortcuts for Windows applications #417

Uh oh!

Conversation

enXov commented Oct 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Overview

What's New

Technical Details

Known Limitations

Testing

Uh oh!

enXov commented Oct 26, 2025

Uh oh!

svein298 commented Nov 26, 2025

Uh oh!

Levev Dec 1, 2025

Choose a reason for hiding this comment

Uh oh!

enXov Dec 1, 2025

Choose a reason for hiding this comment

Uh oh!

Levev Dec 1, 2025

Choose a reason for hiding this comment

Uh oh!

enXov Dec 1, 2025

Choose a reason for hiding this comment

Uh oh!

Levev Dec 1, 2025

Choose a reason for hiding this comment

Uh oh!

enXov Dec 1, 2025

Choose a reason for hiding this comment

Uh oh!

enXov commented Dec 1, 2025

Uh oh!

enXov commented Dec 2, 2025

Uh oh!

enXov commented Dec 2, 2025

Uh oh!

enXov commented Dec 2, 2025

Uh oh!

Kunstbanause commented Dec 3, 2025

Uh oh!

enXov commented Dec 3, 2025

Uh oh!

Kunstbanause commented Dec 4, 2025

Uh oh!

enXov commented Dec 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Kunstbanause commented Dec 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

enXov commented Dec 6, 2025

Uh oh!

enXov commented Dec 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Kunstbanause commented Dec 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

enXov commented Dec 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Kunstbanause commented Dec 6, 2025

Uh oh!

enXov commented Dec 6, 2025

Uh oh!

enXov commented Dec 6, 2025

Uh oh!

enXov commented Dec 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Kaan88 commented Dec 14, 2025

Uh oh!

enXov commented Dec 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

enXov commented Oct 26, 2025 •

edited

Loading

enXov commented Dec 4, 2025 •

edited

Loading

Kunstbanause commented Dec 5, 2025 •

edited

Loading

enXov commented Dec 6, 2025 •

edited

Loading

Kunstbanause commented Dec 6, 2025 •

edited

Loading

enXov commented Dec 6, 2025 •

edited

Loading

enXov commented Dec 6, 2025 •

edited

Loading

enXov commented Dec 14, 2025 •

edited

Loading

Kaan88 commented Dec 14, 2025 •

edited

Loading