Problem

After clicking login in Kiro IDE on Linux, the browser opens and authentication succeeds, but the redirect to kiro:// protocol fails to return to the IDE, leaving you stuck on the login screen.

Root Cause

Linux doesn't have the kiro:// custom protocol handler registered, so the browser doesn't know which application should handle the redirect URL.

Solution

1. Create Protocol Handler Desktop File

Create ~/.local/share/applications/kiro-url-handler.desktop with the following content:

[Desktop Entry]
Name=Kiro URL Handler
Exec=/path/to/your/Kiro/kiro --open-url %u
Type=Application
Terminal=false
MimeType=x-scheme-handler/kiro;
NoDisplay=true

Important: Replace /path/to/your/Kiro/kiro with your actual Kiro IDE installation path.

2. Register the Protocol Handler

Run these commands:

# Update desktop database
update-desktop-database ~/.local/share/applications/

# Set as default handler for kiro:// protocol
xdg-mime default kiro-url-handler.desktop x-scheme-handler/kiro

3. Verify Registration

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

Should output: kiro-url-handler.desktop

4. Test

xdg-open "kiro://test"

This should launch Kiro IDE.

5. Complete Login

1. Close all Chrome/browser windows (important for browser to reload protocol handlers)
2. Restart Kiro IDE
3. Click login again - the redirect should now work correctly

Key Points

• The --open-url parameter is crucial - without it, Kiro treats the URL as a file path
• The %u placeholder gets replaced with the actual kiro:// URL including all parameters
• Kiro IDE is a single-instance application, so the protocol handler passes the URL to the running instance

Tested On

• Fedora Linux
• Kiro IDE 0.6.32

Should work on other Linux distributions as they all use the same XDG protocol handler system.