PyKeePassGate

The reference client for KeePassGate, a KeePass 2.x plugin that serves a small specification-defined API over mutual TLS so that automation and AI agents can each be given a narrow, revocable, audited slice of a database.

Reference implementation means the code here is the second copy of the specification. Where the plugin and this disagree, one of them is wrong and a test should already have said so. It also means what is missing is a statement: a route with no method here is a route the gate does not serve.

Install

uv add pykeepassgate

One dependency, cryptography, because the gate hands over a PKCS#12 and Python's ssl reads PEM. Everything else, the command line included, is the standard library.

Pair

The operator presses Renew invite on the KPG tab of the database's settings dialog and sends the invitation over a second channel. What they see while doing it is docs/pairing.md, and worked examples of everything below are docs/pykeepassgate.md. It is spent by the first client to use it and it does not survive KeePass closing.

pykeepassgate pair --port 45678 --name agent-invented --profile-name reader

Leave --invitation off and the token is read from standard input, so it stays out of the shell history and out of the process list.

The same thing from a program:

from pykeepassgate import api

credentials = api.pair(
    port=45678,
    invitation="...",
    name="agent-invented",
    profiles=["reader"],
)

print(credentials.profiles)  # what the operator approved, not what was asked for

Use

from pykeepassgate import GateClient

client = GateClient.open()
print(client.status())

pykeepassgate status
pykeepassgate whoami

What to catch

Every exception says what to do next rather than what went wrong, because that is the part a caller has to decide.

What it does not do

It does not open a .kdbx. There is no file and no master password on this side of the API, by design. What that means for anybody expecting a pykeepass object is measured on the spikes/pykeepass-compatibility branch: 23 of its 56 public members are servable over the routes the gate already has, and the object itself is not one of them.

It defends nothing against local code execution as the user. The client's key is on the disk, because a client has to still be the same client tomorrow. The whole design concedes this throughout, and so does this.