Open-source protection from leaked API keys.
A self-hosted proxy that keeps your real API keys and hands apps virtual ones you can lock, watch, and kill.
Install · Try it · Quickstart · Platforms · Contain a leak · CLI · Docker · Security
API keys leak. They get committed to repos, pasted into CI logs, baked into images, and copied from laptops. Keman makes a leaked key worth much less, and easy to kill.
Keman sits between your apps and the provider. Apps send a kmn_… virtual key, and Keman checks it and forwards the request upstream with the real credential. The real key never leaves Keman, so when a virtual key leaks:
- It may not work at all. Lock each key to the addresses or countries it is used from. A copy used from anywhere else is refused.
- It stops working on its own. New keys expire after 90 days by default.
- You hear about it. Use from a new country or network, request and spend spikes, repeated blocked requests, and use of a disabled key raise alerts to Slack or a signed webhook. Each alert says who called and from where, and gives the exact command to respond.
- Decoys catch the thief. Canary keys never forward anything. Plant one in a repo or CI config, and any use raises a critical alert.
- You kill it in one step.
keman key rotate laptop --grace 0issues a replacement with the same policy and revokes the leaked key. The real provider key stays the same, and so does every other app.
It is a single Go binary with pure-Go SQLite, so it needs no CGO. It ships presets for 21 platforms, among them OpenAI, Anthropic, OpenRouter, Gemini, Groq, Mistral, DeepSeek, xAI, Stripe, GitHub, Slack and Twilio (the full list is under Supported platforms). Any other HTTP API that authenticates with a header or HTTP Basic works too. It runs on Linux, macOS and Windows, does not phone home, and is Apache-2.0.
Beta. The spec is
beta.md. Decisions the spec left open are indocs/ASSUMPTIONS.md. Changes are inCHANGELOG.md.
macOS and Linux:
curl -fsSL https://raw.githubusercontent.com/kirank55/keman/main/scripts/install.sh | shThe script picks the binary for your OS and CPU, checks its SHA-256 sum (and its cosign signature, if cosign is installed), and installs it to /usr/local/bin or ~/.local/bin. Read it first if you like: scripts/install.sh.
Other ways:
| Go 1.22+ | go install github.com/kirank55/keman/cmd/keman@latest |
| Docker | docker pull ghcr.io/kirank55/keman:beta (see Docker) |
| Windows, or by hand | Download keman_<os>_<arch> from Releases. Every binary has a SHA-256 sum, an SBOM, and a cosign signature (how to verify). |
| From source | git clone https://github.com/kirank55/keman && cd keman && make build |
1. Find the keys you already leaked. No server, no setup (more on scan):
keman scan . --history2. See a week in the life of a team using Keman, without a provider key. From a clone of this repo:
./scripts/demo.sh
KEMAN_ADMIN_TOKEN="$(cat .demo/admin.token)" .demo/keman --config .demo/keman.yamldemo.sh builds Keman and seeds .demo/ with seven keys, a week of normal traffic, and the incidents Keman exists to catch: a stolen key draining spend from a new country, a locked key tried from outside its network, a disabled key back in use, a provider key revoked upstream, a decoy that fired, and probes for endpoints a key may not call. Everything runs locally against a mock upstream. Alerts land in .demo/alerts.jsonl, and every address is from a documentation range.
3. Put your own keys behind it. See the Quickstart.
keman scan looks for OpenAI, Anthropic, OpenRouter, Groq, xAI, Stripe, GitHub, Slack, SendGrid, Linear, Google and AWS keys, and Keman virtual keys. For each one it prints the preset that puts the key behind Keman. With --history it checks every commit on every branch as well as the files on disk:
keman scan . --historyfound 1 secret in 2 places
OpenAI sk-proj-…x7Yq
.env:4
config/dev.env:2 (commit 3f9c1a2b7d10)
Move it behind Keman so apps only ever hold a virtual key:
keman upstream add --preset openai (once)
keman credential add --upstream openai --name openai-main --secret-env OPENAI_API_KEY
keman key create --credential openai-main --name <app> --expires 90d
It is in git history, so treat it as leaked: rotate it at OpenAI too.
Secrets are shown redacted. The exit code is 3 when anything is found, so keman scan can gate CI. --json prints machine-readable findings. Put keman:allow on a line to skip a test fixture.
Install Keman, then:
keman init # prints the admin token once; writes keman.yaml and master.key here
keman # opens the terminal UI and starts the proxyIn the UI:
- Paste the admin token from
init. It is masked and kept only in memory. SetKEMAN_ADMIN_TOKENto skip this prompt. - Press
ato add an upstream. OpenRouter is filled in as a suggestion. Use ←/→ on platform to pick any of the supported platforms, or acustomentry to type the host yourself. Every field can still be edited. - The credential form opens. Type the provider API key (masked), or read it from an environment variable. It is stored encrypted and never shown again.
- The new-key form opens. The
kmn_…virtual key is shown once. Copy it. It expires in 90 days unless you change that withp.
Leave the UI open: quitting it (q) stops the proxy it started. To keep the proxy running without the UI, run keman serve. When a server is already up, keman connects to it and leaves it running on exit.
Run keman from the directory where you ran init, or pass --config path/to/keman.yaml.
Send the virtual key wherever the app expects its API key, and change the base URL to Keman's address plus the platform's path. The table under Supported platforms lists the base URL for each one; for example:
| Client | Base URL |
|---|---|
| OpenAI Python / Node SDK | http://127.0.0.1:8080/v1 |
| OpenRouter through Keman | http://127.0.0.1:8080/api/v1 |
| Anthropic SDK | http://127.0.0.1:8080 |
curl http://127.0.0.1:8080/api/v1/chat/completions \
-H "Authorization: Bearer $KEMAN_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"openai/gpt-4o-mini","messages":[{"role":"user","content":"hi"}]}'Back in the UI, select the key and press Enter to see who called it and from where. Then press p and lock it to the addresses your app runs from: a copy used from anywhere else is refused.
./scripts/demo.sh seeds a full demo install (see Try it). For a minimal end-to-end check instead:
./scripts/quickstart.shThe script builds Keman, initializes .quickstart/, starts a mock OpenAI server, creates a virtual key, sends one request through the proxy, then fires an allowlist detection with keman detection test --live. It prints the command to open the UI on that install. Set KEMAN_QUICKSTART_PROXY_PORT and KEMAN_QUICKSTART_ADMIN_PORT if 8080 or 8081 is taken.
A preset fills in an upstream for a known platform: its host, TLS, path allowlist, and the auth header its credentials use. LLM platforms track tokens and spend, and can have spend caps. The others count requests and are limited to the paths their preset allows.
| Platform | Preset | Tracks | App base URL |
|---|---|---|---|
| OpenAI | openai |
tokens and spend | http://127.0.0.1:8080/v1 |
| Anthropic | anthropic |
tokens and spend | http://127.0.0.1:8080 |
| OpenRouter | openrouter |
tokens and spend | http://127.0.0.1:8080/api/v1 |
| Google Gemini (OpenAI-compatible) | gemini |
tokens and spend | http://127.0.0.1:8080/v1beta/openai |
| Groq | groq |
tokens and spend | http://127.0.0.1:8080/openai/v1 |
| Mistral | mistral |
tokens and spend | http://127.0.0.1:8080/v1 |
| DeepSeek | deepseek |
tokens and spend | http://127.0.0.1:8080 |
| xAI (Grok) | xai |
tokens and spend | http://127.0.0.1:8080/v1 |
| Together AI | together |
tokens and spend | http://127.0.0.1:8080/v1 |
| Fireworks AI | fireworks |
tokens and spend | http://127.0.0.1:8080/inference/v1 |
| Cerebras | cerebras |
tokens and spend | http://127.0.0.1:8080/v1 |
| Stripe | stripe |
requests | http://127.0.0.1:8080 |
| GitHub | github |
requests | http://127.0.0.1:8080 |
| Slack | slack |
requests | http://127.0.0.1:8080/api |
| Twilio | twilio |
requests | http://127.0.0.1:8080 |
| SendGrid | sendgrid |
requests | http://127.0.0.1:8080 |
| Resend | resend |
requests | http://127.0.0.1:8080 |
| Postmark | postmark |
requests | http://127.0.0.1:8080 |
| Cloudflare | cloudflare |
requests | http://127.0.0.1:8080/client/v4 |
| Linear | linear |
requests | http://127.0.0.1:8080 |
| Notion | notion |
requests | http://127.0.0.1:8080 |
keman upstream presets # this list, with the host and the key variable for each
keman upstream add --preset groq # name, host, TLS and paths from the preset
keman credential add --upstream groq --name primary --secret-env GROQ_API_KEY- Any flag overrides the preset:
--name,--host,--port,--no-tls, and--path(which replaces the preset's allowlist).--profilemust match the preset's. - The credential's auth comes from the preset:
x-api-keyfor Anthropic,Authorization: {key}for Linear,X-Postmark-Server-Tokenfor Postmark, HTTP Basic for Twilio, and a Bearer token for the rest.--header,--authand--usernameoverride it. - Twilio takes the secret as
AccountSID:AuthToken, unless you pass--username. - Apps can present the virtual key the way their SDK already sends its key: as a Bearer token, GitHub's
tokenscheme,x-api-key, the username or password of HTTP Basic, or a provider header such asX-Postmark-Server-Token. Keman removes that header before it forwards the request. - A platform without a preset still works with
--profile openai,anthropicorgenericand your own host and paths.
The key list shows what matters if a key leaks: its lock (ip, country, decoy, or open when it works from any address), how many rules fired on it in the last 7 days, when it expires, and where it was last seen. A banner counts the keys that are open to every address, never expire, or sit unused.
Open a key to see its exposure findings with the command that fixes each one, who may use it, every client address that called it, its detections, and its recent requests. Spend and models appear only for LLM upstreams.
| Press | To |
|---|---|
1–4, tab |
switch view: keys, detections, audit, setup |
j/k, arrows |
move or scroll |
enter |
open a key (also from a detection or an audit row) |
p |
policy: allowed addresses and countries, expiry, abuse mode, requests per minute, and daily and monthly caps in dollars for LLM keys |
r |
rotate: new key with the same policy; the old one stops after 24 hours, 1 hour, 7 days, or now |
n |
new virtual key (standard or canary) |
d / e |
disable / enable (reversible) |
x |
revoke (permanent; type the key's name to confirm) |
a / c |
add an upstream / a credential |
/ |
filter the current view |
? |
help |
q |
quit, except while typing in a field. ctrl+c always quits. |
Switching a key to auto_disable shows the 7-day dry run first and asks for confirmation. scan, exposure, canary snippets, credential rotation, rekey, admin-token rotation and alert destinations are on the CLI.
| Situation | Command |
|---|---|
| A key leaked | keman key rotate laptop --grace 0: the app gets a replacement and the leaked copy is revoked now |
| Planned rotation | keman key rotate laptop --grace 24h: both keys work for a day, then the old one expires |
| Not sure yet | keman key disable laptop, and keman key enable laptop to undo |
| Find keys that are easy to abuse | keman exposure lists keys open to every address, without expiry, or unused for 30 days, with the fix for each; --strict exits 3 |
| Lock a key down | keman policy set laptop --cidr 203.0.113.0/24 --country US |
| Change expiry | keman key expiry laptop 30d (or 2026-12-31, an RFC3339 time, or never) |
| Plant a decoy | keman canary create --credential primary --name repo-decoy --base-url https://keman.example.com >> .env |
canary create prints only the lines a thief would expect, such as OPENAI_API_KEY=kmn_… and OPENAI_BASE_URL=https://keman.example.com/v1, so it can be appended straight to the file you plant it in. The base URL must reach your Keman proxy, or the canary cannot fire.
Alerts lead with the leak response. For a standard key, they offer rotate-and-revoke first, then disable, and only then the commands that allow the address or country that triggered them, in case it was you. A canary alert tells you to rotate the real secrets that were stored next to the decoy.
Every operation is also a one-shot command, for scripts:
export KEMAN_ADMIN_TOKEN=kma_...
# Set up
keman upstream presets
keman upstream add --preset openai
keman upstream add --preset twilio
keman upstream add --name internal --profile generic --host api.internal.example --port 443 --tls --path "GET /v1/**"
keman credential add --upstream openai --name primary --secret-env OPENAI_API_KEY
keman credential add --upstream twilio --name sms --secret-env TWILIO_CREDENTIALS # AccountSID:AuthToken
keman key create --credential primary --name laptop # expires in 90 days
keman key create --credential primary --name ci --expires 30d
keman key create --credential primary --name decoy --kind canary
# Lock down
keman policy set laptop --cidr 203.0.113.7/32 --rpm 60
keman policy set laptop --mode auto_disable --yes
keman policy dry-run laptop
keman key expiry laptop 2026-12-31
keman exposure --strict
# Respond
keman key rotate laptop --grace 24h
keman key disable laptop
keman key enable laptop
keman key revoke laptop
# Detect
keman scan . --history
keman detection test
keman detection test --file events.jsonl --learned --expect spend_spike,new_country
keman canary create --credential primary --name repo-decoy --base-url https://keman.example.com
keman alert add --kind webhook --url https://example.invalid/hook --secret-file ./hook.secret
# Maintain
keman credential rotate primary --secret-env OPENAI_API_KEY
keman rekey --old-master-key-file ./old --new-master-key-file ./new
keman helpKeys, credentials and upstreams can be referred to by name or id. Pass secrets with --secret-env or --secret-file, never on the command line. Global flags (--config, --admin-url, --admin-token) work before or after the subcommand. Without --admin-url, the CLI uses admin_listen from the config, including unix:// sockets. After init, every change goes through the admin API, so a running server never holds a stale copy.
The proxy listens on 0.0.0.0:8080. The admin API and /metrics listen on 127.0.0.1:8081 and require the admin token. Server settings live in keman.yaml; see examples/keman.yaml. On Ctrl+C or SIGTERM, serve and the UI flush spend and drain the event queue before exiting.
- Rules: rate spike, spend spike, new country, new ASN, repeated allowlist violations, a burst of upstream auth errors, use of a disabled or revoked key, and canary use.
- A new key learns for 7 days or 500 requests before the spike and new-location rules alert. Normal traffic does not create detections.
- Canary keys (
--kind canary) answer with the profile's own 401 and raise a critical alert. They never reach the upstream. - Country and ASN rules, and country allowlists, need a GeoLite2 or DB-IP
.mmdbfile ingeoip_country_dbandgeoip_asn_db. trusted_proxiesis empty by default.X-Forwarded-Forfrom anyone else is ignored and is not sent upstream. All address rules use one client IP.- New standard keys expire after
default_key_ttl(default2160h, 90 days). Set it to0sto turn the default off. - OpenAI and Anthropic have built-in path allowlists, and every preset ships one. A custom generic HTTP upstream requires one, so a leaked key for a generic upstream can only call the endpoints you listed. Paths with
.or..segments or backslashes never match, so/v1/customers/../payoutscannot slip pastGET /v1/customers/*.
keman detection testreplays built-in abuse scenarios and prints what would alert, including whether auto-disable and dry-run would trip. It runs on a fresh engine: it does not start the proxy, deliver alerts, or change a key. Exit code 1 means a scenario missed its expected result.keman detection test --live --secret-file virtual.keyneeds a running server. It sends five requests to a path the allowlist refuses, then waits untilallowlist_violationsis stored.--proxyoverridesproxy_listenfrom the config../scripts/quickstart.shruns this against.quickstart/.keman detection test --file events.jsonlreplays your own events, as a JSON array or as JSONL. Use-to read stdin.- Each object can set
time,key_id,kind,ip,country,asn,status,cost_micro,model,blocked_code, andmode(alert_onlywhen omitted). --learnedseeds every key with a baseline that is past learning: 500 requests, country US, ASN 64500, first seen 8 days before that key's first event.--expect rate_spike,new_countryexits 1 when one of those rules does not fire.--expect-disableexits 1 unless auto-disable would disable the key. That requiresmode: auto_disableon the events.
- Each object can set
Runaway spend is often the first sign of a stolen LLM key, so keys on an LLM upstream (OpenAI-compatible or Anthropic, which covers every platform that tracks tokens and spend) can also have daily and monthly caps.
-
Money is stored as integer microdollars. Prices ship in
internal/price/prices.json(snapshot 2026-10-29). Itsmodelssection is global. Itspresetssection holds prices for one platform, such asgroqortogether, and wins overmodelsfor upstreams made from that preset, since the same model id can cost different amounts on different platforms. -
A model that is not in the price table is recorded with no cost. If the key has a spend cap, the request is refused with
unknown_model_price. That includes OpenRouter'svendor/modelids. To cap those keys, add prices withprices_file, globally or under a preset. Prices are microdollars per million tokens, and the key is themodelstring exactly as the app sends it:{ "version": "local", "models": { "gpt-4o-mini": {"input": 150000, "output": 600000} }, "presets": { "openrouter": { "openai/gpt-4o-mini": {"input": 150000, "output": 600000} } } } -
Generic HTTP does not support model allowlists or spend caps.
-
Caps are reserved before the request and reconciled from usage. A missing usage object on a completed model response charges the reservation and marks it estimated. A dial failure, a blocked cross-host redirect, or a 3xx that is passed through releases the reservation.
-
If spend flushes fail for 60 seconds, keys that have a cap get
503 store_unavailable.
docker volume create keman-data
docker run --rm -v keman-data:/home/nonroot ghcr.io/kirank55/keman:beta init
docker run --rm -p 8080:8080 -v keman-data:/home/nonroot ghcr.io/kirank55/keman:beta serveThe image is multi-arch (amd64, arm64), distroless, runs as non-root, and is signed with cosign. To build it yourself: docker build -t keman:beta .
init writes keman.yaml, master.key and the database to the volume, and prints the admin token. The admin listener stays on 127.0.0.1:8081 inside the container. Use docker exec for the CLI, bind a Unix socket on the volume, or set KEMAN_ADMIN_LISTEN=0.0.0.0:8081 only on a private network. For production, keep the master key out of the data volume (see SECURITY.md).
CGO_ENABLED=0 go test ./...
CGO_ENABLED=0 go build -o bin/keman ./cmd/keman
make fuzzSee CONTRIBUTING.md. Tests use an injectable clock. Fuzz targets cover virtual-key parsing, header stripping and path matching. Proxy overhead is measured in benchmarks/RESULTS.md. examples/sdk_stream.py and examples/sdk_stream.mjs stream through Keman with the official SDKs, and examples/mock-openai is a local upstream for them.
Read SECURITY.md and docs/THREAT-MODEL.md before exposing the proxy. Encryption does not help if the process memory is readable. The admin listener should not be reachable from the network.
Pushing a v* tag runs .github/workflows/release.yml. It tests, then builds static binaries for Linux (amd64, arm64), macOS (amd64, arm64) and Windows (amd64), each with an SPDX SBOM (Syft), a SHA-256 sum and a keyless cosign signature, and publishes them with install.sh as one GitHub release. It also pushes a signed multi-arch image to ghcr.io/kirank55/keman. Release notes come from docs/releases/. Tags with a - are marked as prereleases.
Background research from before the beta is in docs/archive/PLAN.md.