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

An entry path is group/sub/Title[:field]. The field defaults to password. The reserved field names — title, username, password, url, notes, matched case-insensitively — map to the KeePass entry's native attributes; anything else becomes a protected custom property. More than one :, an empty field after :, or an empty / segment is rejected. Variable names passed to --var must match ^[A-Z_][A-Z0-9_]*$.

Environment selection

--env beats $KDBX_ENV, which beats the pointer's defaultEnv, which defaults to dev. kdbx envs and the banner report which of the three won. An environment that isn't in the pointer file is an error (exit 2).

Exit codes

Failures print exactly one stderr line and never a stack trace or a secret. The line carries the stable kind plus kdbx's own message, which is written so that no secret value can ever appear in it:

$ kdbx get api/nope
kdbx: get failed: NotFound: entry not found: api/nope

The text of an underlying third-party error is never shown, since it is not under that rule. Set KDBX_DEBUG=1 to additionally get the full error chain and stack on stderr.

Environment variables kdbx reads: KDBX_ENV, KEEPASSXC_DIR, XDG_CONFIG_HOME, LOCALAPPDATA, KDBX_DEBUG.

Roles — agents read, humans write

kdbx is designed to be safe to hand to a coding agent. The rule is:

• Agent-safe: run, get (masked), list, check, envs, init.
• Human-only: set, delete, mv, import, rekey, export, and get --reveal / get --clip.

An agent can use a credential: kdbx run -- npm test works fine, and kdbx itself never prints the value.

This is a guardrail, not a boundary, and it is worth being precise about why.

The binary does not enforce the split. Possession of the key file is the real boundary: anything that can read the key file can open the vault, whoever or whatever it is. The role split is enforced in harnesses that support hooks, by kdbx guard, and it is advisory everywhere else.

The child command can be pinned, if you choose to. A committed run.allow list in .keepassxc.json makes run refuse any argv not exactly on the list (a human can pass --any; the guard denies it for agents). Be clear-eyed about what that buys: the agent can still edit the pointer in principle, but the guard blocks the obvious edits and the change is a visible diff on a tracked file instead of an invisible one-liner. Without a list, run injects into whatever argv it is handed.

For an environment that deserves ceremony (production, real customer credentials), there is strict mode: kdbx init --mode strict. Strict requires the allowlist, refuses --any and --no-mask outright, writes an audit line for every decision (command and variable names, never values, to a 0600 file next to the vault), and gates injection on a policy hash blessed into the vault with kdbx policy bless — a human-only, interactive command. An out-of-band edit to the policy is refused at the next run instead of silently obeyed. The same rules apply to the MCP server's kdbx_run, which additionally always masks and has no escape hatches at all. A determined agent with your uid can still defeat all of this; what strict changes is that quiet tampering becomes loud. When the output is captured (a pipe, an agent harness, a log), injected values in it are replaced with *** — so kdbx run -- env shows masks, not values, exactly where the bytes were headed for a transcript. A terminal gets raw output, and --no-mask (denied to agents by the guard) restores it for piped human use. Masking matches exact values only: an agent that encodes a value on the way out defeats it, as does a test script edited to exfiltrate. kdbx not printing a secret is a property of kdbx, not of the system it runs in.

What the split actually buys you is that an agent does not stumble into disclosure while doing something else, and cannot author, rotate or export a credential. It does not contain an agent that has decided to read one. If you need that, you need a boundary the agent cannot cross as your user: a separate account, a container, or a broker holding the keys. See issue #11.

kdbx guard reads a PreToolUse payload on stdin and either prints a deny envelope or nothing at all. It always exits 0 — it fails open, so a guard problem can never wedge your agent.

$ echo '{"tool_input":{"command":"kdbx set api/openai"}}' | kdbx guard --hook pretooluse
{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"kdbx role-guard: 'set' is a human-only operation …"}}

$ echo '{"tool_input":{"command":"kdbx run -- npm test"}}' | kdbx guard --hook pretooluse
$ echo $?
0

It blocks two things: agent-issued human-only operations, and non-kdbx programs reaching for *.kdbx / *.keyx files or the KeePassXC config directory (so cat ~/.config/keepassxc/… is denied too). It recognizes kdbx, keepassxc-cli and keepassxc invocations as legitimate.

kdbx mcp applies the same contract to MCP clients: five tools, all read-only. There is no write tool, deliberately.

Agent and editor integration

MCP server — add to .mcp.json (Claude Code) or your client's equivalent:

{
  "mcpServers": {
    "kdbx": {
      "command": "kdbx",
      "args": ["mcp"]
    }
  }
}

PreToolUse hook — Claude Code settings.json or a plugin's hooks.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "kdbx guard --hook pretooluse"
          }
        ]
      }
    ]
  }
}

The kdbx plugin in yarrasys/extensions bundles both, along with the skill documentation an agent loads to learn the contract. That repository is archived and read-only as of 2026-07-30 — the plugin still works, but it receives no updates, issues or PRs. The snippets above are the whole integration; you do not need the plugin to wire kdbx guard or kdbx mcp into an agent.

Security

• The key file is the only secret. There is no master password. Anyone who can read <env>.keyx can open <env>.kdbx. Keep them apart from your repo — the default location (~/.config/keepassxc/<project>/) is deliberately outside it.
• Back the key file up, out of band. Losing it makes the vault unrecoverable. There is no recovery path, by design.
• Watch out for cloud sync. A vault or key file under OneDrive, Dropbox, iCloud Drive or similar is replicated to a third party and to every device on the account. kdbx init warns when it detects this, but does not refuse.
• Vault, key file and exported dotenv files are written 0600 (owner-only ACL on Windows), atomically, and vault saves are crash-safe (temp file → rename, with the previous vault kept as .bak until the rename lands).
• Secret values never reach argv, logs, JSON output, or error text. Intake is stdin, --from-env, or an interactive prompt only.
• Accepted limitation: secret strings are not zeroized in memory (same as the Python implementation). A core dump or a sufficiently privileged local process can recover them.

Vulnerabilities: see SECURITY.md. Please do not open a public issue.

Origin

kdbx began as a Python skill in yarrasys/extensions, a repository now archived. This binary is the canonical kdbx and the Python skill is retired; the design spec that governs compatibility lives here, in docs/kdbx-go-standalone-design.md. Vaults are standard KDBX4 (Argon2, key-file-only), so any vault kdbx writes opens directly in keepassxc-cli and the KeePassXC desktop app; .keepassxc.json pointers and KeePass XML v2 key files are the ordinary formats those tools already use.

A few behaviors were chosen deliberately when porting from the original Python skill:

Bugs & feedback

Found a bug or have a feature idea? Please open an issue. Include kdbx --version, your platform, and redacted reproduction steps — never paste a real secret, vault path, or key file; a description of the shape of the problem is enough.

Security vulnerabilities are the one exception: report them privately through GitHub Security Advisories (see SECURITY.md), not as a public issue.

Contributing

Start with CONTRIBUTING.md for setup and the build/test loop. AGENTS.md (symlinked as CLAUDE.md) carries the repository's rules — the engine boundary, the secret-hygiene invariants, and the test discipline. Read it before opening a PR. CI runs the suite on Linux, macOS and Windows plus go vet, gofmt and golangci-lint.

Participation is governed by the Code of Conduct.

License

MIT — see LICENSE. Dependency licenses are inventoried in NOTICE; the dependency tree is MIT / BSD / Apache-2.0 throughout, with no copyleft component.