Default applications and Web Apps: trace the route that actually launches

You choose Firefox as the default browser, but a Web App still opens in Chromium. A PDF opens in a browser, while an editor shortcut continues launching the old editor. These can be three different routing decisions, not one failed default setting.

This guide uses the pinned 4.0.0.alpha source. Later launchers can change implementation details; query your installed defaults and inspect your own shortcuts. Here the Web App resolver uses supported Chromium-family defaults and falls back to Chromium for others. It does not expose a separate universal Web App browser preference.

1. Follow the entry point before changing a setting

ordinary URL → XDG http/https handler → browser desktop entry
Omarchy browser shortcut → omarchy-launch-browser → default browser resolver
fixed personal shortcut → explicitly named command
file-manager open → file MIME type → default desktop entry
Web App entry → its Exec line → omarchy-launch-webapp → supported browser/fallback

Entry point	Usually follows	Useful check
Browser shortcut using Omarchy’s helper	Omarchy/XDG browser default	Binding description and action
Personal shortcut containing firefox	That explicit executable	Personal bindings.lua
URL clicked inside a chat app	XDG handler, unless app overrides it	App preference and HTTP/HTTPS handlers
PDF opened from Files	application/pdf handler	MIME query
PDF already inside a browser tab	Browser’s internal viewer	Browser settings, not file association
Installed Web App	Desktop entry’s Exec	Inspect the actual user entry

A launcher icon’s name does not prove which executable runs. A .desktop entry can call a helper, an explicit browser, or an app-specific command. A user entry with the same desktop ID can also shadow a system entry. MIME default specification

2. Record the current handlers

Before changing anything:

omarchy-default-browser
env -u BROWSER xdg-settings get default-web-browser
xdg-mime query default x-scheme-handler/http
xdg-mime query default x-scheme-handler/https
xdg-mime query default application/pdf
omarchy menu keybindings --print

Save the output locally. BROWSER can influence some tools; Omarchy clears it for its browser-default query to avoid resolving back to its own helper. The pinned resolver searches configured HTTP associations for an installed entry, then falls back to XDG queries. An HTTP/HTTPS disagreement therefore deserves investigation rather than another unrelated reinstall. Default resolver

Record existing mimeapps.list files in your user configuration, including any desktop-specific variant. Back up files you plan to edit with new names, and record absent files. Do not copy a whole guessed mimeapps.list over your existing associations.

3. Case: Firefox for ordinary links, Chromium for Web Apps

Install Firefox through Install → Browser if needed, then use Setup → Defaults → Browser to choose it. The direct equivalent at this snapshot is:

omarchy-default-browser firefox

This setter may offer installation if the executable is missing. Installing a browser and selecting it as default are different operations; confirm the displayed default afterwards.

Test three entry points with a harmless URL:

xdg-open 'https://example.com/'
omarchy-launch-browser 'https://example.com/'
omarchy-launch-webapp 'https://example.com/'

Expected for this configuration: the first two use Firefox if their associations are consistent; the third uses Chromium in app mode. This is the intended fallback, not evidence that Firefox was never selected. It does not create a persistent application entry by itself. Browser setter · Web App resolver

Try a URL click from the actual chat app too. If that alone launches something else, inspect that application’s explicit browser preference. A successful helper test cannot prove every app uses the helper.

Changing the ordinary default to a supported Chromium-family browser can also move Web Apps to that browser. Existing cookies, profiles and login state do not migrate automatically. Do not promise that a Web App is isolated merely because it has no ordinary browser toolbar; this launcher does not automatically create a separate profile for every app.

4. Case: a shortcut ignores the new default

Inspect your personal binding and the current list. Compare these actions:

-- Follows Omarchy's browser helper.
o.rebind("SUPER + SHIFT + RETURN", "Browser", { omarchy = "browser" })

-- A deliberate fixed application, independent of the browser default.
-- o.rebind("SUPER + SHIFT + RETURN", "Firefox", { launch = "firefox" })

Use only the intended definition, after backing up bindings.lua. The first example replaces an existing binding; it does not add another competing action. Save through Setup → Keybindings, query the list and test the key.

The same distinction applies to editor helpers versus a shortcut naming a particular editor. The “default editor” used by an Omarchy command is also not a universal promise about every text-file MIME type or an application’s built-in editor. See shortcut design for matching, conflicts and rollback.

5. Case: PDFs should open in a document viewer

Use a local, non-sensitive PDF as the test. Establish its actual type rather than assuming the extension:

xdg-mime query filetype "$HOME/Documents/test.pdf"
xdg-mime query default application/pdf

Replace that path with an existing test file. A missing file does not test its association. In Files, use Open With to choose an installed viewer and, where offered, make it the default. Alternatively use xdg-mime default with the viewer’s verified desktop ID.

For example, only if your installed entry is org.gnome.Evince.desktop:

xdg-mime default org.gnome.Evince.desktop application/pdf
xdg-open "$HOME/Documents/test.pdf"

Check the ID in /usr/share/applications/ or ~/.local/share/applications/ first. The executable evince and its desktop ID are different names; another package can provide another ID.

Verify both the query and an actual open from Files. A browser’s own download/PDF preference may still display a document in a tab. Changing the file association does not replace that in-browser behaviour, nor does selecting a browser change all PDF associations.

6. Inspect and create one Web App entry

Use Install → Web App for an app name, an HTTP(S) URL and its icon. A unique name avoids overwriting an existing entry. A safe teaching example is Example Site with https://example.com/; this tests launching, not a real service’s login workflow.

The created entry is under ~/.local/share/applications/. Inspect, rather than execute, its identifying fields:

grep -E '^(Name|Exec|Icon|StartupWMClass)=' \
  "$HOME/.local/share/applications/Example Site.desktop"

The normal Exec calls omarchy-launch-webapp. A legacy entry with an explicit chromium --app=..., or a custom command, can bypass today’s default resolver. Read the actual file before concluding the helper is wrong. Installer source

Launch from the menu and check hyprctl clients if you need a workspace rule. The class of a Web App can differ from the normal browser; discover it before writing a rule. Test an already-open instance separately: an application may focus an existing window instead of creating a new one.

Do not copy shell quoting into Exec blindly. Desktop entries have their own quoting and field codes: %U represents URLs supplied by the launcher, while literal percent signs need escaping. A URL with query parameters should remain one argument. Prefer Omarchy’s installer to hand-building this escaping. Desktop Entry Exec specification

7. Diagnose and restore only the affected route

Symptom	Next evidence
Firefox ordinary links, Chromium Web Apps	Expected unsupported-default fallback in this snapshot
Only one Web App ignores the default	Its Exec, custom entry and existing instance
Only one key launches the old browser	Fixed or duplicate binding
HTTP and HTTPS differ	Both handlers and relevant mimeapps.list precedence
Default points to an uninstalled app	Desktop entry and whether its executable still exists
PDF query is right, browser still shows PDFs	Browser’s internal viewer preference
Website logged out after browser change	Different browser/profile storage, not an XDG routing failure

Restore the recorded browser through the defaults menu. Restore the old PDF handler only if it is nonempty and its desktop entry still exists. If the original had no explicit association, restore the backed-up association files after comparing later changes; inventing an explicit handler is not identical to restoring inheritance.

Remove the test Web App through Remove → Web App using its unique name. Removing its launcher does not erase a website account, browser cookies or an already-running window. Restore only the edited binding or compare its backup. Then repeat the same URL, shortcut, PDF and Web App tests; each checks a separate route.

Continue with window rules, application appearance and application management. Sources were reviewed; the workflows were not run on a real Omarchy installation.