# Keychain

How credentials are stored in the OS keychain and read by tools.

Credentials (provider API keys, OAuth tokens) are stored through `go-pkg/filesystem/keychain` under service `agenvoy`:

| Platform | Backend |
|---|---|
| macOS | `security` CLI |
| Linux / other | `secret-tool` (libsecret), falling back to a plain `KEY=value` file `~/.config/agenvoy/.secrets` |

When no stored value is found, an environment variable of the same name is used. The service name `"agenvoy"` is fixed and must not change.

The `GET /v1/key?key=<name>` lookup endpoint (loopback-only), which script tools used to fetch a stored value over HTTP, was removed in v1.0.23. A script tool now reads the keychain in-process, in the same order: `security find-generic-password -s agenvoy -a <KEY> -w` on macOS, `secret-tool lookup service agenvoy account <KEY>` then `~/.config/agenvoy/.secrets` on Linux, then the environment variable. `DELETE /v1/key`, `GET /v1/keys` and `POST /v1/keys` remain, behind `localhostOnly()`.