Get started with Vernam

About five minutes from install to an agent running on placeholder tokens. You need Node.js 22 or later on macOS or Linux.

Install

This puts the vn command on your path. Check it with vn help.

Quickstart

  1. 1

    Create your vault and pick a passphrase of 12 characters or more.

    vn init
  2. 2

    Unlock it. Keys stay in a background daemon, and the vault locks itself after 8 hours.

    vn unlock
  3. 3

    Add a key. Paste it at the hidden prompt; it's pinned to api.openai.com.

    vn add OPENAI_API_KEY --preset openai
  4. 4

    Run your agent. Anything after -- runs with placeholder tokens.

    vn run -- claude
  5. 5

    See what it did.

    vn log

What the agent sees

Inside vn run, the agent's environment holds a placeholder and a base URL that points at the local proxy:

OPENAI_API_KEY  = vn_z1sN98ghnNN6ZZ6kH9Bp2Ub7GtCfhsoM
OPENAI_BASE_URL = http://127.0.0.1:62602/OPENAI_API_KEY/v1

Official SDKs read both variables, so your code doesn't change. The proxy swaps the placeholder for the real key and forwards the request to api.openai.com. A placeholder sent down another key's route gets a 403 and never leaves your machine. When vn run exits, its placeholders stop working.

Commands

vn initCreate the vault.
vn unlock [--for 8h]Type your passphrase once. Keys stay in memory until the vault locks.
vn lockStop the daemon and wipe keys from memory.
vn statusShow whether the vault is unlocked and linked to a team.
vn add NAME --preset …Store a key for openai, anthropic, stripe or github. Reads the value from stdin or a hidden prompt.
vn listList stored keys. Values are masked to the last 4 characters.
vn rm NAMEDelete a key.
vn run [--ttl 1h] -- CMDRun a command with placeholder tokens.
vn log [-n 20]Show recent brokered requests.
vn login / vn logoutLink this machine to your team's dashboard, or unlink it.

Custom APIs

For an API without a preset, give the host yourself. Set --base-env to the variable your SDK reads for its base URL, so it sends requests through the proxy.

vn add RESEND_API_KEY --target https://api.resend.com --base-env RESEND_BASE_URL

The key and its host are always set together, so nothing can repoint a stored key at a different server.

Team dashboard

Run vn login to link a machine. Your browser opens, you approve the machine, and from then on every brokered request shows up live in your team's log. The dashboard gets key names, hosts, methods, paths without query strings, status codes and whether a request was blocked. It never gets a key value. Without vn login, the CLI sends nothing anywhere.

Current limits

  • The SDK or tool has to read a base-URL variable. OpenAI, Anthropic and Claude Code do. Tools with a hard-coded API URL aren't covered yet.
  • Placeholders are swapped in headers and query strings, not request bodies.
  • The vault is as strong as your passphrase. That's why it needs 12 or more characters and uses a slow key derivation.
  • A process running as you could read the daemon's memory on a machine with debugging rights turned on. Running the daemon as a separate user is planned.