Files

T

AaronandGitHub 2d7c40ef81 [WEB-6612] fix(desktop): handle deep link URLs on Linux/Windows cold launch (#6252 )

* fix(desktop): handle deep link URLs from process.argv on Linux/Windows cold launch

On macOS, Electron receives plane:// deep links via the 'open-url' event.
On Linux/Windows, when the app is not running, xdg-open/shell launches the
app with the URL as a command-line argument. Without reading process.argv,
the deep link was silently dropped and Google OAuth sign-in would stall
after the browser redirect.

* docs: add Linux desktop app setup guide with protocol handler instructions

2026-03-13 17:19:32 +05:30

3.4 KiB

Raw Blame History

Plane Desktop App — Linux Setup

Prerequisites

A Linux distribution with a Wayland or X11 desktop environment
The Plane .AppImage file downloaded to ~/Downloads

1. Install AppImageLauncher

AppImageLauncher handles desktop integration (menu entries, icons) for AppImage files.

Arch Linux (AUR):

yay -S appimagelauncher

Ubuntu/Debian:

Download the latest .deb from AppImageLauncher releases and install:

sudo dpkg -i appimagelauncher_*.deb
sudo apt-get install -f

Fedora:

Download the latest .rpm from AppImageLauncher releases and install:

sudo rpm -i appimagelauncher-*.rpm

2. Install the Plane AppImage

Make the AppImage executable:
```
chmod +x ~/Downloads/Plane-*.AppImage
```
Run the AppImage:
```
~/Downloads/Plane-*.AppImage
```
AppImageLauncher will show a dialog asking to Integrate and run or Run once. Choose Integrate and run.

This moves the AppImage to ~/Applications/ and creates a .desktop entry so Plane appears in your application launcher.

3. Register the `plane://` Protocol Handler

To enable deep links (e.g., plane:// URLs that open directly in the desktop app), you need to register a protocol handler.

Find the Plane .desktop file:
```
ls ~/.local/share/applications/ | grep -i plane
```
You should see something like appimagekit_...-Plane.desktop.

Add the protocol handler to the .desktop file:

DESKTOP_FILE=$(ls ~/.local/share/applications/appimagekit_*-Plane.desktop 2>/dev/null | head -1)

# Check it doesn't already have MimeType for plane
if ! grep -q "x-scheme-handler/plane" "$DESKTOP_FILE"; then
  sed -i '/^Categories=/i MimeType=x-scheme-handler/plane;' "$DESKTOP_FILE"
fi

DESKTOP_FILENAME=$(basename "$DESKTOP_FILE")
xdg-mime default "$DESKTOP_FILENAME" x-scheme-handler/plane
update-desktop-database ~/.local/share/applications/

Verify it works:
```
xdg-open plane://test
```
The Plane desktop app should launch (or come to focus if already running).

Troubleshooting

AppImageLauncher dialog doesn't appear

Make sure the AppImageLauncher daemon is running:

# Check if the service is active
systemctl --user status appimagelauncherd

# Start it if needed
systemctl --user enable --now appimagelauncherd

`plane://` links don't open the app

Verify the handler is registered:

xdg-mime query default x-scheme-handler/plane

This should print the Plane .desktop filename. If it doesn't, re-run step 3 above.

App doesn't launch on Wayland

If the app fails to start or shows a blank window, try launching with the Ozone flag:

~/Applications/Plane-*.AppImage --ozone-platform-hint=auto

To make this permanent, edit the Exec line in the .desktop file to include the flag before %U.

Updating the AppImage

When you download a new version:

Remove the old version via the application launcher (right-click → "Delete this AppImage") or delete it from ~/Applications/.
Run the new .AppImage from ~/Downloads/ — AppImageLauncher will prompt to integrate it again.
Re-run the protocol handler registration (step 3) since the .desktop file will be recreated.

3.4 KiB Raw Blame History