keysink
English | 简体中文
Pre-1.0: the CLI and route surface may still change between releases; each release's operational notes are in the changelog.
A small local gateway that keeps your real API keys out of your agents. The
agent gets a revocable virtual key (ks_…); keysink holds the real key in an
encrypted local vault and swaps it in only at forward time.
agent ──ks_…──▶ keysink :8787 ──real key──▶ upstream
The threat this exists for
Agents read untrusted content all day: web pages, issue threads, tool outputs,
fetched documents. A single prompt injection away, env | curl … walks your
real key out the door, and you find out from the bill.
There is no read channel for real keys: the CLI cannot print them, export
backups strip them, and the gateway binds loopback only. A dumped environment
is a dumped ks_… — revocable in one command while the rest of your setup
keeps working.
One real key can back many routes: each agent gets its own ks_…, and rotating
a key or switching provider is keysink route update — routes hot-reload in
about a second, so the agent's config is pinned once.
The other channels
An agent runs as you, so it also has your files and your /proc. Measured on
Linux, agent and gateway under the same uid:
| What the agent runs | What it gets |
|---|---|
cat token.txt, .env, ~/.config/*/credentials |
plaintext — the key was never in a vault |
age -d -i vault.key vault.age |
the whole vault, if vault.key is readable |
tr '\0' '\n' < /proc/<pid>/environ |
whatever a launcher injected into a sibling process |
/proc/<pid>/mem, gdb -p, strace -p |
a running program's memory, real keys included |
deploy closes the first two rows with a dedicated uid for the vault. serve
closes the last two on Linux — prctl(PR_SET_DUMPABLE, 0) at startup, so
same-uid reads of /proc/<pid>/* and ptrace get EPERM. Neither helps if
both run in your own uid: then the vault files are simply shared.
docs/security.md
has the details and what to do about them.
Quick start
-
Install — any of these:
cargo installlands in~/.cargo/bin, which sudo can't see. So if you later runsudo keysink deploy, usesudo ~/.cargo/bin/keysink deploy. Prebuilt binaries are also on Releases (Linux / macOS / Windows, amd64 / arm64) — put one on yourPATH. Linux x86_64 needs glibc 2.35+, arm64 needs 2.39+; anything uncovered (musl/Alpine, Windows arm64) falls back tocargo install. -
Start the gateway (standalone — no root, no service):
-
Add a route, in another terminal:
# guided prompts: name → base URL → upstream auth → key (hidden input) # non-interactive: printf %s "$KEY" | keysink route add claude --base-url … --auth x-api-keyIt prints the vkey (only this once) and the two lines your agent needs:
vkey: ks_R6OpUgxRjVnuCwISI0_BgtAi1E8FGUILJHQouA50tYc BASE_URL=http://127.0.0.1:8787 TOKEN=ks_R6OpUgxRjVnuCwISI0_BgtAi1E8FGUILJHQouA50tYcRoutes hot-reload into a running gateway within ~1s, so adding one never requires a restart.
-
Point your agent at it:
ANTHROPIC_BASE_URL+ANTHROPIC_AUTH_TOKENin Claude Code'ssettings.json, providerbase_url+apiKeyfor anything else (OpenAI-style clients usually need/v1in the base URL). The vkey rides in whatever header your client already sends, so for most clients this is a base-URL change and nothing else.
Documentation
| Doc | What is in it |
|---|---|
| usage.md | routing rules, every command and route option, health endpoint fields, vault layout, FAQ |
| service.md | sudo keysink deploy: system user, systemd unit, headless init |
| security.md | threat model, same-uid channels, audit log, bounds and shutdown |
| performance.md | measured overhead and the scripts/perf.sh harness |
What this is not
- Not a secret manager: one user, no RBAC, no HA, no KMS. A team or several hosts want Vault, Infisical or a cloud secrets manager.
- Not an LLM gateway: no token accounting, budgets, model routing, caching or rate limiting. Put LiteLLM or one-api next to it.
- Not multi-machine: one process, one host, loopback.
- Not key pools: one upstream and one key per route, no failover.
- Not a sandbox for the agent: a vkey is a capability.
route disable/rotateis how you take it back. - Not worth the extra hop if your agent never reads untrusted content: a plain
.envis simpler, and nothing here protects you from a teammate.
Development
cargo test includes a seeded fuzz suite (22 targets over the pure helpers, a
vault corruption matrix, and end-to-end fuzz against a mock upstream) plus the
perf harness in perf/ksbench. Pushing a v* tag makes GitHub Actions build
and publish release artifacts for all platforms, plus crates.io and the npm
package once CRATES_PUBLISH / NPM_PUBLISH are enabled (see
docs/publishing.md).
If keysink let you stop pasting API keys into agent configs — or it already
caught the rotation you didn't have to do — a
star helps other people find
it before the leak does. For file-based secrets outside agents, see the
companion tool envpouch: encrypted
.env profiles with the same author.