feat: add desktop shortcuts for Windows applications

[enXov]

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.

[enXov]

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 :sob:

[svein298]

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

[enXov]

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

[enXov]

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

[enXov]

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 :sob:

[enXov]

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]

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]

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]

Works with the fix: https://github.com/TibixDev/winboat/commit/637d68f0307b83433a31bb56f884da0f9239a40f

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

[enXov]

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]

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]

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.

[enXov]

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]

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]

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]

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]

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

[enXov]

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

[enXov]

that should be 100% working,

can you test now???

[Kaan88]

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]

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]

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]

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]

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]

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

[TDS700]

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.

[enXov]

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