Set up GlanceKey

GlanceKey has two parts: the iPhone app, and GlanceKey on each computer. They reach each other through a relay on the internet, so they don't need to be on the same network.

What you need

iPhone

GlanceKey for iPhone is coming to the App Store; it's in testing now. Everything it needs to know about a computer, it learns when you pair with it.

Mac

Install

Download GlanceKey for Mac, open the zip and move GlanceKey to your Applications folder. Or use Homebrew:

brew install --cask dinkelburg/glancekey/glancekey

Open it, and GlanceKey appears in the menu bar. Click it to set it up:

  1. Accessibility access: click Grant… and switch GlanceKey on in System Settings. It needs this to type your password on the lock screen and into password dialogs.
  2. Mac password: enter your login password and click Save. GlanceKey checks it, then keeps it in your keychain. It never leaves your Mac.
  3. Pair iPhone… shows a QR code; see Pairing.

The menu also has Keep Mac awake on power adapter (a sleeping Mac can't be reached), Open at login, and Fill in password dialogs from iPhone.

Linux

Install

This installs glancekey-agent in ~/.local/bin and starts it with your session as a systemd user service (without one, it tells you how to start it). It doesn't need root, and running it again updates it.

curl -fsSL https://www.glancekey.com/install.sh | sh

Prefer to do it yourself? Download the program for x86-64 or ARM64, compare it with the checksums, put it on your PATH as glancekey-agent and run glancekey-agent install-service. Homebrew on Linux works too:

brew install dinkelburg/glancekey/glancekey-agent
glancekey-agent install-service

Set up

glancekey-agent set-password   # for Omarchy's lock screen; checked, then kept in your keyring
glancekey-agent pair           # shows a QR code to scan with your iPhone
glancekey-agent status         # the connection, the lock screen and your paired iPhones

How it unlocks depends on your lock screen: on Omarchy it types your saved password (it needs wtype, secret-tool and an unlocked GNOME keyring, which Omarchy has), hyprlock gets a signal to unlock, and GNOME and KDE unlock through logind. Only Omarchy needs the saved password.

Logs: journalctl --user -u glancekey-agent -f

Pairing

On the Mac click Pair iPhone…; on Linux run glancekey-agent pair. Scan the QR code with your iPhone's Camera and GlanceKey opens and pairs. Pairing creates a key on your iPhone for that computer, which only works after Face ID recognizes you. There's no account to make.

Pair each computer once. To add another computer, tap Add another computer in the app. To remove one, use its … menu in the app, and remove the iPhone on the computer too (the Mac menu, or glancekey-agent unpair <name>).

Unlocking

Open GlanceKey and look at your iPhone: if one computer is locked, it unlocks. If several are, tap the one you want, or Unlock all with one Face ID. Switch off Unlock when GlanceKey opens if you'd rather tap first.

Without opening the app: ask Siri, or use the Unlock Computer shortcut on the Action button, in Control Center or on your Home Screen.

The computer has to be awake and logged in. After a restart, type your password once yourself.

Approving sudo

Optional. sudo, and on Linux also polkit's admin dialogs, first waits for your iPhone:

$ sudo pacman -Syu
GlanceKey: approve on your iPhone, or wait 30 s to type your password.
GlanceKey: approved on iPhone.

Your iPhone shows the exact command. Tap Approve and look at your phone. If you tap Deny, don't answer within 30 seconds, or the iPhone can't be reached, sudo asks for your password as usual. Over SSH it asks for your password straight away.

On a Mac

In the GlanceKey menu, click Turn on… next to sudo and enter an administrator password. After pairing another iPhone or updating GlanceKey, the menu offers Update…. Turn off… puts sudo back to just your password.

If sudo ever stops working, this undoes it without sudo:

osascript -e 'do shell script "rm /etc/pam.d/sudo_local" with administrator privileges'

On Linux

sudo glancekey-agent enable-sudo    # again after pairing another iPhone or updating
sudo glancekey-agent disable-sudo   # back to just your password

polkit keeps its settings in /usr/lib/pam.d on Arch and Debian, so enable-sudo copies them to /etc/pam.d/polkit-1; run it again after polkit updates.

Why it's safe

Your iPhone signs the command it showed you, and a part of GlanceKey that only the system can change checks that signature against the iPhones you paired. GlanceKey itself, the relay and other programs running as you only pass messages along, so they can't approve in your place.

On Linux this is mostly a convenience: the password GlanceKey keeps for Omarchy's lock screen is in your keyring, which programs running as you can read, and it's also your sudo password.

Mac password dialogs

When a Mac dialog asks for your password, such as 1Password, Safari passwords, System Settings or an installer, it shows up on your iPhone. Tap Approve and look at your phone, and GlanceKey types your saved password into that dialog. Deny cancels it. Handle the dialog on the Mac instead and the request disappears from your phone. Switch it off with Fill in password dialogs from iPhone in the menu.

Notifications

In the iPhone app, turn on Notify me. When a computer waits for you, your iPhone gets a notification that names the computer; tap it to open GlanceKey. What's waiting travels over the relay when the app asks, never in the notification.

Your own relay

The relay that connects your iPhone to your computers is one small Cloudflare Worker, in the relay folder of GlanceKey's code (which goes public on GitHub at launch). Deploy it to your own Cloudflare account with npx wrangler deploy, then point your computers at it:

# Mac: then quit and reopen GlanceKey
defaults write nl.dinkelworks.glancekey.mac relayURL https://relay.example.com

# Linux: set "relay" in ~/.config/glancekey/agent.json, then
systemctl --user restart glancekey-agent

Then pair again. The QR code carries the relay's address, so your iPhone follows. Notifications need your own build of the iPhone app and your own Apple push key, because Apple only delivers them to apps of the key's developer.

Updating and removing

Mac

Update by downloading GlanceKey again and replacing it, or with brew upgrade --cask glancekey. If you use sudo approvals, click Update… when the menu asks for it.

To remove it: click Turn off… for sudo approvals, quit GlanceKey and delete it (or brew uninstall --cask glancekey), then remove the computer in the iPhone app.

Linux

Update by running the install command again, or with brew upgrade glancekey-agent followed by glancekey-agent install-service. If you use sudo approvals, run sudo glancekey-agent enable-sudo again.

To remove it:

sudo glancekey-agent disable-sudo
glancekey-agent forget-password
systemctl --user disable --now glancekey-agent
rm ~/.local/bin/glancekey-agent ~/.config/systemd/user/glancekey-agent.service   # or: brew uninstall glancekey-agent
rm -r ~/.config/glancekey

Troubleshooting

Still stuck? Email ruben@dinkelworks.nl.