Mudrix Desktop

The desktop app for Mudrix, built with Tauri v2.

Mudrix Desktop is a fork of WizardChat Desktop by Arian Farahani and Jan Philipp Kleinschmidt, rebuilt on Tauri instead of Electron. It is licensed under the AGPL-3.0 (see LICENSE), like upstream.

It wraps the Mudrix web client (the mudrix-web git submodule) and adds:

• a system tray icon (Open Mudrix, Mute notifications, Quit); closing the window hides to the tray (setting "Keep running in the background", on by default); left-click toggles the window
• a single running instance (a second launch focuses the window and forwards matrix: links)
• optional launch at login, optionally minimised to the tray
• the window size and position are remembered
• native notifications; the sound is still played by the web app
• an unread badge: tray icon and tooltip, Windows taskbar overlay, macOS dock badge
• matrix: deep links
• in-app updates, verified against a minisign signature (Windows and macOS install them, Linux gets a download prompt; AppImage installs update in place)
• a themed app icon that follows the theme setting (window and tray)
• optional activity sharing (Settings > Activity): detects the game you are playing (against a list of known games, plus programs you add yourself) and the song playing in a music app, and shows it on your profile. Windows only for now.
• SSO / OIDC login through the system browser (see below)

Setup

git clone --recurse-submodules https://github.com/kapsikkum/mudrix-desktop.git
cd mudrix-desktop
npm install

If you cloned without submodules: git submodule update --init --recursive.

You need Node 20+, a Rust toolchain (rustup) and the Tauri prerequisites for your OS (WebView2 on Windows, Xcode command line tools on macOS, webkit2gtk-4.1 and friends on Linux).

Develop

npm run desktop:dev

This starts the web client's Vite dev server on port 8080 (--strictPort) and opens the Tauri window on it. If you already run the web dev server on 8080, attach to it instead:

npm run desktop:dev:attach

The first run compiles the Rust dependencies, which takes a while and a lot of memory.

Build

npm run desktop:build

This builds mudrix-web (npm ci and npm run build inside the submodule), then the installers into src-tauri/target/release/bundle/ (NSIS and MSI on Windows, .dmg and .app on macOS, AppImage, .deb and .rpm on Linux). For a universal macOS build add -- --target universal-apple-darwin. Releases are built by GitHub Actions; RELEASING.md covers cutting a release and the update signing key.

Unsigned builds

Releases are not code-signed.

• Windows: SmartScreen shows "Windows protected your PC". Click "More info", then "Run anyway".
• macOS: Gatekeeper blocks the first launch. Open System Settings, Privacy & Security, scroll to Security and click "Open Anyway" (or right-click the app and choose Open).
• Linux: no warning. Make the AppImage executable (chmod +x) and run it.

The installers are unsigned, but in-app updates are not: every update is checked against a minisign signature (tauri-plugin-updater) before it is installed.

Login: SSO and OIDC

The webview's own origin (http://tauri.localhost, tauri://localhost) cannot be a redirect target for an identity provider, so the app signs in through your system browser and a loopback listener on 127.0.0.1 (the same approach the Electron app used):

• OIDC (Matrix Authentication Service): the redirect URI is http://127.0.0.1:34759/oidc/callback, registered dynamically as a native client. The homeserver / MAS must allow loopback redirects for native clients (MAS does by default).
• Matrix SSO (m.login.sso): the redirectUrl is rewritten to http://127.0.0.1:<port>/. Synapse only redirects to URLs in sso.client_whitelist, so the homeserver needs client_whitelist: ["http://127.0.0.1"] (or the port-less prefix) for desktop SSO to work.
• Password login needs nothing special.

Known gap: the "SSO popup" used for cross-signing / UIA re-authentication needs window.opener messaging and is not reworked for the system browser; use the homeserver's account page in that case.

Push to talk

The push-to-talk key is heard system-wide (src-tauri/src/ptt.rs, using rdev; it only listens, the key still reaches the app in front). On macOS this needs Input Monitoring (System Settings > Privacy & Security); the web app asks for it. Under Linux it needs an X11 session: on Wayland it is reported as unsupported and the key only works while the Mudrix window is focused.

Notifications

On Windows and Linux the notification plugin cannot report clicks. Instead, when the window gains focus within 20 seconds of a notification (for example after clicking it, or the tray icon), the room of that notification is opened.

How the pieces fit

path	what
mudrix-web/	git submodule, the web client (https://github.com/kapsikkum/mudrix-web)
src-tauri/	the Rust shell: tray, settings, notifications, auth loopback, updater
src-tauri/tauri.conf.json	window, CSP, bundle config (version read from package.json)
src-tauri/capabilities/default.json	permissions of the webview (only core:default)
src-tauri/icons/	app icons (generated from logo.svg with tauri icon) and tray/ variants
src-tauri/src/activity/	activity detection (running games, music) and games.json, the known-games list
scripts/	check-version.mjs, set-version.mjs, sync-games-db.mjs, format-games-db.mjs

The web client talks to the shell through src/util/desktop.ts in mudrix-web; none of it runs in a normal browser.

The Content Security Policy in tauri.conf.json allows https: and wss: for homeservers, GIF providers (api.giphy.com, api.klipy.com and their CDNs) and media, blob: and data: images, and 'wasm-unsafe-eval' for the Matrix crypto WebAssembly.