Security, plainly
What we protect, and what we don't.
A key tool that oversells its security is a liability. This page is the threat model, written to be quoted back at us.
The one thing to know
Resolving a reference puts the real key in the child process's environment, or on stdout for kj get. A process running as the same OS user can read both. A reference keeps the key out of files. It does not keep the key from an agent that runs as you.
If you start an agent with kj run, or point its key hook at kj get, that agent can read the key and could print it. KeyJar removes the plaintext copies lying around. It does not sandbox the tool you hand a key to.
What KeyJar protects against
Stray plaintext copies
Keys end up in old .env files, notes, shell history and configs an agent wrote for you, often in files that are gitignored and never pushed. kj scan finds them and groups every location under one key.
Plaintext at rest
A .env file that holds kj://anthropic/main carries no key. A backup, a synced folder or a committed file leaks nothing. Import rewrites only a dotenv line whose whole value is the key, and only after you approve it, file by file. kj undo reverses an import, which puts the plaintext back. Shell history, JSON configs and source files are never rewritten; they are listed with path, line and reason for you to clean up by hand. For most stray copies, that list is most of the work, and the output says so.
The vault file at rest
Keys live in one encrypted file using XChaCha20-Poly1305 with a fresh nonce per write, with subkeys derived by HKDF-SHA256. The 32-byte vault key is held in your OS keychain, not next to the file. Copying the vault file alone gets an attacker ciphertext. works today
Forgotten keys and surprise expiry
KeyJar records when each key was added and when it was last resolved through KeyJar, and Pro reminds you 14, 3 and 0 days before expiry and after 90 idle days, as one summary notification Pro. "Last resolved" only counts uses through KeyJar, so a key used elsewhere can look idle. The field says exactly that.
Mistakes in error output
Error text goes to stderr, never contains key material and never repeats the text you passed as a reference, because people paste keys by mistake. works today
What KeyJar does not protect against
The process you run
kj run puts the real key in that process's environment. An agent you start that way can read it, and so can anything it spawns. KeyJar does not mask output in kj run.
Malware or another process running as you
Code with your user's access can ask your keychain, the same as KeyJar does. KeyJar adds no sandbox, broker or daemon between your user account and your keys. The OS keychain is the boundary.
Keys that already leaked
If a key sits in a public repo, a chat transcript or a paste, rotate it at the provider. Importing it into the vault does not un-leak it.
Spend
KeyJar does not cap usage. Set a spend limit and alerts at each provider as well.
Lost keychain entry
If your OS keychain entry is reset, the vault cannot open. The way back is a recovery file you export in advance with kj recovery export not built yet. The recovery file is the vault key in plain text until you delete it, so keep it off the machine. There is no cloud copy and no account to reset.
Headless machines without a keychain
There is no key-file fallback. On a server with no keychain service, vault commands fail with exit code 4 rather than store the key somewhere weaker.
What a reference does and does not promise
- It is safe to commit, paste and copy into worktrees. It names a key; it does not contain it.
- It resolves only on a machine that has the vault and its keychain entry.
- A resolver never returns the wrong key for a reference it does not understand. It stops with exit code 5.
- It does not make the key unreadable to the program that receives it.
Where your data goes
The vault stays on your machine. No key is sent to KeyJar, and the app itself has no telemetry. This website uses the Ship or Die traffic tracker, described on the privacy page. The app makes two network calls.
- License check. Activating or re-checking a Pro license key contacts the payment provider, Polar, with that license key. No vault key goes with it.
- Pro auto-fill. To read a key's dates, KeyJar sends that key to the provider that issued it, as the credential on a request to that provider's own API:
openrouter.aifor OpenRouter (expiry, usage, limit),api.github.comfor GitHub (expiry),api.x.aifor xAI (created date) andhuggingface.cofor Hugging Face (created date, expiry). A key goes only to the provider its own shape names, never to another host.
Auto-fill is off until you say yes
A Pro license alone sends nothing. KeyJar asks once, in a terminal prompt or in a dialog in the tray app. Until you answer yes, no key leaves your machine. Once on, it asks a provider about a key after you add or import it, and then daily. Turn it off at any time with kj autofill off or the switch in the tray app. kj autofill status shows the current answer. Setting KJ_NO_AUTO_FILL=1 stops it whatever the answer is. Reading and turning off the setting never needs a license.
What this does not cover. The provider sees the request, so it learns that this machine's IP address asked about that key, the same as when your own tools use it. Providers whose keys have no expiry endpoint are never contacted: you type the date.
What you can check, and what you take on trust
KeyJar is a downloadable app, and its source code is not published. You are trusting a binary, so here is what you can verify instead.
- The formats. The kj:// reference spec and the vault format spec are public. You can inspect
vault.kjvon your disk against the second one and confirm it holds ciphertext, not keys. - The download. Every release publishes a SHA-256 checksum for each file. Check it before you run the file. This catches a corrupted or swapped download. It does not tell you what the code does.
- The network. The calls above are the whole list, and auto-fill makes none until you turn it on. You can confirm that with a firewall or a network monitor on your own machine.
What you cannot check yourself today is the code that implements the specs. If that is a blocker, wait, or run KeyJar on a machine and with keys you can afford to rotate. Rotating a key at the provider is always the fallback.