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:
gocryptfsandfuse3for a shared vault;cryptsetupfor a disk or bootdisk vault on LUKS;zfsutils-linuxfor one on ZFS; KeePassXC anddbus-send(dbus-bin) for a keepass vault - FIDO2 keys speaking FIDO 2.1 at least (
fido2-token -IlistsFIDO_2_1, orFIDO_2_1_PREas on older YubiKey 5 firmware, among its versions) and supporting both resident keys andhmac-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 thetssgroup - 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 thehousekey-bootpackage (orlibcryptsetup-devand 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.