If you’re moving to Waterfox because of the Mozilla CEO’s recent threat that “[Firefox] will evolve into a modern AI browser…” and you use KDE Plasma, you may be surprised to see that the native browser integration doesn’t work. Don’t fret though, the problem is actually because Waterfox is looking for files that haven’t been copied to the right place. Let’s fix that.

The Workaround

A screenshot of the Waterfox browser with the Plasma Browser Integration add-on installed. The add-on shows an error message that reads “Failed to connect to the native host.” and gives some troubleshooting options and a link to the project wiki.

The error message you may have seen.

The most convenient way to install Waterfox and keep it updated automatically is through Flathub. The files we need will be created once the Firefox Flatpak is installed. Go ahead and install the Firefox Flatpak as well. You’ll also need Flatseal to add a permission to Waterfox.

Open your application launcher and search for “Background Services”. In the search bar, type "browser”. You should see two services:

A screenshot of the KDE Background Services options window. The search bar has the word “browser” typed in it. There are two services listed: Plasma Browser Integration Flatpak Integration and Plasma Browser Integration Installation Reminder. Both are enabled and currently running.

The two background services we need.

Pause and unpause the Plasma Browser Integration Flatpak Integration service. This step may be unnecessary, but will speed things up if you’re between polling cycles (this is mostly an assumption).

Now, let’s copy some files:

# Copy the integration host to Waterfox's flatpak data directory
cp ~/.var/app/org.mozilla.firefox/plasma-browser-integration-host ~/.var/app/net.waterfox.waterfox/plasma-browser-integration-host
# Make a director for the next file
mkdir ~/.var/app/net.waterfox.waterfox/.waterfox/native-messaging-hosts
# Use sed to replace the Firefox flatpak app id with Waterfox's flatpak app id,
# then output that file to where Waterfox will look for native-messaging-hosts.
# Ref: <https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Native_messaging>
sed 's/org\\.mozilla\\.firefox/net\\.waterfox\\.waterfox/' ~/.var/app/org.mozilla.firefox/.mozilla/native-messaging-hosts/org.kde.plasma.browser_integration.json > ~/.var/app/net.waterfox.waterfox/.waterfox/native-messaging-hosts/org.kde.plasma.browser_integration.json

Now, open Flatseal and select Waterfox to edit its settings. We need to go to Session Bus → Talks and add a new item: org.kde.plasma.browser.integration .

A screenshot of Flatseal with Waterfox selected. In the window, you can see the “Session Bus” section. Added to the “Talks” subsection is a new string with the contents “org.kde.plasma.browser.integration”. A warning symbol is shown next to the value to indicate the default permissions have been changed.

When you’re done, Waterfox should look like this in Flatseal.

Now, when you manage the Plasma Integration add-on and go to Preferences, you’ll see options! Furthermore, you can control your browser’s media with your media keys and system tray icons.

A screen shot of Waterfox showing the “about:addons” page with “Plasma Integration” selected. The “Preferences” tab is selected with various options showing. This indicates that the extension can talk to our local messaging host.

The Plasma Integration add-on works in Waterfox Flatpak!

The Real Fix

This is a cool workaround, but the real issue lies in https://invent.kde.org/plasma/plasma-browser-integration. The application watches for many different browsers, but not Waterfox… for now… hopefully… I have a merge request out to KDE with the fix for Waterfox, both Flatpak and native versions:

feat: add waterfox support (!180) · Merge requests · Plasma / Plasma Browser Integration · GitLab