Vault
The vault is the operating system's own secret store, and monkeys keeps nothing anywhere else. There is no file of monkeys's own to back up, leak or forget,…
The vault is the operating system's own secret store, and monkeys keeps
nothing anywhere else. There is no file of monkeys's own to back up, leak
or forget, and the desktop's own tools see everything monkeys stores.
| platform | vault | reached through |
|---|---|---|
| macOS | the login keychain | Security.framework |
| Linux | whatever answers the Secret Service API over D-Bus: GNOME Keyring on most desktops, KWallet on KDE | secret-tool from libsecret |
What an item looks like
Each secret is one item carrying two attributes: service is monkeys, and
account is <profile>/<KEY>, or <KEY> alone for a key with no profile, so a
project's item reads foo.test/OPENROUTER_API_KEY. The label is monkeys:
followed by the account. Deleting an item in the desktop's tools deletes it
for monkeys.
On macOS that is a generic password in the login keychain. Search Keychain
Access for monkeys, or ask for one by account:
security find-generic-password -s monkeys -a OPENROUTER_API_KEY
security find-generic-password -s monkeys -a foo.test/OPENROUTER_API_KEYItems are created with
kSecAttrAccessibleAfterFirstUnlock,
so a shell that starts while the screen is locked can still read them.
On Linux the same attributes go through secret-tool:
secret-tool lookup service monkeys account foo.test/OPENROUTER_API_KEYThe keychain prompt on macOS
A binary built from source carries an ad-hoc
code signature,
whose identity is a hash of the binary itself. A rebuild changes that
identity, so the keychain may ask you to allow access once when the new build
first reads an item the old one stored. The release builds are what brew
and the install script give you.
The Secret Service on Linux
The Secret Service is a desktop session service. Over SSH or in a container
there is usually no session bus and no secret daemon, and monkeys fails
saying so. Machines like that want a different mechanism, not this one.
Secret
A secret is what a key holds: the API key, token or password itself. It is the only thing monkeys exists to keep, and the only thing it never prints.
Profile
A profile is a named set of secrets. Every secret monkeys stores sits under one, as <profile>/<KEY>, and a project's .monkeys file lists its keys under the…