KeePassBox: Give Your AI Agent Its Own Password Vault

I built KeePassBox to give an AI agent its own password vault without handing it mine. It runs in Docker and serves a real KeePass .kdbx file over MCP. Create a vault, put the agent’s accounts in it, and give the client a token for that owner. The agent can look up entries and, if you grant it permission, retrieve a password or a one-time code. I can still open the same file in KeePassXC or use the REST API from a script.

Say I want an agent to sign in to a staging dashboard. It gets a staging account in its own vault. Giving it access to my personal vault because it needs one damn login would be an impressively stupid shortcut. So would pasting that login into the chat every time I start a session.

I start with a vault I can afford to lose

On a Linux host, install Docker Compose, curl and OpenSSL. Run this as your regular Docker user. The installer sets up Compose and a keepassbox command. Read it before running it; the thing you’re about to install is going to handle your passwords.

curl --fail --silent --show-error --location \
  --output keepassbox-install.sh \
  https://raw.githubusercontent.com/psyb0t/docker-keepassbox/main/install.sh
less keepassbox-install.sh
bash keepassbox-install.sh
keepassbox start

If the command isn’t on your PATH, use ~/.local/bin/keepassbox. The default port is 8000 and Compose binds it to loopback. If it’s taken, pass --port 8010 to the installer and change the port in the examples. keepassbox config prints the directory with the Compose settings, access file and vault data.

Put jq in the same shell for this demo. The installer makes a full-access token for the automation owner. The following uses it locally without printing it. The separate password is for a disposable vault called lab. Keep the password if you want to open that test file again.

KEEPASSBOX_TOKEN=$(keepassbox token)
LAB_PASSWORD=$(openssl rand -hex 24)
kb() {
  curl --fail-with-body \
    -H "Authorization: Bearer $KEEPASSBOX_TOKEN" \
    -H "Content-Type: application/json" "$@"
}
base=http://127.0.0.1:8000/v1/vaults
jq -n --arg password "$LAB_PASSWORD" \
  '{id:"lab",name:"Lab",credentials:{password:$password}}' |
  kb --data-binary @- "$base"
kb --data-binary '{"title":"Demo service","username":"demo"}' \
  "$base/lab/entries"
kb "$base/lab/entries?q=Demo"

Creation unlocks the vault. The last request finds the test entry and returns its ID, title, username, URL, tags, group ID and whether it has TOTP. The demo entry has no password. On a real entry, an ordinary search still doesn’t return the password or notes. The agent can check which account to use without seeing the password.

I don’t hand the agent my token

Two things open different doors here. The bearer token decides which owner and operations a client can access. The vault password, configured key file, or both unlock the encrypted file. Tokens for the same owner share unlocked state. If I unlock a vault over REST and an MCP client for that owner has secrets:read, it can ask for a password without typing the master password again. That makes a full-access token the wrong damn thing to paste into whatever client I installed this morning.

For this demo, add a second client under automation in access.local.json. Give it a fresh random token and just entries:read, then stop and start KeePassBox to load it. That scope can lock a vault and can unlock it if the caller supplies the unlock credentials. For real use, give the agent a different owner from your personal vaults. Tokens cover an owner’s vaults, so making another vault under your own owner won’t isolate the rest. Entry edits and password generation require entries:write, vault creation requires vaults:create, and crypto settings and rekeying require vaults:admin.

A restart locks the vault. Open the lab again from the original shell before asking the MCP client to list its entries:

jq -n --arg password "$LAB_PASSWORD" '{password:$password}' |
  kb --data-binary @- "$base/lab/unlock"

Point the MCP client at http://127.0.0.1:8000/mcp with Streamable HTTP and that scoped bearer token. Ask the agent to find the username for “Demo service” in lab. It can call list_vaults and list_entries and find demo. It can’t reveal the entry’s password with that token.

For the staging login, the agent needs secrets:read if it’s going to ask KeePassBox for the password or a TOTP code. That scope also allows attachment downloads and other secret reads in the owner’s unlocked vaults. KeePassBox accepts a TOTP seed or an otpauth:// URI and returns the current code with its expiry. Once MCP returns a secret, the client has it and may put it in the model’s context or the tool logs. If a script can do the login without showing the password to a model, I’d do that instead.

When I’m done with the lab vault, kb --data-binary '' "$base/lab/lock" drops its unlocked state. Keep the empty body argument: the server expects a content length even for this POST. Unlocked state also expires after ten idle minutes by default. The encrypted file stays put.

I keep the damn KDBX

The installer keeps lab.kdbx under data/automation/ in the configuration directory. If I already have a vault, I can put a copy there and unlock it through the API. I don’t need to turn it into a CSV full of shit I now have to remember to delete. For a key file, put it under that owner’s keys/ directory as <alias>.keyx and pass the alias as keyFile. Use one writer per vault. I stop the service before editing the managed file in KeePassXC.

The file keeps normal KeePass structure. I can create groups, move entries, and edit usernames, passwords, notes, tags and protected custom fields. Ordinary entry edits keep the old version in history; deleting an entry sends it to the recycle bin. Small attachments go into the vault too, up to 32 KiB apiece.

For a fresh KDBX 4 file the default is AES-256 with Argon2id at 64 MiB, three iterations and two lanes. The security settings let me change the cipher, KDF, memory, iteration count, parallelism and compression. I can set Argon2 to 512 MiB under the default cap, but that costs real RAM when the file opens. Rekeying is a separate operation for changing the password or key file. Both settings changes and rekeys require the current revision.

On a write, KeePassBox encrypts a temporary file and opens it again before touching the original. If the original changed on disk, the write fails instead of quietly burying somebody else’s edits. It keeps the preceding encrypted revision as lab.previous. After a rekey, that file still needs the old unlock credentials. It rolls forward with the next write, so I keep separate backups of the vault and key file. A single previous revision is not a fucking backup plan.

I’d still let an agent log in to staging. It can have the staging account. It doesn’t need my email password to get there.

Get KeePassBox on GitHub or use the KeePassBox docs for installation, REST and MCP setup.