keysink 0.2.3

Local gateway that keeps real AI API keys out of agents (Claude Code, OpenAI, MCP): agents hold revocable virtual keys, real keys stay in an encrypted vault.
Documentation

keysink

English | 简体中文

CI crates.io docs.rs Release License Platforms

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

  1. Install — any of these:

    npm install -g keysink     # prebuilt binary, no toolchain
    cargo install keysink      # from crates.io, needs a Rust toolchain
    

    cargo install lands in ~/.cargo/bin, which sudo can't see. So if you later run sudo keysink deploy, use sudo ~/.cargo/bin/keysink deploy. Prebuilt binaries are also on Releases (Linux / macOS / Windows, amd64 / arm64) — put one on your PATH. Linux x86_64 needs glibc 2.35+, arm64 needs 2.39+; anything uncovered (musl/Alpine, Windows arm64) falls back to cargo install.

  2. Start the gateway (standalone — no root, no service):

    keysink serve      # first run: interactive init (set a master password), then the gateway starts
    
  3. Add a route, in another terminal:

    keysink route add claude --base-url https://api.anthropic.com
    # guided prompts: name → base URL → upstream auth → key (hidden input)
    # non-interactive: printf %s "$KEY" | keysink route add claude --base-url … --auth x-api-key
    

    It 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_BgtAi1E8FGUILJHQouA50tYc
    

    Routes hot-reload into a running gateway within ~1s, so adding one never requires a restart.

  4. Point your agent at it: ANTHROPIC_BASE_URL + ANTHROPIC_AUTH_TOKEN in Claude Code's settings.json, provider base_url + apiKey for anything else (OpenAI-style clients usually need /v1 in 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 / rotate is how you take it back.
  • Not worth the extra hop if your agent never reads untrusted content: a plain .env is simpler, and nothing here protects you from a teammate.

Development

cargo test
cargo build --release
bash scripts/smoke.sh    # end-to-end: fake upstream, forwarding / SSE / retry / hot-reload / export stripping

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.