OpenVireo started as a fork of KeePassXC, the cross-platform KeePass password manager. KeePassXC is excellent at what it does: a fast, local, account-free app with a decade of history. I wanted something it deliberately doesn’t do: accounts with end-to-end encrypted sync and sharing, an iPhone app and a web app, all working on the same KeePass files.
Building those features was most of the work. But the fork itself, giving it a new name and identity without breaking anything, raised more questions than I expected. This post covers the decisions, and the rules I settled on for what to rename and what to leave alone.
Rule zero: say what it is
Before anything else: OpenVireo says plainly, in the README, the About dialog and the site footer, that it’s a fork of KeePassXC and isn’t affiliated with or endorsed by the KeePassXC Team. Factual attribution is fine, and it’s good manners. Implying endorsement isn’t.
The website even has a comparison page with a section called “Where KeePassXC is ahead”: track record, an independent audit and a security certification, simpler code, and packaging in every Linux distribution. If you only want local files, KeePassXC is the better choice, and the page says so.
What not to rename
The naive version of a rebrand is a global search and replace. There were about 1,000 files mentioning KeePassXC across the desktop app, the website, the browser extension and the backend. Most of them should not change.
1. Copyright and licence notices
KeePassXC is GPL. Every source file starts with Copyright (C) … KeePassXC Team, and the GPL requires keeping those notices. They stay. I add my own copyright line only to files I wrote or substantially changed. More than 500 files in src/ still carry the original header, and that’s correct.
2. Data inside the user’s files
KeePass files carry data that other apps read. The browser integration stores its keys under KeePassXC-Browser Settings, passkeys use KPEX_PASSKEY_* attributes, and so on. Renaming them would make OpenVireo’s files incompatible with KeePassXC, KeePassDX, Strongbox and every other KeePass app, which would break the whole point: your file works in any KeePass app. Those keys stay exactly as they are.
3. Internal code symbols
KPXC_FEATURE_* CMake options, KEEPASSXC_VERSION* macros, namespaces, class names, file names. Users never see them, and renaming them would turn every future upstream merge into a conflict on hundreds of lines. They stay.
4. History
Comments like // See https://github.com/keepassxreboot/keepassxc/issues/803 are accurate history, and the link is the best documentation of why the code is the way it is. They stay.
What did change is everything a user sees or a system identifies the app by: the display name, binary names, the bundle ID, the Linux desktop file and AppStream metadata, the native-messaging host name, the URL scheme, the config directory, environment variable prefixes, and the website.
A clean break
The biggest single decision: nothing migrates. Not the old config, not keychain items, not browser extension pairings. OpenVireo is a new app with its own config directory, and it doesn’t read KeePassXC’s.
That sounds unfriendly, but it was the right call:
- The two apps can be installed side by side without fighting over settings or keychain entries.
- There’s no migration code to maintain, and no half-migrated state to debug.
- What users care about, their
.kdbxfiles, needs no migration at all. They open unchanged.
The clean break also let me change the parts of the protocol I’d already written for accounts. Crypto domain-separation labels, token prefixes and well-known URLs all moved to the new name in one contract change, with the test vectors regenerated, before anyone outside had an account.
Version numbers
A fork has to decide whose version numbers it uses. KeePassXC was at 2.8 when I forked. Calling the first OpenVireo release 2.8.1 would suggest it’s a KeePassXC point release. So OpenVireo has its own SemVer: 0.x for betas, 1.0.0 for the first stable release.
The catch: the browser extension (itself a fork of KeePassXC-Browser) decides which features to enable by asking the desktop app for its version. “Passkeys need KeePassXC 2.7 or later.” Sent 0.9.0, the extension would have turned passkeys off.
So the build keeps a second number, KEEPASSXC_UPSTREAM_VERSION, recording which KeePassXC release the code is based on. The About dialog shows both, and the extension is sent the upstream number. Users see OpenVireo’s version; the code that cares about KeePassXC compatibility sees KeePassXC’s.
Two more constraints shaped the scheme:
- Plain
X.Y.Zonly. The Windows MSI and the auto-update feeds reject suffixes like-beta.1. Betas are marked inside the app (a “Beta” pill) and in the release title instead. - Nightlies sort between releases. A nightly built from 1.0.0 is
1.0.0.26112103(the UTC date and hour), above 1.0.0 and below 1.0.1, so the updater does the right thing on both channels.
Translations
KeePassXC is translated by volunteers on Transifex into dozens of languages. Throwing that away would have been a huge loss, but the translations say “KeePassXC” everywhere.
The approach: script the rename over both the <source> and <translation> strings in the .ts files, limited to user-visible strings. Translations stay marked as finished, so nothing falls back to English. The translation file names (keepassxc_de.ts) keep their upstream names, to keep merges easy.
One trap: a plain build of the browser extension runs tx pull, which downloads fresh upstream translations and silently overwrites the renamed ones. The build has to skip it.
The browser extension’s identity
Chrome identifies an extension by an ID derived from its public key. The desktop app’s native-messaging manifest lists the extension IDs allowed to talk to it, so the two have to agree.
For unpacked development builds, the manifest’s "key" field pins the ID. The Chrome Web Store assigns its own ID unless you upload the private key with the first submission. The store ID and the ID in the desktop app’s allow-list have to match, or every user who installs from the store will find the extension can’t connect. It’s an easy thing to get wrong, and the kind of thing to test with a real store install, not a development build.
Firefox is simpler: the extension declares its own ID (browser@openvireo.com) in the manifest.
Licences beyond the desktop app
The desktop app stays GPL, like KeePassXC. But a fork is rarely one repository. The SDK, CLI and GitHub Action are meant to be embedded in other people’s code, and GPL would stop most companies from using them.
The SDK’s OPAQUE support originally came from a GPL library, which settled the question until I replaced it with opaque-ke (MIT/Apache). After that the SDK could be MIT OR Apache-2.0. The later shared Rust core is the same dual licence, which the GPL desktop app can link.
Worth checking before you publish anything from a fork: what each repository vendors or ports, and under what licence. “Our code is MIT” isn’t true if a dependency in the bundle says otherwise.
Branding
The logo appears in dozens of places: app icons in five formats per platform, the macOS .icns, the Windows .ico, Linux icons in every size, the browser extension, favicons, the iOS asset catalog, social preview images. Updating them by hand is how you end up with one old logo in a corner nobody checks.
I wrote one script that takes a single SVG and generates every icon in every repository, and keeps a snapshot of the originals. Changing the logo is now one command.
Keeping upstream merges possible
The point of leaving internal names alone is that KeePassXC keeps improving, and I want those improvements. Every rename I didn’t do is a conflict I won’t have.
Merging upstream is still real work. The account features touch the main window, the database widget and the settings, and those are exactly the files upstream changes most. Some upstream commits conflict with OpenVireo’s changes and need porting rather than merging. But the conflicts are about features, not about a thousand renamed identifiers.
What I’d tell someone forking a big project
- Say it’s a fork, everywhere a user looks. And be honest about where the original is better.
- Rename what users see. Leave what code and files see. Every internal rename is a merge conflict forever, and every renamed file-format key breaks compatibility.
- Prefer a clean break to a migration when the old and new apps can coexist.
- Decide your version scheme early, and find every place the old version number is used as a feature check.
- Audit licences per repository, including what’s vendored.
- Automate the branding. One source image, one script.