IvyKey User Guide

Applies to: desktop 1.0 (Fedora and Windows; test build). Last updated: 2026-11-02. IvyKey has not yet been independently audited. Do not use it for real passwords.

1. Read these first

1. There is no password recovery service. Your master password exists only in your head. If you forget it and lose your recovery key, the data in your vault is gone for good — nobody, including the developers, can help.
2. Your data stays on your devices. IvyKey never connects to the internet: no account, no cloud. If your computer breaks or is lost, only a backup you exported yourself can bring your data back.
3. Uninstalling the app or clearing its data deletes the local vault. Export an encrypted backup first.

2. Getting started

1. Open the app and choose a master password on the "Create vault" page. We recommend "Generate passphrase": six random English words. Write it down on paper. A password you make up yourself must be strong; common patterns such as Chinese names plus birthdays or "520/1314" number idioms are rejected.
2. Click "Create". The app tunes the encryption cost to this computer; this takes a second or two.
3. Save the recovery kit: the page shows a 27-character recovery key in 7 groups. Write it down, or click "Print recovery kit…" — it prints only the recovery key and instructions, never a password; use a directly connected printer, not "print to file" — and keep it offline, separately from your backups. Then type back the two groups you are asked for. If you close the window or the screen locks before confirming, a new recovery key is generated and must be confirmed at the next unlock — the last confirmed key is the valid one.
4. You will then be asked to export your first backup (section 5).

Already using IvyKey on another device? On the create page choose "Have a sync copy from another device? Start from a sync copy…", pick the copy exported on the other device and enter that device's master password.

3. Everyday use

• New entry: "+" at the top left (Ctrl+N), then pick a type: login, bank card, ID document, API key, server / SSH, Wi-Fi, software licence or secure note. Each type comes with the usual fields (a bank card has number, expiry, security code, …) and sensitive ones are hidden by default; empty fields are not saved, and every field can be renamed, added or removed.
• Custom fields: each row has, on the right, a "Hidden" switch, multi-line (for certificates, private keys, configs), move up, move down and delete. Hidden fields show only dots in the detail view.
• Expiry date: when editing an entry you can set an "Expiry date", or click "In 3 months" / "In 1 year". The detail view shows the days left; from 14 days before, the password health check lists it.
• Duplicate: "Copy as new entry" in the detail view starts a new entry from the current one (e.g. several accounts at the same company); " (copy)" is appended to the title.
• Secure note: a text-only note whose body is masked by default.
• Generate a password: "Generate" in the entry dialog. Under "Generator options" choose random characters (length, character classes, exclude look-alikes) or a passphrase (number of words, separator, …). The entropy in bits is shown; higher is harder to guess.
• Browse: the sidebar lists all entries, favourites, folders, tags and the trash, each with a count. Folders can be nested: a folder of "Work/Servers" appears as "Servers" under "Work", and selecting the parent also lists entries in its sub-folders. Above the list you can sort by "Name", "Recently modified" or "Recently created".
• Search: the box above the list matches title, username, URLs, tags and folder, within the category selected in the sidebar — never passwords or notes.
• Copy password: the clipboard is cleared after 30 seconds by default; on KDE the password is kept out of the clipboard history.
• Copy hidden fields and secure-note text: each custom field in the detail view has a copy button (bank card numbers are copied without spaces and dashes, ready for web forms), and secure notes have a "Copy note" button. Hidden fields and note text are treated like passwords: cleared automatically and kept out of the clipboard history. Secure-note text cannot be selected and copied by hand; use the button. Good for API keys and tokens.
• Show password: asks for your master password first; for the next 5 minutes you won't be asked again. The plaintext hides itself after 30 seconds. Editing an existing entry, copying it as a new entry, and showing a secure note's text or a hidden field (the show button next to it) work the same way.
• Large password display: the large-display button next to the password shows every character large and numbered (digits blue, symbols orange) so you can type it on a TV or router; same verification, closes automatically.
• Delete: entries go to the trash first and are permanently deleted after 30 days; you can also restore or permanently delete them from the trash.

4. Automatic locking

IvyKey locks immediately — and clears all plaintext from the window — when:

• you have been idle for a while (5 minutes by default; 1–60 minutes in Settings; there is no "never");
• the screen locks, the screensaver starts or the computer goes to sleep;
• you close the window;
• you click the lock button (Ctrl+L).

After 5 wrong master passwords in a row you must wait 30 seconds, and longer after each further mistake. The wait survives restarting the app.

5. Backups

Main menu → "Export sync copy / backup…". The exported file is encrypted exactly like the vault.

• Store it off the computer (USB stick, external drive).
• Do not move it through cloud drives, e-mail or chat apps: that hands the ciphertext to a third party who can try to guess your master password offline.
• Keep backups and the recovery key in different places.
• Export regularly; a banner appears if your last backup is more than 30 days old.

Verify a backup: main menu → "Verify a backup…". The file is fully checked against your vault; nothing is written.

6. Syncing devices (manually)

1. On device A, export a sync copy and carry it to device B on a USB stick.
2. On device B, main menu → "Merge import…" and choose the file.
3. The file is fully authenticated, then a preview shows how many entries will be added, updated, deleted, and which ones conflict.
4. Confirm to write. A history version is saved first, so the merge can be undone.
5. For both sides to be identical, export from B and merge on A as well.

Rules: if only one side changed an entry, the newer version wins; if both changed it, it is a conflict and by default both versions are kept; if one side deleted and the other edited, the entry is kept by default. Data is never silently dropped. A copy older than your vault is reported as such and nothing changes.

Don't merge very old copies: once every device has synced a permanent deletion and the retention period has passed, the deletion record is cleaned up. If you later merge a sync copy or backup exported before that, the deleted entry may come back (nothing leaks; just delete it again). Always sync with a recently exported copy.

Sync history: main menu → "Sync history…" lists when each merge happened, from which device and how many changes it brought.

Different master passwords on the two devices do not affect merging. Afterwards IvyKey offers to switch this device to the other device's master password; you must enter both passwords.

7. History and undo

Main menu → "History…" keeps the last 10 versions (saved automatically before a merge or restore, or manually). A restore is treated as a new change and syncs to your other devices.

8. Master password vs. recovery key vs. key rotation

If you suspect your master password has leaked, changing it is not enough (old backups still open with it). Rotate the vault key:

1. Merge changes from your other devices first.
2. Rotate (enter the current password, choose a new one).
3. Write down and confirm the new recovery key.
4. On other devices use "Replace import", see section 9.
5. Before rotating, IvyKey saves a backup of the old vault in the backups folder of its data directory. That backup still opens with the old password. Copy what you need to offline storage, then delete it under Settings → Automatic backups.

9. Replace import

After another device rotated the vault key, this device's vault can no longer merge with it. Use main menu → "Replace import…":

• choose the new file, enter this device's current master password and the new file's master password;
• your current data is first backed up to the backups folder, then replaced entirely (no merge);
• from now on, unlock with the new file's master password.

9a. Moving from / to another password manager

Import: main menu → "Import from another password manager…", then pick a file:

• KeePass / KeePassXC: the .kdbx file itself, then enter that file's master password. Only password-protected KDBX 4 files are supported (the KeePassXC default); remove key files / hardware keys first or export to CSV.
• Bitwarden: export as .json (not "encrypted JSON") or .csv. Cards and identities become IvyKey bank-card and ID entries.
• Browsers (Chrome, Edge, Firefox), Apple Passwords, 1Password and similar .csv exports.

A preview shows how many entries will be added, which ones look like duplicates (skipped by default) and what will not be imported (attachments, 2FA codes…). Nothing is written until you confirm, and a history snapshot is saved first so you can undo.

Delete the source file right after importing: CSV and unencrypted JSON exports contain plain-text passwords.

Export: main menu → "Export to another password manager…" (master password required):

• KeePass file (recommended): encrypted with a separate export password; opens in KeePassXC, KeePass, Strongbox, Bitwarden and others.
• Plain CSV: no encryption at all. Use only if the target app cannot read KeePass files, and delete it afterwards.

For regular backups use "Export sync copy / backup…" instead.

10. Forgot your master password

On the unlock page choose "Forgot master password? Unlock with recovery key", enter the recovery key (case, spaces and dashes don't matter) and set a new master password. A new recovery key is then shown and must be written down and confirmed; the key you just used no longer opens this vault. Older backups and copies on other devices still open with the old password or old recovery key.

Lost both the master password and the recovery key: the data cannot be recovered.

11. Settings

Main menu → "Settings…" (Ctrl+,):

• auto-lock delay and clipboard clearing delay (making either longer requires your master password);
• "Hide login notes by default" (off by default; when on, a login's notes are hidden like a secure note until you choose Show note; turning it off requires your master password);
• device name (used in copy file names and the sync history);
• system security check: whether the disk holding the vault uses full-disk encryption (LUKS), whether swap is encrypted, whether you are on X11 (where other programs can capture the screen and keyboard), whether key memory is locked;
• automatic backups: count and delete all;
• advanced: increase key-derivation strength (creates a new recovery key; every device that opens this vault must have enough memory).

12. Residual risks (what we cannot protect against)

• A compromised device (malware, keylogger, someone with root access).
• Text that was displayed: shown passwords and notes may linger in the GUI toolkit's memory and cannot be guaranteed to be wiped.
• While a file dialog is open (a few seconds), the protection that stops other programs from reading this process's memory is relaxed so the system file chooser can work; it is restored as soon as the dialog closes.
• Printing the recovery kit: the recovery key passes through this computer's print system and may stay in the print queue for a while; a network printer or "print to file" leaves it elsewhere.
• Clipboard: a copied password is handed to whichever program reads the clipboard; automatic clearing has been verified on KDE (KWin) only.
• Swap: encryption keys are locked in memory and never swapped out, but decrypted entries that were displayed may still reach an unencrypted swap partition. Use full-disk encryption or encrypted swap (Settings → system security check tells you).
• Offline guessing: anyone who obtains your vault or a backup can try to guess your master password offline. A strong master password is your real protection — and the reason not to send copies through cloud services.
• Changing the master password does not invalidate old backups (section 8).

13. Where files are stored

(For the Flatpak, the same folders live under ~/.var/app/nz.xlab.ivykey.IvyKey/.)

Two ways to install on Linux (from our website):

• RPM (for Fedora): updates automatically with your system updates. It runs like any other app, without extra isolation. IvyKey itself has no networking features at all.
• Flatpak: updates automatically. It runs in the system's isolated environment, which guarantees it cannot go online or see your other files.
• The two keep their data in different places and don't share it. Don't install both; to switch, export a sync copy / backup first, then use "Start from a sync copy" or "Replace import…" in the other one.

13a. Windows

The Windows version has the same interface and features as the Fedora version, with these differences (supports Windows 10 version 2004 or later and Windows 11; Windows 10 no longer receives regular security updates, so we recommend upgrading to Windows 11 or enrolling in Extended Security Updates):

• Protection: screenshots, screen recording and Remote Desktop cannot see IvyKey's windows; copied passwords are kept out of clipboard history (Win+V) and cloud clipboard sync and are cleared automatically; locking the session (Win+L) or sleeping locks IvyKey immediately; the input method is switched off while you type the master password; no crash dumps are kept; the vault files are accessible only to you (loosened permissions are tightened at start-up).
• Input methods: ordinary fields such as titles and notes still go through the input method. Chinese input methods with "cloud input" may send what you type to the internet — do not put passwords in notes.
• Other programs under the same account: Windows cannot stop other programs running under the same Windows account from reading IvyKey's memory. Do not install untrusted software, and lock IvyKey when you are done (locking wipes the keys from memory).
• Full-disk encryption: IvyKey cannot detect BitLocker automatically. Check Windows Settings › Privacy & security › Device encryption (or Control Panel › BitLocker Drive Encryption).
• Uninstalling deletes your data: when installed from the package (MSIX), uninstalling IvyKey also deletes the vault. Export a backup or sync copy first.
• File locations: vault and automatic backups in %LOCALAPPDATA%\IvyKey\, settings and state in %LOCALAPPDATA%\IvyKey\config\ (redirected by Windows to the app's private folder when installed from the package).
• Screen readers: the Windows interface cannot be read by Narrator or other screen readers (not supported in 1.0). If you rely on a screen reader, please use the phone or Linux version.

14. Feedback

IvyKey collects no usage data and has no crash reporting. Report problems through the channels published by the project; please do not disclose security issues publicly — see SECURITY.md.