KeeStart

Passwordless KeePassXC auto-open via hardware-backed authentication.

KeeStart sets up automatic opening of a KeePassXC main database at login, protected by your device's hardware authentication:

• Windows — Windows Hello (PIN / biometric, TPM-backed)
• macOS — Touch ID / device passcode (Secure Enclave)
• Linux — TPM 2.0 + PIN (hardware anti-hammering)

Your database credentials are stored in a private, tool-owned KDBX vault, encrypted by a master secret that is wrapped by your device's hardware key.

Screenshots

Initialize	Lock Screen	Main Screen
First-run setup	Unlock with PIN/biometric	Entry management + autostart

(Screenshots from Linux; macOS and Windows may look slightly different.)

How It Works

1. Add your database — KeeStart verifies your credentials and stores them in its private vault
2. Mark as active — One database at a time is the active one for auto-open
3. Enable autostart — KeeStart registers to run at login
4. At login — Authenticate with your biometric/PIN → KeePassXC opens with your database

See ARCHITECTURE.md for the full architecture and security design.

Getting Started

There are two first-class ways to get KeeStart:

1. Use a prebuilt artifact (easiest) — download a single file from the latest GitHub Release and run it from anywhere in your user space. No Rust toolchain needed.
2. Build from source (full control) — compile on your machine and install via the per-platform scripts.

Both paths require the platform prerequisites below (TPM/SEP, KeePassXC).

Option A: Prebuilt artifacts

Platform	Artifact	Run / install it
macOS	KeeStart-macOS-<ver>.dmg → KeeStart.app	Open the DMG, drag KeeStart.app to ~/Applications, first launch: right-click → Open once, then sign in to Xcode so the app can self-sign. Remove later with KeeStart.app/Contents/Resources/uninstall.sh
Windows	KeeStart-Windows-<ver>.zip → keestart.exe + install.ps1 + uninstall.ps1	Unzip anywhere; run install.ps1 (installs without compiling, adds PATH + Start Menu shortcut) — this also makes keestart available to your shell, which Windows Hello needs. Remove with uninstall.ps1
Linux	KeeStart-Linux-<ver>.tar.gz → keestart + install.sh + uninstall.sh + setup-caps.sh	Extract; run ./install.sh (installs without compiling, desktop integration + setcap) or run ./keestart directly. Remove with uninstall.sh

On macOS the .app is unsigned in the artifact: on first launch the app itself detects your Apple Development identity, creates a provisioning profile, and codesigns its own bundle — no signing secrets in CI, and a single artifact works for any user. (Your macOS app will show "unidentified developer" on first run — right-click → Open once to allow it.)

On Linux, TPM access requires a one-time sudo setcap cap_dac_override=ep /path/to/keestart (the app surfaces this instruction on the Refused screen if it's missing).

Option B: Build from source

All three platforms follow the same build pipeline. Each step builds on the previous one:

Step	Command	When	Does
1. Setup	./*-support/setup.{sh,ps1}	Once, first time	Checks TPM/SEP/Hello, installs system deps, finds KeePassXC
2. Build	cargo build --release	Every code change	Compiles optimized binary, embeds logo, generates platform icons
3. Post-build	cargo post build --package keestart	macOS: required	Bundles unsigned .app (macOS); sets TPM capability on build output (Linux)
4. Install	./*-support/install.{sh,ps1}	Recommended for daily use	Copies to PATH, desktop icon + .desktop/launcher, production setcap
5. Uninstall	./*-support/uninstall.{sh,ps1}	When removing KeeStart	Removes the binary/app, autostart entry, desktop integration — same script used by artifact installs

Steps 1-2 are required on all platforms. Step 3 is required on macOS (creates the unsigned .app bundle; the app self-signs on first launch), optional on Linux (dev convenience for TPM access). Step 4 is recommended for a permanent installation; Step 5 is identical to the script bundled in the artifacts.

Platform-Specific Requirements

Linux: TPM 2.0, KeePassXC, Rust toolchain, libtss2-dev macOS: Secure Enclave (all modern Macs), KeePassXC, Xcode (for signing) Windows: Windows Hello (enrolled PIN/biometric), KeePassXC, Rust toolchain, Visual Studio Build Tools

After installation or artifact download, run keestart from your terminal (or keestart.exe on Windows) and follow the GUI to add your first database.

Moving KeeStart after setup

If you move the binary/app to a new location, KeeStart self-heals its autostart entry on next launch: the OS login entry is re-registered at the new path automatically. You'll see a one-shot notification when this happens.

Features

• TPM Slot Manager (Linux) — view, select, override, and delete TPM persistent handle slots from the GUI. Accessible from the Locked, Initialize, and Main screens. Shows slot status (Me / Orphaned / Other OS / Other user / Occupied), creation time, and machine/user tags.
• Inactivity auto-lock — the store automatically locks after a configurable timeout (10–300s, default 60s) when there's no user interaction.
• macOS code-signing self-heal — the app detects your Apple Development identity, creates a provisioning profile, and codesigns its own bundle on first launch. A "Signature validity" indicator with a manual "Renew" button is shown in the GUI.
• --uninstall mode — the per-platform uninstall scripts invoke keestart --uninstall before removing the binary. This performs a full hardware + data reset: deregisters autostart, deletes the hardware-backed Protector key (TPM handle / Secure Enclave key / Windows Hello credential), and removes the private store files.

Troubleshooting

Linux

TPM device not found

• Ensure TPM 2.0 is enabled in your BIOS/UEFI settings
• For virtual machines: enable vTPM in your hypervisor (VirtualBox, QEMU, VMware all support it)
• Check with: ls /dev/tpm*

TPM permission denied

• Option A (recommended): sudo usermod -aG tss $USER then log out and back in
• Option B (workaround): sudo setcap cap_dac_override=ep ./target/release/keestart (or let install.sh handle it)
• cargo post build and install.sh both attempt to set this automatically

Autostart not working

• Check that ~/.config/autostart/keestart.desktop exists: it should launch keestart --autostart (an always-on-top GUI window that unlocks and auto-opens your database once)
• Verify an active entry is set in the KeeStart GUI (use "Set active" button)
• If you moved KeeStart, the app updates the autostart entry automatically on next launch — you may see a one-shot "Auto-open was updated" notification
• If KeePassXC has its own "Start KeePassXC at login" enabled, disable it to avoid two instances competing at login

PIN lockout (too many wrong attempts)

• The TPM will refuse further attempts for a recovery period (typically ~30s)
• Wait and retry with the correct PIN — the sealed secret is NOT deleted
• If you forgot your PIN, use the "Reset all" button on the Locked screen

macOS

"Code signing error" / "No Apple Development certificate found"

• Open Xcode → Settings → Accounts → sign in with your Apple ID
• A free Apple Developer account is sufficient (no paid membership needed)
• The app self-signs at runtime on first launch — no manual signing step is needed for the prebuilt artifact. If you're building from source, re-run ./macos-support/setup.sh after signing in

"KeeStart.app is damaged" (Gatekeeper)

• Right-click the app → Open once, or run xattr -dr com.apple.quarantine /path/to/KeeStart.app to clear the quarantine attribute
• The bundled .app is unsigned on purpose: it detects your Apple Development identity and self-signs on first launch (after you sign in to Xcode once), so it only looks unsigned before that first run

Touch ID not responding

• Verify Touch ID is enrolled: System Settings → Touch ID & Password
• Ensure you're running from a signed .app bundle (bare binary = session-only SEP key)
• If the app was moved or the certificate expired (7-day private-team certs), the app re-signs itself automatically on next launch — you may see a "Signature validity" indicator in the GUI with a manual "Renew" button

Windows

"No usable hardware-backed authentication was found"

• Windows Hello must be enrolled: Settings → Accounts → Sign-in options → set up a PIN or biometric
• Windows Hello may show as "Unavailable" over Remote Desktop — use a local/console session

KeePassXC not detected

• Install from keepassxc.org
• Use the "Re-detect" button in the KeeStart GUI to scan PATH and known locations

Build fails with "link.exe not found"

• Install Visual Studio Build Tools → select "Desktop development with C++"
• Restart your terminal after installation

Autostart not working

• Check HKCU\Software\Microsoft\Windows\CurrentVersion\Run for the KeeStart entry (should launch keestart --autostart)
• Verify an active entry is set in the KeeStart GUI (use "Set active" button)
• If you moved keestart.exe, the app updates the autostart entry automatically on next launch
• If KeePassXC has its own "Start KeePassXC at login" enabled, disable it to avoid two instances competing at login

Security

• Secrets via stdin only to KeePassXC — never as command-line arguments
• Master secret is CSPRNG (≥256-bit), stored only as a hardware-wrapped blob
• Mandatory hardware-throttled auth — no software fallback
• No network, telemetry, or IPC — minimal attack surface
• See SECURITY.md for vulnerability reporting and the threat model

Documentation

• ARCHITECTURE.md — Architecture, security model, and implementation phases
• SECURITY.md — Security policy and threat model
• CONTRIBUTING.md — Build workflow and coding standards
• CHANGELOG.md — Release history

License

MIT — see LICENSE

Disclaimer

KeeStart is provided "as is", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose, and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages, or other liability, whether in an action of contract, tort, or otherwise, arising from, out of, or in connection with the software or the use or other dealings in the software.

KeeStart is an independent, community-developed tool and is not affiliated with, endorsed by, or sponsored by the KeePassXC project, KeePassXC team, or any of its contributors. "KeePassXC" is a trademark of its respective owners. KeeStart does not modify, patch, or redistribute KeePassXC — it only launches it as a separate, unmodified application.

Use at your own risk. KeeStart manages access to your password database credentials. While it is designed with security in mind, no software is perfect. You are responsible for:

• Keeping your KeePassXC database files and master passwords safe
• Understanding that a hardware failure, TPM reset, or OS reinstall may invalidate the hardware-bound secret and require re-setup
• Ensuring you have appropriate backups of your KeePassXC database files
• Reviewing the SECURITY.md threat model before relying on KeeStart for critical access