Skip to content

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:

housekey config init

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:

housekey key test

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.

housekey key rename

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:

housekey key init --type tpm2

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:

housekey vault create --type keepass --database ~/mysecrets.kdbx --name mysecrets

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:

housekey vault enrolkey mysecrets

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:

housekey vault enrolkey workfiles

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:

sudo housekey vault create --type disk --dataset tank/secure

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.