keepassxc-keyring

Recipe card from the charly-infrastructure plugin (Images — the deployable catalog).

keepassxc-keyring – KeePassXC as the system Secret Service

Candy Properties

Property	Value
Dependencies	`keepassxc`, `gnupg`
Ports	none
Service	none (KeePassXC autostarted via XDG `~/.config/autostart/keepassxc.desktop`, not a systemd unit)
Install files	`task:` only
Target	`target: local` (host deploys); harmless on container images but pointless

Packages

Arch (pac:): pinentry, libsecret
Fedora (rpm:): pinentry-qt, libsecret
Debian/Ubuntu (deb:): pinentry-qt, libsecret-tools

pinentry provides the GUI passphrase dialog that gpg-agent spawns; libsecret provides secret-tool and the C client lib that pinentry-qt uses to query KeePassXC.

What this candy changes on the host

~/.config/keepassxc/keepassxc.ini — writes [FdoSecrets] Enabled=true block (and three plugin-behavior toggles).
~/.config/autostart/keepassxc.desktop — XDG autostart entry that launches KeePassXC on every session login.
~/.config/autostart/<competitor>.desktop — for each known competing Secret Service daemon (gnome-keyring-secrets, gnome-keyring-ssh, gnome-keyring-pkcs11, org.kde.kwalletd[5,6], kwalletd[5,6]), writes an override with Hidden=true + X-GNOME-Autostart-enabled=false. Per the XDG spec, user-level overrides take precedence over /etc/xdg/autostart/, so the system package stays untouched and the change is fully reversible by charly bundle del.
systemctl --user disable --now <unit> for the same competitors’ systemd user units (gnome-keyring-daemon.socket, gnome-keyring-daemon.service, the kwallet service variants). Idempotent, silent if a unit doesn’t exist.
~/.gnupg/gpg-agent.conf — pinentry-program /usr/bin/pinentry-qt (the libsecret-linked pinentry that talks to KeePassXC for GPG passphrase storage).
~/.config/environment.d/ssh-agent.conf — exports SSH_AUTH_SOCK="${XDG_RUNTIME_DIR}/ssh-agent.socket" for systemd-bootstrapped sessions.
Per-shell init exports (via the shell: schema): for non-systemd-bootstrapped shells (tmux from a screen-locked session, ssh-in shells without a fresh login, scripts), the candy’s shell: block lands managed-block exports of SSH_AUTH_SOCK (guarded with command -v / socket-existence check), KEEPASSXC_DATABASE advisory pointer, and GPG_TTY=$(tty). bash/zsh/sh share one POSIX-style snippet; fish gets a syntactically-correct counterpart via set -gx. environment.d (item 6) and the shell: block coexist with no conflict — environment.d wins under systemd, the shell-rc lines fill the gap when systemd isn’t in the loop.
Direnv shell hooks come from the direnv candy (declared via require: [direnv]). This candy writes no direnv hooks itself — the responsibility belongs to the direnv candy’s own shell: block. charly migrate cleans up any legacy inline direnv-hook blocks left on a host by older configs.
systemd user service for KeePassXC with Restart=on-failure and explicit dependency on graphical-session.target.

What this candy DOES NOT do

Marking a .kdbx group as “Secret Service exposed” — this is per-database state inside the .kdbx file itself, not in keepassxc.ini. It is a one-time GUI action (right-click group → “Mark as Secret Service exposed”) performed by the user once per database.
charly secrets gpg setup — the gpg-agent.conf, systemd socket, and Secret-Service passphrase storage are still wired by the user-invoked charly secrets gpg setup command. This layer just installs the packages that command requires (pinentry-qt, libsecret).
Removing or downgrading any system package. All competitor disabling is per-user, reversible.

Usage

local:
  charly-cachyos:
    candy:
      - direnv
      - gnupg
      - keepassxc
      - keepassxc-keyring     # this layer
      ...

Order with respect to direnv/gnupg/keepassxc doesn’t strictly matter (the candy system topo-sorts via require:), but listing them adjacently makes the YAML self-documenting.

Used In Boxes / Templates

charly-cachyos (kind:local template, applied via the charly-cachyos deployment — same name; cross-kind name reuse is permitted)

Tests

Build-scope (run on package install):

keepassxc-binary — /usr/bin/keepassxc exists.
pinentry-qt-installed — at least one of pinentry-qt, pinentry-qt5, pinentry-qt6 resolvable on PATH.
secret-tool-installed — secret-tool resolvable on PATH.

Deploy-scope (run on the host post-charly bundle add against the running user’s HOME):

keepassxc-ini-fdosecrets — [FdoSecrets] Enabled=true written.
keepassxc-autostart — autostart .desktop file readable.
gnome-keyring-secrets-disabled — competitor override has Hidden=true (or the file doesn’t exist on this host, which is also fine).
direnv-fish-hook — fish hook file contains direnv hook fish.
direnv-bash-hook — ~/.bashrc contains the bash hook.

Relationship to other skills

Skill	Relationship
`/charly-infrastructure:keepassxc`	The package-only candy. `keepassxc-keyring` `require:` on it; never composes it.
`/charly-infrastructure:gnupg`	Same — keepassxc-keyring `require:` on gnupg, never composes.
`/charly-distros:agent-forwarding`	Distinct concern. agent-forwarding is for FORWARDING the host’s GPG/SSH agents INTO containers via socket bind-mounts. keepassxc-keyring is about turning the host itself into a Secret Service server. Both can be active simultaneously.
`/charly-build:secrets`	The CLI surface that talks to KeePassXC after this layer is in place. `charly secrets gpg setup` and `charly secrets gpg doctor` find pinentry-qt + libsecret on PATH because this layer installed them.
`/charly-coder:direnv`	Installs the direnv binary. This layer adds the missing piece (the shell hook) for `.envrc` to actually trigger on `cd`.
`/charly-image:layer`	Candy authoring reference.
`/charly-check:check`	`check:` block format reference.

Why a separate candy (and not edits to `keepassxc` or `agent-forwarding`)

The keepassxc candy is consumed by container/desktop boxes where FdoSecrets and autostart make no sense.
agent-forwarding is a clean metalayer (gnupg + direnv + ssh-client) used by 27 application boxes. Adding host-only behavior there would polute every container build that composes it.
Keeping host-only secret-service wiring in its own candy means containers stay containers and hosts stay hosts.

When to Use This Skill

Use when the user asks about:

Making KeePassXC the default Secret Service on a host.
The .envrc + .secrets workflow not triggering on cd (likely missing direnv hook from this layer).
gnome-keyring or kwallet conflicting with KeePassXC over the org.freedesktop.secrets D-Bus name.
Why charly’s keyring backend “can’t find” the user’s KeePassXC database (FdoSecrets plugin disabled in keepassxc.ini).
The charly-cachyos template’s keyring/direnv/gpg block.

/charly-infrastructure:keepassxc — package install (parent dependency)
/charly-infrastructure:gnupg — gpg binary (parent dependency)
/charly-distros:agent-forwarding — sibling: container-side agent forwarding metalayer
/charly-build:secrets — charly secrets and charly secrets gpg CLI surface
/charly-coder:direnv — direnv binary candy (the shell hook this candy adds completes the chain)
/charly-image:layer — candy authoring reference
/charly-check:check — declarative testing reference
/charly-local:local-spec — kind: local template reference (where this candy is composed)
/charly-local:local-deploy — target: local deploy semantics