Joe Julian
146 lines
4.0 KiB
Markdown
146 lines
4.0 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
go run .
|
|
```
|
|
|
|
Phone-sized preview:
|
|
|
|
```bash
|
|
go run . -mode phone
|
|
```
|
|
|
|
## Test
|
|
|
|
```bash
|
|
go test ./...
|
|
go tool golangci-lint run ./...
|
|
```
|
|
|
|
KDBX security and KDF compatibility notes are documented in [`docs/kdbx-compatibility.md`](./docs/kdbx-compatibility.md).
|
|
|
|
## Build
|
|
|
|
Desktop build:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
go test ./...
|
|
```
|
|
|
|
Install:
|
|
|
|
```bash
|
|
go get -tool gioui.org/cmd/gogio@latest
|
|
```
|
|
|
|
Package:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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`](./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:
|
|
|
|
```bash
|
|
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`](./docs/browser-extension.md).
|