kdbx — per-project secrets in KeePassXC vaults, safe to hand an AI agent

kdbx keeps a project's secrets in a per-project, per-environment KeePassXC vault (KDBX4, unlocked by a key file only — no master password) and gets them into the tools that need them without kdbx ever printing them into a transcript, a log file, or your shell history. Discovery is automatic: kdbx walks up from your current directory to a committed .keepassxc.json pointer file, works out which environment is active, and takes it from there. The headline command is kdbx run -- <cmd>, which resolves that environment's variable mappings and injects them into a child process' environment. It replaces .env files as the source of truth; the vault stays outside the repo, so there is nothing secret to accidentally commit.

Every install method below is live — the curl installer, Homebrew, go install, the ghcr.io container image, and the signed release archives (SHA256SUMS + cosign, with reproducible builds). The badge above tracks the current version.

Install

# curl installer — downloads the release archive, verifies its SHA-256, installs to
# ~/.local/bin (override with KDBX_INSTALL_DIR; pin with KDBX_VERSION=v0.3.1)
curl -LsSf https://raw.githubusercontent.com/yarrasys/kdbx/main/install.sh | sh

brew install yarrasys/tap/kdbx                    # Homebrew
go install github.com/yarrasys/kdbx@latest        # from source, needs Go 1.25+
docker run --rm ghcr.io/yarrasys/kdbx:latest --version   # container (FROM scratch)

Windows: download the _windows_ archive from the releases page and put kdbx.exe on your PATH.

Building from source needs Go 1.25 or newer (the KDBX engine and golang.org/x/term both declare a 1.25 floor). Release binaries are static and impose no toolchain requirement on users.

Shell completions:

kdbx completion zsh  > "${fpath[1]}/_kdbx"
kdbx completion bash > /etc/bash_completion.d/kdbx
kdbx completion fish > ~/.config/fish/completions/kdbx.fish
kdbx completion powershell | Out-String | Invoke-Expression

Quick start

1. Commit a pointer file at the repo root. It names the project and its environments; it contains no secrets, so it is safe to check in.

{
  "project": "demo",
  "defaultEnv": "dev",
  "envs": {
    "dev": {},
    "prod": {}
  }
}

An empty env object is fine — kdbx derives the artifact paths from the project and environment name: <keepassxc-dir>/demo/dev.kdbx and <keepassxc-dir>/demo/dev.keyx, where <keepassxc-dir> is $KEEPASSXC_DIR if set, else %LOCALAPPDATA%\keepassxc on Windows, else $XDG_CONFIG_HOME/keepassxc or ~/.config/keepassxc. Set vault and keyFile explicitly if you want them somewhere else; both accept a ${KEEPASSXC_DIR} token and a leading ~.

2. Create the vault and its key file.

$ kdbx init
ACTIVE ENV: dev  vault=/home/you/.config/keepassxc/demo/dev.kdbx  (source: pointer)
created /home/you/.config/keepassxc/demo/dev.kdbx
KEYFILE: /home/you/.config/keepassxc/demo/dev.keyx — back this up; losing it makes the vault unrecoverable.

3. Store a secret and map it to an environment variable. The value never appears on the command line — it arrives on stdin, from --from-env, or from an interactive prompt.

$ kdbx set api/openai --var OPENAI_API_KEY < secret.txt
ACTIVE ENV: dev  vault=/home/you/.config/keepassxc/demo/dev.kdbx  (source: pointer)
modified tracked file .keepassxc.json — review and commit

--var records the mapping in the pointer file, preserving existing key order so the diff stays reviewable:

"dev": {
  "vars": {
    "OPENAI_API_KEY": "api/openai"
  }
}

4. Run something with the secrets injected.

kdbx run -- claude              # the author's actual daily use
kdbx run -- npm test
kdbx --env prod run -- ./deploy.sh

The child inherits your environment plus the mapped variables. Its exit code is passed straight back out. Nothing is written to disk, and the value never appears in your shell history.

Reading is deliberately boring:

$ kdbx list
api/openai
$ kdbx get api/openai
(set, hidden)
$ kdbx check          # every mapping still resolves → exit 0, no output
$ kdbx envs
* dev
  prod

Operations

Every operation accepts --env NAME. Read operations additionally accept --json. Operations marked ✦ print the banner ACTIVE ENV: <env> vault=<path> (source: <src>) to stderr; pure display operations do not.

Integration surfaces:

--json

--json gives read operations a machine-readable stdout. Secret values are never included.

$ kdbx --json list
{"entries":["api/openai"]}
$ kdbx --json envs
{"envs":[{"name":"dev","active":true}],"source":"pointer"}
$ kdbx --json check
{"missing":[],"ok":true}
$ kdbx --json get api/openai
{"path":"api/openai","set":true}

--json with --reveal is rejected (exit 7). On failure, stdout carries {"error":{"op":"check","exit":5,"kind":"Drift"}} alongside the usual stderr line and exit code.

Entry paths