keyr

Local-first MITM HTTPS proxy that injects credentials and OAuth grants for AI agents — so agents (Claude Code, Cursor, custom SDK agents) never see raw keys or refresh tokens.

Status: alpha. All Phase 1–5 features have shipped (proxy, broker, requests, OAuth Apps + Grants + refresh worker, container isolation). Distribution polish (single-binary releases, Homebrew tap) is in progress.

What it does

• Intercepts agent HTTPS traffic via a transparent MITM proxy.
• Injects the right Authorization header per upstream host based on per-Vault config.
• Supports static credentials (API keys, basic auth, custom headers).
• Holds OAuth refresh tokens and keeps access tokens fresh in the background.
• Notifies the human operator when an OAuth grant goes invalid (invalid_grant) so it can be re-authorized.
• Approval-gated: agents cannot edit Vault contents directly — they file Requests that the human reviews and applies.

Concepts

| Term | Meaning | | --- | --- | | Vault | A namespace of Resources, Credentials, OAuth Apps, and Grants | | Resource | Per-host config (e.g. api.github.com → use Credential GITHUB_TOKEN) | | Credential | A stored static value (API key, password, custom header) | | OAuth App | A registered app on the provider side (client_id + client_secret from Google / GitHub / etc.) | | Grant | Live OAuth state — access token + refresh token + scopes for one authorized account | | Request | Pending agent-to-human approval (the change-control system) | | Agent | An AI process you grant access to a Vault (Claude Code, Cursor, etc.) |

Quickstart

# Install. Today only the npm path is available; brew / curl-install are
# tracked under Phase 6 and will land alongside the first signed release.
npm install -g @keyr/cli

# First-run setup. `keyr init` prints the instance proxy token once;
# save it (env var, password manager, etc.) — `keyr run` needs it.
keyr init

# Start the daemon (foreground; ^C to stop). HTTP API on 7331, MITM
# proxy on 7332. Open http://127.0.0.1:7331 for the web UI.
keyr server

# --- Static-credential resource ---
keyr credential set --vault default --key GITHUB_TOKEN ghp_xxx
keyr resource add  --vault default --host api.github.com --auth bearer --credential GITHUB_TOKEN

# --- OAuth grant (Google / GitHub / etc.) ---
keyr oauth-app create --vault default --provider google \
  --display-name "Personal Google" \
  --client-id <your-client-id> --client-secret <your-client-secret>

keyr grant connect --vault default --provider google
# → opens an authorize URL; after you grant access in the browser the
#   server's /v1/oauth/callback persists the Grant.

keyr resource add --vault default --host www.googleapis.com \
  --auth oauth2 --grant <grant-id-from-list>

# --- Run an agent through the proxy ---
export KEYR_TOKEN=<proxy-token-from-init>

# Cooperative (HTTPS_PROXY env vars; trusted agents):
keyr run -- claude

# Non-cooperative (Docker + iptables-locked egress; for untrusted agents):
keyr run --isolation=container -- claude

Development

Requires Node.js ≥ 22.

npm install
npm test                              # vitest, must be 100% green
npm run typecheck                     # tsc --noEmit, strict
npm run lint                          # biome check, no errors
npm run dev -- init                   # iterate locally
npm run build                         # esbuild bundle to dist/index.js

Every PR must pass lint + typecheck + test. CI enforces this.

Architecture

• Two ports: HTTP API on 7331, MITM proxy on 7332. Both bind to 127.0.0.1 by default.
• SQLite at ~/.keyr/keyr.db. AES-256-GCM at rest; Argon2id-derived KEK wraps the DEK.
• MITM proxy with per-SNI leaf certs minted by an embedded ECDSA P-256 software CA whose root key is encrypted with the DEK.
• Background OAuth refresh worker (Phase 4) keeps Grants fresh; expired Grants surface as Requests for re-auth.

For the full architectural rationale, read the Architecture Decision Records. For the threat model and crypto choices, read docs/security.md. For agent-friendly project conventions, read AGENTS.md.

License

MIT. Inspired by Infisical Agent Vault (also MIT) — see THIRD_PARTY_LICENSES.