Skip to content

README_EN.md

Latest commit

 

History

History
209 lines (151 loc) · 10.5 KB

README_EN.md

File metadata and controls

209 lines (151 loc) · 10.5 KB
Raw

Monica Local Password Vault

中文 | English | 日本語 | Tiếng Việt | Русский | 黑羽川

Monica App Icon

A local-first password vault that bridges Bitwarden and KeePass

Android / Browser · Local Vault · TOTP · WebDAV Backup

Friend Link: Linux.do Linux.do

Release Downloads Last Commit QQ Group Telegram

Afdian Ko-fi PayPal
JoyinJoester%2FMonica | Trendshift

Monica is a local password vault that aggregates Bitwarden and KeePass. It is built around local-first storage and helps you manage passwords, 2FA, secure notes, and sensitive attachments across Android and browser clients.

This project is AI-assisted. Please build a habit of backing up regularly to avoid data loss. Data privacy is priceless, so do not keep all of your data in a single app.

Website: https://monica-pass.github.io/MonicaDocs/

Monica for Windows is archived. Historical code: Monica-for-Windows

Monica for Browser is archived. The new Monica Extension is currently being rewritten and under active development — stay tuned.

Since the project is currently maintained mostly by me alone, both time and bandwidth are limited. Because of that, Monica for Wear cannot be updated continuously for the time being. My current focus will stay on improving features, experience, and stability for Monica for Android. Thanks for your understanding and support.

User First

Who Monica is for

  • Users who want local-first password management instead of fully hosted cloud storage.
  • Users who work with both Bitwarden data and KeePass (.kdbx) files.
  • Users who need Android daily usage and browser autofill at the same time.

What you get

  • Encrypted local vault for logins, cards, identity data, notes, and attachments.
  • Dual ecosystem integration: Android includes Bitwarden API/sync capability and KeePass (.kdbx) read/write support.
  • Optional sync/backup through your own WebDAV infrastructure.
  • Built-in TOTP management in the same app.

MDBX local database format

MDBX is Monica's local-first encrypted vault format in progress. It is not just a password table; it is designed around nested folders, attachments, commit history, conflict detection, tombstone-based deletion, snapshot recovery, and Tiga security modes.

If you want to integrate MDBX in another client, start with the MDBX workspace README and the MDBX client integration guide. The full format specification lives in mdbx/docs.

Quick install

Android:

  1. Download the latest APK from Releases.
  2. Install on Android 8.0+ and initialize your master password.

Browser extension (Chrome / Edge):

  1. Build from Monica for Browser.
  2. Open chrome://extensions/ and enable Developer mode.
  3. Load unpacked and choose the dist folder.

Known limitation

  • Due to system compatibility constraints, Monica for Android currently cannot create passkeys on some Xiaomi HyperOS devices.

Android Focus

Core capabilities

  • Local vault for credential storage.
  • Aggregated import/integration with KeePass and Bitwarden.
  • Fast search by title, domain, and tags.
  • Biometric unlock with Android system capability.
  • Unified TOTP storage and generation.

Implementation details

  • UI: Jetpack Compose + Material 3 + Navigation Compose.
  • Data: Room (PasswordDatabase) + DAO + Repository.
  • Concurrency: Kotlin Coroutines + Flow.
  • DI: Koin (initialized in MonicaApplication).
  • Security: Android Keystore, EncryptedSharedPreferences, BiometricPrompt.
  • Background tasks: WorkManager (AutoBackupWorker) for automatic WebDAV backup.
  • Protocols and integrations: Retrofit + OkHttp (Bitwarden API), kotpass (KeePass), sardine-android (WebDAV).

Security model

  • Encryption: AES-256-GCM (authenticated encryption).
  • KDF: PBKDF2-HMAC-SHA256 (high iteration parameters).
  • Local protection: master password hash and security settings are managed locally.
  • Network boundary: the app declares network permissions, mainly for Bitwarden integration and WebDAV sync/backup.

Support

If Monica helps your workflow, consider supporting development and security improvements.

Support Monica
Scan with WeChat or Alipay

Support Monica with PayPal

Your support mainly funds:

  • Security hardening and audits.
  • Android UX and stability improvements.
  • Cross-platform consistency and documentation maintenance.

Developer Notes

Project layers (current code layout)

  • takagi/ru/monica/ui: Compose screens and components.
  • takagi/ru/monica/data: Room entities, DAO, database migrations.
  • takagi/ru/monica/repository: data access wrappers.
  • takagi/ru/monica/security: encryption, key handling, authentication-related logic.
  • takagi/ru/monica/bitwarden: API, crypto, mapper, sync, and viewmodel logic.
  • takagi/ru/monica/autofill: Autofill services and flows.
  • takagi/ru/monica/passkey: Android 14+ credential provider implementation.
  • takagi/ru/monica/workers: background tasks such as automatic WebDAV backup.
  • mdbx: Rust workspace and client integration documents for Monica's MDBX local database format.

Mature components currently used (verifiable in repo)

  • Android UI: Jetpack Compose, Material 3, Navigation Compose.
  • Data and state: Room, DataStore Preferences, ViewModel.
  • Security: Android Keystore, EncryptedSharedPreferences, BiometricPrompt.
  • Network and protocol: Retrofit, OkHttp, Kotlinx Serialization.
  • Sync and ecosystem: sardine-android (WebDAV), kotpass (KeePass), Bitwarden API integration.
  • Async and jobs: Coroutines, Flow, WorkManager.
  • Additional capabilities: CameraX + ML Kit (QR scan), Credentials API (Passkey).

Build and contribution

  • Android Studio: latest stable.
  • JDK: 17+.
  • Android config: compileSdk 35, targetSdk 34, minSdk 26 (see Monica for Android/app/build.gradle).
  • Android build baseline: AGP 8.6.0, Kotlin 2.0.21, Compose BOM 2026.03.00 (Material3 aligned by BOM).
  • Version source of truth: Monica for Android/gradle/libs.versions.toml and Monica for Android/app/build.gradle.
  • Browser tech stack: React + TypeScript + Vite (see Monica for Browser/package.json).
  • Contributions via Issues and PRs are welcome.

Acknowledgments

Monica's design, compatibility work, and several feature directions have been inspired and supported by the following excellent open-source projects and software:

  • Keyguard - reference for Android password manager interaction design and UX.
  • Bitwarden - an important reference for the open-source password management ecosystem, vault model, and sync capabilities.
  • KeePass - a foundational influence for the local vault philosophy and .kdbx ecosystem compatibility.
  • Stratum Auth - reference for authenticator experience, icon resources, and related compatibility support.
  • Steam Desktop Authenticator - reference for Steam maFile format, Steam Guard, and trade confirmation compatibility.
  • steamguard-cli - reference for Steam Guard login, authenticator transfer, and confirmation protocol implementation.
  • AnotherVaporAuth - reference for Steam mobile authenticator, login approval, and confirmation UX.

Star History

Star History Chart

Contributors

Contributors

Community and support

License

Copyright (c) 2025 JoyinJoester

Monica is released under GNU General Public License v3.0.

Third-Party Icon Attribution