Unlock a Stuck Linux Lock Screen from Your Phone (Cordovan)
The problem: you type your password, the lock screen says "Authenticating..." and nothing happens. Switching to a text console (Ctrl-Alt-F2) can freeze the whole machine, and then the only way out is the power button.
The fix: a button on your phone, "Unlock computer". Tap it and the lock screen clears. Your windows and work stay as they were.
It uses KDE Connect's "Run command", which you probably already have if your phone's notifications show up on your computer.
Install
bash install.shIt asks for your password once. Then add the button on the computer:
- KDE Plasma: System Settings > KDE Connect > your phone > Run command > Add command
- GNOME (GSConnect): GSConnect settings > your phone > Commands > +
- COSMIC: see "COSMIC" below
Name it Unlock computer. The command is ~/.local/bin/phone-unlock (the installer prints the full path). On the phone: KDE Connect > your computer > Run command.
Try it: lock the screen, tap the button.
To remove: bash uninstall.sh, then delete the button.
If the button doesn't work
- The phone and computer must be connected (notifications coming through).
- From another computer:
ssh yourcomputer loginctl unlock-sessions - Frozen solid: hold Alt+SysRq and press R, E, I, S, U, B, a second or two apart. That restarts safely, saving files first. The power button does not.
Please test before relying on it
This is shared as-is, with no warranty. It works on my own computers, and your system, settings and software versions may differ, so please try it in a safe setting first. If something doesn't work, you can ask Claude (or another AI coding assistant) to look into it, and I'd appreciate hearing what you found and how you fixed it. You are also welcome to just let me know at support@veered.org, and I'll look into it.
License
MIT.
Information for nerds
What it installs
| File | What it does |
|---|---|
~/.local/bin/phone-unlock | Runs loginctl unlock-sessions; logs each run to ~/.local/state/phone-unlock.log |
/etc/polkit-1/rules.d/49-<you>-phone-unlock.rules | Grants org.freedesktop.login1.lock-sessions to your user only |
loginctl unlock-sessions asks systemd-logind to send Unlock to every session, and the desktop's locker drops the lock. Without the rule, logind wants interactive authentication, which a phone-triggered command can't give. The rule names only your user, and only the lock/unlock-sessions action. Anyone who can already run commands as you could unlock your screen anyway, so it adds nothing an attacker in your account didn't have.
COSMIC
COSMIC's KDE Connect daemon (cosmic-utils/kdeconnect) reads commands from ~/.config/kdeconnect/runcommand.json:
[{"id":"phone-unlock","name":"Unlock computer","command":"/home/YOU/.local/bin/phone-unlock"}]Then send the list to the phone (or reconnect it):
busctl --user call io.github.hepp3n.kdeconnect /io/github/hepp3n/kdeconnect/Daemon \
io.github.hepp3n.kdeconnect.Daemon PushLocalCommands s <device-id>ListDevices on the same object gives the device id. If the link keeps dropping on COSMIC, see Scarlet.
Checking a tap arrived
tail ~/.local/state/phone-unlock.logok means logind accepted it; failed: shows logind's reason.