Skip to content

Installation

Each release has packages for Debian and Ubuntu (.deb) and for Fedora (.rpm). You can also build them yourself (see Building the packages).

Package What it is .deb .rpm
housekey the command line, housekey (with hkey as a short alias), and the core product amd64, arm64 x86_64, aarch64
housekey-boot unlocks an encrypted boot disk in the initramfs; needs dracut (not initramfs-tools) amd64, arm64 x86_64, aarch64
housekey-gtk the desktop window (GTK 4) amd64 not yet

Only machines with a bootdisk vault need housekey-boot. It must be the same version as housekey, and it rebuilds the initramfs when it is installed.

From a release

Debian and Ubuntu:

sudo apt install ./housekey_*_amd64.deb
sudo apt install ./housekey-boot_*_amd64.deb   # only for a bootdisk vault
sudo apt install ./housekey-gtk_*_amd64.deb    # the window

Fedora:

sudo dnf install ./housekey-[0-9]*.x86_64.rpm
sudo dnf install ./housekey-boot-*.x86_64.rpm  # only for a bootdisk vault

On arm64, use the arm64 or aarch64 files instead.

Additional tools for each vault type

The packages only suggest the tools for each kind of vault, so install the ones you need yourself:

Vault Debian / Ubuntu Fedora
shared (gocryptfs) sudo apt install gocryptfs fuse3 sudo dnf install gocryptfs fuse3
disk or bootdisk (LUKS) sudo apt install cryptsetup sudo dnf install cryptsetup
keepass sudo apt install keepassxc dbus-bin sudo dnf install keepassxc dbus-tools
on ZFS sudo apt install zfsutils-linux OpenZFS's zfs

housekey status lists anything that is missing, and a command that needs a missing tool tells you which package to install.

Requirements

  • libfido2-1, always: housekey is linked against it
  • Each kind of vault's own tools: gocryptfs and fuse3 for a shared vault; cryptsetup for a disk or bootdisk vault on LUKS; zfsutils-linux for one on ZFS; KeePassXC and dbus-send (dbus-bin) for a keepass vault
  • FIDO2 keys speaking FIDO 2.1 at least (fido2-token -I lists FIDO_2_1, or FIDO_2_1_PRE as on older YubiKey 5 firmware, among its versions) and supporting both resident keys and hmac-secret. A token that speaks only FIDO 2.0 is not supported: housekey has a fallback for it, but it has never been tried on one.
  • For a TPM2 key: a TPM2 (/dev/tpmrm0), tpm-udev, and membership of the tss group
  • For a mobile key: an Android 16 mobile with its QPR2 update or later, or an iPad or iPhone on iOS 26 or later with a passcode set, with the housekey app, on a network one router away at most, and TCP port 8455 open in this machine's firewall
  • For a shared vault, the vault root reachable at the same path on each machine
  • For a bootdisk: dracut, and the housekey-boot package (or libcryptsetup-dev and a Rust toolchain to build it)

The package depends only on libfido2-1. It recommends cryptsetup, sudo and tpm-udev - small, and on nearly every system already - and suggests the rest, which apt does not install by default: a machine that uses one kind of vault, or a rescue disk, gets no other's tools. The Fedora package does the same, with Fedora's names (tpm2-tss, dbus-tools, OpenZFS's zfs). housekey-boot depends on cryptsetup and dracut, and suggests the ZFS tools and OpenZFS's dracut module for a ZFS root. Whatever is missing, housekey status lists it, marked when a configured vault needs it, and a command that needs it says which package to install, with apt or dnf.

Check with housekey key ls. If a connected key is not listed at all, the libfido2 udev rules are missing. It also reports this machine's TPM, whether its key exists, and how many PIN attempts remain.

Building the packages

You need Go, a C compiler and libfido2-dev. The rpm targets also need rpmbuild (from the rpm package). They only package what make built, so they work on a Debian or Ubuntu machine too. housekey-boot also needs libcryptsetup-dev, libtss2-dev, libssl-dev and a Rust toolchain.

git clone https://codeberg.org/jonmusker/housekey-public housekey-cli
cd housekey-cli

make deb-amd64 deb-boot-amd64      # build/housekey_<version>-1_amd64.deb, build/housekey-boot_<version>-1_amd64.deb
make rpm-x86_64 rpm-boot-x86_64    # build/housekey-<version>-1.x86_64.rpm, build/housekey-boot-<version>-1.x86_64.rpm

Then install the files in build/ as shown above. make deb deb-boot and make rpm rpm-boot build both architectures.

To install from the source tree without a package:

make && sudo make install
make plugin && sudo make install-plugin && sudo /usr/lib/housekey/housekey-initramfs   # housekey-boot

make builds natively, and make test runs the tests (the TPM ones against swtpm when it is installed). make arm64 cross-builds inside an arm64 Debian container, because linking libfido2 through cgo needs an aarch64 toolchain and aarch64 headers, and a binary linked against a newer glibc than the target's will fail there. It needs podman or docker, and qemu registered with the host's kernel (sudo apt install qemu-user-static on the host); make binfmt checks it, once per boot.

make deb-amd64 the housekey package; make deb builds amd64 and arm64
make rpm-x86_64 the housekey package for Fedora (needs rpmbuild); make rpm builds x86_64 and aarch64
make rpm-boot-x86_64 the housekey-boot package for Fedora; make rpm-boot builds both architectures
make plugin, make deb-boot-amd64 the boot plugin, and its housekey-boot package; make deb-boot builds both architectures
make plugin-test the plugin's tests, and the end-to-end test with housekey through cryptsetup (root, swtpm)
make phone-sim heft-phone-sim, a mobile with its key in a file, for trying mobile keys without the app

housekey and housekey-boot of one build carry one version, and housekey-boot requires exactly that housekey.

Both builds are dynamically linked against libfido2, so targets need libfido2-1 - which they need anyway, for its udev rules.

The window (housekey-gtk), the Android app and the iOS app are built separately, each against the housekey-cli source checked out beside it.

Shell completion

The packages install completion for bash, zsh and fish, for housekey and hkey. From a source build:

housekey completion bash | sudo tee /usr/share/bash-completion/completions/housekey
sudo ln -s housekey /usr/share/bash-completion/completions/hkey
housekey completion zsh > "${fpath[1]}/_housekey"             # then compinit
housekey completion fish > ~/.config/fish/completions/housekey.fish
ln -s housekey.fish ~/.config/fish/completions/hkey.fish

It completes targets, actions and options from the command table, configured vault names (from the file -c names, if the line has one), the --type values that make sense for the command in hand, LUKS containers for vault add --type disk|bootdisk, and paths wherever an option takes one. The scripts are thin: each asks housekey __complete what can come next, so they never need regenerating when housekey gains a command, and they call whichever housekey was typed. To try a build before installing it, source its script and type its path - the scripts are registered for housekey-amd64 and housekey-arm64 too, so ./build/housekey-amd64 vault <TAB> completes as itself.