Getting started with housekey¶
Installation¶
Install the housekey package from a release, plus the tools for the kinds of vault you will use. See Installation for the packages, the extra tools for each vault type, and how to build from source.
Getting help¶
housekey --help (or housekey -h) lists every command. housekey vault -h lists one target's actions with their options, and housekey vault close -h explains one action.
Press Tab to complete commands, options and vault names (the packages install completion for bash, zsh and fish).
hkey is a short alias for housekey, if you would rather not type the whole name.
housekey status shows, on one screen, what this machine has and can do: the vaults and whether each is open, the keys plugged in, this machine's TPM, and any tool that is missing.
Initialise¶
To get started, run:
This creates your configuration file, ~/.config/housekey/housekey.conf. The most important value in it is the realm name. No secrets are stored in the configuration file: everything in it could be written again by hand. See Configuration for what it holds.
Choose a realm¶
A realm is a name you give to a set of computers and keys that open each other's vaults - your home, or your business. Every key's registration uses the realm as its identifier, so every machine must spell it identically, and it cannot be changed later without enrolling every key again.
A realm name is lower-case letters, digits and hyphens, 1 to 63 of them, not starting or ending with a hyphen. A short name is best: charlie-home or acmecorp, say. A DNS name such as home.myhouse.com is not allowed (dots are not permitted). See Realms.
Prepare your keys¶
You enrol keys on each vault: creating a vault enrols its first key, and you add more afterwards. Some kinds of key need a step of their own first.
FIDO2 security keys¶
FIDO2 keys are small USB devices that provide security-key and passkey functions. YubiKey is the best-known maker, but housekey avoids anything specific to one vendor: Feitian and Token2 keys work too. The key must support FIDO 2.1, resident (discoverable) credentials and the hmac-secret extension - see Requirements. Check a key before you rely on it:
Naming a FIDO2 key is optional, but useful: every time you enrol a key you are asked for a label, and a key that names itself offers its name, so it keeps the same label on every vault. To name it, plug in only that key and run the command below; you are asked for the name, then the key's PIN and a touch.
This machine's TPM¶
The TPM (TPM2) is a security chip in your computer. Not every computer has one. Take care in a virtual machine or remote-desktop session: it may appear to have a TPM that is not a real hardware chip.
Your user needs access to the TPM (on Debian and Ubuntu, install tpm-udev, then sudo usermod -aG tss $USER and log in again). Then create this machine's key and choose its PIN:
See TPM2 keys.
Android and iOS¶
An Android mobile (Android 16 with its QPR2 update or later), or an iPad or iPhone (iOS 26 or later, with a passcode set), running the housekey app can be a key. The app makes its key the first time it runs.
Note
The housekey apps are not yet published in the app stores.
The mobile must be able to reach this machine over the network: open TCP port 8455 in this machine's firewall. See Mobile keys.
Create a vault¶
KeePassXC¶
KeePassXC is open-source software that stores passwords securely in KeePass databases (.kdbx files). With housekey you can secure a KeePass database so that it can only be opened with one of your enrolled keys: no password to remember, and no key file to carry around and back up.
To create a new KeePass database in your home folder:
You are asked to verify your first key, and then KeePassXC opens the new database.
This creates a KeePass database called mysecrets.kdbx in your home folder; to housekey it is a vault called mysecrets. Enrol more keys - three is a sensible minimum - one at a time:
See KeePass vaults.
gocryptfs (a shared folder)¶
gocryptfs makes an encrypted folder that can sit on a shared drive, such as a NAS. With housekey you can secure a gocryptfs vault so that it can only be opened with one of your enrolled keys: no password to remember. Anyone looking at the shared files sees only encrypted files with random names, in folders with random names. When you open the vault you see a mounted folder with the decrypted files inside.
You need two folders: one in the shared location, which holds the encrypted files, and a mount point, which is where the decrypted files appear. In this example the shared folder is /mnt/mynas/workfiles, and the mount point is workfiles in your home folder:
mkdir /mnt/mynas/workfiles
mkdir ~/workfiles
housekey vault create --type shared --name workfiles \
--mount-point ~/workfiles --vault-root /mnt/mynas/workfiles
You are shown a master key (8 groups of 8 characters), which always unlocks the vault, with or without housekey. Be very careful with the master key. housekey can show it again later (housekey vault masterkey workfiles, after verifying a key), so you do not have to record it now, but a copy on paper, kept safely away from the computer, is the recovery that still works if every key is lost. Do not photograph it or save it in a file.
The command creates a shared gocryptfs vault at /mnt/mynas/workfiles and mounts it in your home folder at ~/workfiles; to housekey it is a vault called workfiles. Enrol more keys - three is a sensible minimum:
To use the same vault from another machine, mount the share at the same path there and add it: housekey vault add /mnt/mynas/workfiles. See A vault from another machine.
Disk encryption: LUKS¶
housekey does not create LUKS containers: create the encrypted disk first (with cryptsetup luksFormat, or your installer), then let housekey take it over. Its existing passphrase stays. See Examples and LUKS specifics.
Disk encryption: ZFS¶
housekey can create an encrypted ZFS dataset in a pool that is imported, or take an existing encrypted one over:
See ZFS specifics.
Disk encryption: boot disk¶
A boot disk is encrypted by your installer; housekey then takes it over so that it is unlocked at boot by a key, through the housekey-boot package. It needs dracut. Read Bootdisk vaults before you start.
Open and close a vault¶
housekey vault open workfiles # verify a key, then mount
housekey vault close workfiles # unmount and lock
housekey vault ls # every vault, and whether it is open
A disk vault is root's work, so use sudo housekey vault open NAME for one; a shared or keepass vault is yours, and never needs sudo. See As yourself, or as root.
When several keys could answer, housekey tries a FIDO2 key that is plugged in first, then this machine's TPM, then a mobile (see the order under Mobile keys). --type chooses one outright.