Sync and merge your KeePass/KeePassXC password database over FTP, SFTP, SMB, SCP, or Google Drive. Keeps the remote file up to date; changes on PC or mobile are merged on the next sync.
Languages: Deutsch · English · Español
- Sync & merge KeePass/KeePassXC databases via KeePassXC-CLI
- Protocols (recommended order): 1. Google Drive (rclone), 2. SFTP (prefer over FTP when using FTP protocols), 3. FTP, SMB, SCP
- Platforms: Linux, Windows (incl. WSL2), macOS (x86_64)
- No lftp required on Windows – pure Node.js for FTP/SFTP
- Mobile: Use the same credentials in KeePass2Android, Strongbox, etc.
Requirements: Node.js 18+, KeePassXC (with keepassxc-cli in PATH)
npm install -g keepass-sync
# or from source: git clone https://github.com/benjarogit/keepass-sync.git && cd keepass-sync && npm installQuick setup: Run npm run setup for interactive configuration (recommended for beginners). For Google Drive: cp config.example.gdrive.json config.json then run rclone config.
cp config.example.json config.json
# For Google Drive: cp config.example.gdrive.json config.json
# Edit config.json – see table below| Field | Meaning |
|---|---|
local.localPath |
Path to local .kdbx – same file as opened in KeePassXC. Absolute (e.g. /path/to/keepass_passwords.kdbx) or relative to project dir. |
ftp.type |
ftp, sftp, scp, smb, or rclone/gdrive (recommended: rclone, else sftp) |
ftp.host |
Server (IP or hostname) – not needed for rclone |
ftp.port |
21 (FTP), 22 (SFTP/SCP) |
ftp.user |
Username |
ftp.password |
Password |
ftp.remotePath |
Full path to .kdbx – server path or rclone path (e.g. gdrive:KeePass/keepass_passwords.kdbx) |
keepass.databasePassword |
KeePass master password |
Optional: KEEPASS_DB_PASSWORD env var overrides the master password (safer than storing in config). KEEPASS_LOCAL_PATH overrides the path to the local KDBX.
keepass-sync --test # Test connection (no sync)
keepass-sync # Sync & merge
keepass-sync --status # StatusWrappers: ./linux/sync_ftp.sh · ./mac/sync_ftp.sh · windows\sync_ftp.bat · .\windows\sync_ftp.ps1
Detailed installation & automation (Cron, Task Scheduler, LaunchAgent)
Step-by-step guides for inexperienced users: DE · EN · ES
Includes Cron syntax, Task Scheduler clicks, LaunchAgent setup, and install scripts for Linux/Windows/macOS.
Merge only – no overwrite. Both sources are combined; local and remote entries are merged. Nothing is replaced blindly.
- Backup local database
- Download database from remote (FTP/SFTP/SMB/SCP or Google Drive via rclone)
- Validate downloaded file (reject corrupt or incompatible KDBX)
- Merge with KeePassXC-CLI (
keepassxc-cli merge -s … --same-credentials) - Upload merged database back to remote
The remote file stays current. Mobile: With Google Drive, open the DB directly from Drive. With FTP/SFTP, use the same credentials in KeePass2Android.
If merge fails: Neither local nor server file is modified. Backups in backups/ remain unchanged.
When to sync: After Desktop changes: run keepass-sync --sync. After smartphone changes: save in KeePass2Android first, then keepass-sync --sync on Desktop. In KeePass2Android: close and reopen DB to load sync changes.
With type: "rclone" open the database in KeePass2Android directly from Google Drive (built-in support). Choose the same file as in remotePath, e.g. folder KeePass/keepass_passwords.kdbx. No FTP configuration needed.
In KeePass2Android, Strongbox, etc. use the same values as in config.json: Host, Port, Username, Password, Start directory. Prefer SFTP (encryption; fewer compatibility issues than FTP).
| App field | Enter |
|---|---|
| Host | ftp.host |
| Port | 21 (FTP) or 22 (SFTP) |
| Encryption | FTP or SFTP (ftp.type) |
| Username | ftp.user |
| Password | ftp.password |
| Start directory | Directory part of ftp.remotePath |
Tip: If you have issues with KeePass2Android and FTP: In KeePassXC save as KDBX 3.1. Usually not needed with Google Drive.
- Passwords are never logged – credentials never appear in logs or error messages
- Master password: Use
KEEPASS_DB_PASSWORDenv var instead of storing in config (safer) - KeePassXC-CLI: Password passed via stdin only, never on command line
- config.json: Restricted permissions recommended –
chmod 600 config.json(Linux/macOS) - config.json is in
.gitignoreand never committed to the repository
List the configured FTP/SFTP directory:
npm run open-ftp
# or: node scripts/open_ftp.jsDo I need an FTP server? With Google Drive: no, use rclone. With FTP/SFTP/SMB/SCP: yes, you need server access where the .kdbx is stored.
How does merge work? KeePassXC-CLI merges the downloaded file into your local copy; conflicting entries are combined. Both files use the same master password. Merge only – no overwrite. Data is never replaced blindly.
What if the merge fails? Neither your local database nor the remote file is modified. See Android section for compatibility tips. Backups in backups/ remain safe.
Does it work on Windows without WSL? Yes. Node.js handles FTP/SFTP natively; no lftp or WSL needed.
- Run tests:
npm test - KeePassXC reference:
keepassxc/submodule –git submodule update --init
Version in package.json and Git tags (e.g. v2.0.1) stay in sync. npm package and GitHub releases match.
docs/ – Installation & Automation · Testing · Release-Workflow
| Topic | DE | EN | ES |
|---|---|---|---|
| Installation & Automation | INSTALL | INSTALL | INSTALL |
| Testing | TEST | TEST | TEST |