keepassgo/README.md

KeePassGO

KeePassGO is a Go-based KeePass-compatible password manager targeting desktop first, with future Android support.

Current Capabilities

• KDBX load and save
• password-only, key-file-only, and composite master-key flows through the desktop product UI
• master-key changes for existing vault sessions
• WebDAV-backed open and save support in the session layer
• password generation profiles
• gRPC integration surface for trusted automation
• template, attachment, group, history, and recycle-bin persistence

Run

go run .

Phone-sized preview:

go run . -mode phone

Test

go test ./...
go tool golangci-lint run ./...

KDBX security and KDF compatibility notes are documented in docs/kdbx-compatibility.md.

Build

Desktop build:

go build ./cmd/keepassgo

By default, build outputs stamp the app version from git describe --tags --always --dirty. You can override the version shown in KeePassGO with:

go build -ldflags "-X git.julianfamily.org/keepassgo/internal/appui.appVersion=v0.0.1" ./cmd/keepassgo

Arch Linux Package

An AUR-style package definition for the Linux desktop client lives under:

• packaging/archlinux/keepassgo-git/

From that directory you can build and install it with:

makepkg -si

The package installs:

• /usr/bin/keepassgo
• /usr/bin/keepassgo-browser-bridge
• a desktop entry at /usr/share/applications/keepassgo.desktop
• application icons under the hicolor theme

Android Packaging

KeePassGO uses Gio, so Android packaging is done with gogio.

The repo now has automated tests for the packaging contract:

• default APK build arguments
• required Android SDK / NDK / JDK layout checks

Those are covered by normal test runs:

go test ./...

Install:

go get -tool gioui.org/cmd/gogio@latest

Package:

make apk

make apk prefers a local Java 25 install at JAVA_HOME. If that is not available, it falls back to the repo-managed Docker build image, which also uses Java 25. CI provisions Java 25 directly in the build job so release packaging follows that same local path. You still need the Android SDK and NDK installed and configured for real device or release packaging.

Release package:

make apk-release

make apk-release is the production-signing path. It requires a dedicated release keystore at ~/.config/keepassgo/android-release.keystore and a password file at ~/.config/keepassgo/android-release.pass, unless you override RELEASE_SIGNKEY and RELEASE_SIGNPASS_FILE.

Automation

Desktop automation is resolved through the secure gRPC API rather than synthetic auto-type. See docs/desktop-automation.md.

On desktop, KeePassGO now listens on a Unix socket by default under the user runtime directory. Set KEEPASSGO_GRPC_ADDR or -grpc-addr to override it, for example tcp://127.0.0.1:47777.

MCP Server

KeePassGO includes a stdio Model Context Protocol server for agent and assistant integrations. It connects to the same local authenticated gRPC API used by browser and desktop automation, so existing token policy and approval prompts remain in force.

Build it with:

make mcp-server

Configure your MCP client to run keepassgo-mcp-server and provide an API token through KEEPASSGO_MCP_TOKEN. The server also accepts KEEPASSGO_BEARER_TOKEN for compatibility with existing local gRPC tooling. Set KEEPASSGO_GRPC_ADDR or pass -grpc-addr when KeePassGO is not listening on the default local socket.

The MCP server exposes tools for session status, metadata-only entry search, browser-login matching, and explicit credential retrieval. Metadata tools do not return passwords, notes, or custom field values; credential retrieval uses KeePassGO's credential access policy.

Browser Extension

Firefox and Chromium browser integration is available through the local gRPC API plus a native messaging bridge. See docs/browser-extension.md.