Get started

Command line

Swap the keys in your .env files for ghost keys with one command, and scan your code for leaked keys.

The vallkey command line tool does the setup for you. It needs Node.js 18 or newer and nothing else. Run it in your project folder:

TerminalShell

npx vallkey login   # approve this computer in your browser, oncenpx vallkey init    # swap the keys in your .env files for ghost keys

init finds the API keys in your .env files, creates a ghost key for each one with the provider's safe default rules, and writes the ghost keys back in place of the real ones. The official OpenAI, Anthropic and Groq SDKs read their address from the environment, so init also adds OPENAI_BASE_URL, ANTHROPIC_BASE_URL or GROQ_BASE_URL and those need no code change. For other SDKs it prints the one line to change. Use --dry-run to see what it would do first.

Note

Your real keys are stored encrypted and removed from the files, and Vallkey never shows a real key again. If you use one anywhere else, keep a copy in your password manager.

Command	What it does
`login`	Opens your browser to approve this computer. The tool gets its own API token, named after the computer, which you can revoke in Settings → API tokens. Only the account owner can approve.
`init [files]`	Swaps the keys in .env, .env.local and the other usual .env files (or the files you name) for ghost keys.
`scan [paths]`	Looks for API keys in your code and .env files, and with `--history` in every commit. Keys are shown masked. Exits with 1 if it finds any, so it can stop a CI build.
`keys`	Lists your ghost keys.
`keys add --from <id>`	Makes another ghost key for a real key shared by several ghost keys, inside its outer rules.
`real-keys`	Lists the real keys shared by several ghost keys.
`domains`	Lists your own API domains; `domains check <domain>` checks one. `init` uses your default domain for the address it writes.
`kill <key id>`	Stops a ghost key everywhere, right away.

Any SDK, no code changes

In Node.js, vallkey/auto sends every request that carries a ghost key to Vallkey, with the same path, so no SDK needs a base URL. Requests without a ghost key are not touched. It covers fetch and Node's http and https modules, which carry almost every JavaScript SDK: OpenAI, Anthropic, Stripe, Google, axios, got and more.

TerminalShell

1npm install vallkey2node -r vallkey/auto app.js3 4# or for any tool that starts Node, such as next dev:5NODE_OPTIONS='-r vallkey/auto' npm run dev

You can also load it in code with import 'vallkey/auto', as the very first import, before any SDK. VALLKEY_DEBUG=1 logs each request it sends to Vallkey (never the key) and VALLKEY_AUTO=0 turns it off.

Short-lived keys for web pages and apps

On your server, vallkey/session makes a short-lived key for a signed-in user, from the ghost key in VALLKEY_GHOST_KEY. Never call it from a web page.

Your serverTypeScript

import { createSessionKey } from 'vallkey/session'; const { session_key } = await createSessionKey({ user: user.id }); // send it to the page or app

In CI, give the tool an API token in VALLKEY_TOKEN instead of signing in. To stop keys from ever being committed:

.github/workflows/keys.yml

1on: [push, pull_request]2jobs:3  scan:4    runs-on: ubuntu-latest5    steps:6      - uses: actions/checkout@v77      - uses: vallkeyhq/scan-action@v1

Each key found is marked on its line in the pull request and listed in the run summary, always masked. Add history: true (with fetch-depth: 0 on checkout) to scan every commit too. Other CI systems can run npx --yes vallkey scan.

A line that only looks like a key, such as a test fixture, can be skipped with a vallkey:ignore comment on it.

Still have a question?

We read every email, usually within a day.

Contact support