KeePassXC Wayland Auto-Type

A standalone Wayland Auto-Type bridge for KeePassXC databases. It does not patch KeePassXC, so normal KeePassXC package upgrades do not overwrite it.

The recommended memory-agent setup asks for the database password once at login, keeps it encrypted in guarded memory, and can then Auto-Type into normal applications or unlock KeePassXC itself. GNOME Keyring remains the desktop Secret Service provider.

Behavior

• Ctrl+Alt+X once: Auto-Type the single matching entry. If there are zero or multiple matches, open the selector.
• Ctrl+Alt+X twice within 250 ms: always open the selector with entries matching the active window ranked first.
• The selector can type the normal sequence, username, password, or TOTP.
• The active window title is placed in the search field initially when at least one entry matches any meaningful word from it; otherwise search starts empty.
• Switching to another application closes the selector instead of leaving it backgrounded.

The shortcut is registered through the desktop or compositor—not through an application-specific hotkey daemon.

Requirements

• A Wayland compositor with a focused-window adapter:
  • KDE Plasma: kdotool
  • Hyprland: hyprctl
  • Niri: niri
• KeePassXC and keepassxc-cli
• ydotool with its user service and writable /dev/uinput
• Python 3, PyQt6, libsodium, and notify-send

On Arch Linux / EndeavourOS:

sudo pacman -S --needed keepassxc ydotool python-pyqt6 qt6-base libnotify

Also install kdotool when using KDE. Hyprland and Niri provide their own IPC commands.

Quick start

./install.sh --memory-agent --database /absolute/path/to/database.kdbx

For a database that also requires a key file:

./install.sh --memory-agent \
  --database /absolute/path/to/database.kdbx \
  --key-file /absolute/path/to/database.keyx

The agent starts with the graphical session and opens its one-time password dialog. Register this command as Ctrl+Alt+X using the normal shortcut settings of your desktop:

/home/you/.local/bin/keepassxc-wayland-autotype --trigger

The memory agent clears its session password on screen lock and suspend by default. These events can be controlled independently in ~/.config/keepassxc-wayland-autotype.conf:

CLEAR_ON_SCREEN_LOCK=true
CLEAR_ON_SUSPEND=true

Set an option to false and restart the agent to retain the session password across that event. Logout and agent exit always discard process memory.

Examples:

• KDE Plasma: System Settings → Keyboard → Shortcuts → Add New → Command or Application.

• Hyprland 0.55 or newer:

  hl.bind("CTRL + ALT + X", hl.dsp.exec_cmd("/home/you/.local/bin/keepassxc-wayland-autotype --trigger"))
  

• Niri, inside binds { ... }:

  Ctrl+Alt+X repeat=false { spawn "/home/you/.local/bin/keepassxc-wayland-autotype" "--trigger"; }
  

These are examples, not a desktop allowlist. Any shortcut manager capable of launching a command can call --trigger; another compositor only needs an adapter for its active-window and focus APIs.

Documentation

• Only enter your password once — setup
• KeePassXC entry and Auto-Type setup
• Security model and boundaries
• Alternative database backends
• Migrating GNOME Keyring entries

Installed components

~/.local/bin/keepassxc-wayland-autotype
~/.config/keepassxc-wayland-autotype.conf
~/.config/systemd/user/keepassxc-wayland-autotype-agent.service

Two background user services are involved:

• keepassxc-wayland-autotype-agent.service owns the encrypted session secret, metadata cache, selector, screen-lock monitoring, and trigger socket.
• ydotool.service owns the virtual input device required by Wayland.

Check them with:

systemctl --user is-active keepassxc-wayland-autotype-agent.service
systemctl --user is-active ydotool.service

Updating and uninstalling

Re-running the installer without database arguments preserves the existing configuration:

./install.sh

Remove the program while retaining its configuration:

./uninstall.sh

Also remove the database-path configuration:

./uninstall.sh --purge-config

The database and key file are never deleted.

Development

python -m py_compile src/keepassxc-wayland-autotype.py
python -m unittest discover -s tests -v

No KeePassXC source patches are required or included.