The Desktop Launcher Opened the App and Dropped the Login
A Linux desktop entry advertised our callback scheme but never passed the URL to the app. GIO returned success. The AppImage had a separate problem: no registered handler at all.
gio open returned zero. The app opened. The login callback never arrived.
That was the useful failure in our latest test of gptme’s Linux desktop release. The native callback parser could handle a URL passed directly to the executable. That did not establish whether a browser could deliver one through the operating system.
For Linux desktop maintainers, these are two separate questions: does a handler exist, and does its launch command forward the URI? Our Debian package failed the second. Our unintegrated AppImage failed the first.
An association without an argument
The published v0.35.1 Debian package contained these desktop-entry fields:
Exec=gptme-tauri
MimeType=x-scheme-handler/gptme
The MIME declaration advertises a handler for gptme:// links. The Exec line starts the program, but contains no URI field code. Querying the entry through GIO returned supports_uris=false.
We unpacked the released package into an isolated desktop profile, launched the actual GUI binary, and opened a synthetic callback through GIO. A process trace showed the launcher invoking the executable without the URL in its arguments. The running app logged no callback ingestion.
Then we changed only the test entry to include %U, which expands to a list of URIs. GIO still returned zero, but this time the URL reached argv unchanged and the running app ingested the fake authorization code.
| Desktop entry | GIO exit | URI in argv | Native callback ingested |
|---|---|---|---|
| Published entry, no URI field code | 0 | No | No |
Control entry with %U |
0 | Yes | Yes |
The synthetic code was deliberately not a credential. This test established delivery to the native handler, not a successful sign-in.
The repair in gptme/gptme#4417 supplies a shared Tauri desktop template for Debian and RPM:
Exec= %u
The lowercase %u accepts one URI, matching a single callback. The uppercase form was the diagnostic control; the final template uses the singular form. AppImage staging also consumes this template through Tauri’s Debian data generator. We used Tauri’s supported template configuration rather than rewriting generated packages afterward. The bundler defect is also tracked upstream.
The AppImage had no association
The released AppImage failed earlier in the path. In a fresh profile, it created no handler. The default association query was empty, GIO found no application for the scheme, and opening a synthetic callback exited 2.
The existing runtime registration call was guarded by cfg!(debug_assertions). It could run in development and disappear from a release build.
gptme/gptme#4418 enables that existing registration path for Linux release builds too, following Tauri’s AppImage guidance. That path needs xdg-mime and update-desktop-database available.
A locally built optimized AppImage then registered a handler pointing at its persistent file path, with the path quoted and %u appended. We moved the AppImage to a different path containing spaces and launched it again in the same profile. The association updated; dispatch still reached the native app while the old file path was absent.
Test the boundary cheaply, then test the whole trip
The Debian regression extracts the generated package and launches its desktop entry through GIO. An argument recorder stands in for the app in this narrow check. It compares the received URI exactly, including & and %2F, without starting a sidecar or spending a real authorization code. The regression fails on the published package and passes on the locally rebundled package.
That recorder does not prove login works. The separate native reproduction proves callback ingestion. A further test of the locally built AppImage goes through the real browser, with a Playwright driver filling the real sign-in page using an existing dogfood account and native input approving the browser confirmation:
- Click Cloud sign-in in the native app.
- Sign in through the browser opened by the OS association.
- Approve Chromium’s “Open gptme” confirmation.
- Let the browser dispatch the callback through the registered handler.
- Complete the setup wizard and send a prompt from the GUI.
- Observe the assistant reply.
No code was extracted from the browser and handed to the executable manually. That omission matters: manual delivery would skip exactly the boundary that broke.
What this does—and does not—establish
The local optimized AppImage completed that browser-to-reply flow in an isolated GNOME/GIO fixture, using the real released v0.35.1 sidecar. This is evidence for the repaired native registration path and current frontend. It is not verification of every Linux desktop, or of Windows and macOS.
The v0.35.1 download stayed broken. The source repairs merged the same day as this draft (gptme/gptme#4417, gptme/gptme#4418) and first shipped in the v0.36.0 notes (2026-11-02).
A changelog line is not that test, so on 2026-11-19 I checked the released artifacts instead. Extracting both packages from the current v0.37.0 release:
gptme_0.37.0_amd64.deb usr/share/applications/gptme.desktop: Exec=gptme-tauri %u
gptme-0.37.0-1.x86_64.rpm ./usr/share/applications/gptme.desktop: Exec=gptme-tauri %u
That is the exact defect, fixed where it counts: the packaged entry now forwards the URI, in both the Debian and the RPM build. It closes the packaging half of the question. I still have not replayed the AppImage runtime registration end to end against a released build, and nothing here says anything about Windows or macOS.
The practical debugging order is short: inspect the scheme association, inspect the launch command, observe the actual argv, then test sign-in. A successful launcher exit tells you much less than the callback reaching the app.