keysink
English | 简体中文
A tiny local gateway that keeps real API keys away from your agents. The agent only ever holds a revocable virtual key (ks_...); keysink stores the real keys encrypted on your machine and injects them only when forwarding a request.
There is no read channel for real keys: the CLI cannot print them, backups strip them, and the gateway binds loopback only.
Quick start (download & run)
-
Grab the binary for your OS from Releases — Linux / macOS / Windows, amd64 / arm64. Make it executable and put it on your
PATH. -
Start the gateway (standalone mode — no root, no service):
# first run: interactive init (set a master password), then the gateway starts -
Add a route (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-keyroute addprints the two lines your agent needs. Routes hot-reload into a running gateway within ~1s. -
Point your agent at it:
BASE_URL=http://127.0.0.1:8787 TOKEN=ks_...Claude Code:
ANTHROPIC_BASE_URL+ANTHROPIC_AUTH_TOKENinsettings.json. Other clients: providerbase_url+apiKey.
Vault lives at ~/.local/share/keysink (Windows: %LOCALAPPDATA%\keysink). Move it with --home or KEYSINK_VAULT_HOME. The master password is only used to encrypt/restore export backups — serving, adding and rotating keys never ask for it.
Linux system service (systemd)
One shot — the binary installs itself: creates the keysink system user and a 0700 vault dir, copies this binary to /usr/local/bin/keysink, writes the systemd unit and the sudoers rule (for the admin invoking sudo), initializes the vault interactively (hidden password, entered twice), then enables the service. Idempotent — re-running upgrades in place and restarts. Removal is symmetric: sudo keysink uninstall.
The unit refuses to start until the vault exists (ConditionPathExists). Without a terminal, init manually:
Admin commands then go through sudo -u keysink keysink ...; each invocation re-authenticates (timestamp_timeout=0), so agents can't silently run them.
Everyday commands
keysink route add|ls|show|rotate|update|rm|enable|disable
keysink serve [--listen 127.0.0.1:8787] [--audit-log FILE]
keysink status | doctor
keysink export --output FILE # needs master password; strips all key values
keysink rekey [--yes] # rotate the vault master key
keysink uninstall [--yes] # remove the vault; system installs also lose unit/sudoers/binary
keysink deploy # one-shot system install (Linux + systemd, via sudo)
Route options worth knowing:
--auth bearer|x-api-key|<custom-header>|basic|query|none— OpenAI uses Bearer, Claudex-api-key, Geminix-goog-api-key--header 'K:V'injects static headers;--proxy URL|directsets a per-route upstream proxy (default: followHTTP(S)_PROXY)- Retries 429/503/504 twice; POST network errors are never replayed (no double billing); no retries once SSE streaming has started
Security model: keys go in, they don't come out
| Channel | Key values |
|---|---|
route ls / route show |
masked |
| CLI read command | does not exist |
export backup |
stripped by design |
| agent process | only ever sees the vkey |
| upstream | real key injected at forward time; inbound auth headers stripped |
Vault files are age-encrypted, 0600/0700, owned by the service user. Root that can read both vault.key and vault.age can still decrypt offline — machine-level isolation stays your job (tight sudo, separate UID). Optional --audit-log records route, vkey fingerprint, status and latency — never headers, body or query.
Limitations: one upstream + one key per route (no pools / failover); audit off by default.
FAQ
Why isn't the vault stored in the current directory?
The vault lives at ~/.local/share/keysink (Windows: %LOCALAPPDATA%\keysink, system installs: /var/lib/keysink) on purpose:
- One vault per user, not per directory. The gateway runs as a daemon while the CLI is invoked from anywhere. A CWD-relative vault would give you a different vault per directory — routes would "vanish" and hot-reload would break. Use
--homeorKEYSINK_VAULT_HOMEwhen you explicitly want another location. - The security model needs a directory it controls. The 0700/0600,
O_NOFOLLOWand owner-follow checks only mean something in a dedicated directory. CWD has arbitrary permissions — and may well be a git repo or a cloud-synced folder wherevault.key+vault.agecould leak. - It's where the OS expects app data. XDG
$XDG_DATA_HOMEon Linux/macOS,%LOCALAPPDATA%on Windows,/var/libfor system services (FHS) — the same convention as~/.ssh,~/.gnupgor/var/lib/docker.
Development
Pushing a v* tag makes GitHub Actions build and publish release artifacts for all platforms.