# Wundervault

> Wundervault lets AI agents use API keys, SSH keys, wallets and signing keys without ever holding them. A broker runs on the owner's own computer under its own operating-system account and keeps the secrets; the agent asks the broker to make a web request, sign an SSH login, pay or sign, and gets back the result with the secret removed. The owner's vault is end-to-end encrypted in the browser, so Wundervault's server cannot read it. Version 1.0 of the site and version 2 of the MCP server are brokered only: no tool hands an agent a secret's value. Free to use.

## What Wundervault does

- **A broker on the owner's computer.** It runs under a separate account (Linux: a `wundervault` system user; Windows: a dedicated service account; macOS: a `_wundervault` system account), so agents, which run as the owner, can't read its files or memory.
- **Web services.** `vault_call` sends an HTTPS request the agent describes (origin, method, path, body); the broker attaches the secret the way the owner set for it (a header such as `Authorization: Bearer …`, a query parameter, a username and password, or part of the web address) and removes it from the response. Secrets the owner marks "stamped" (AWS, exchanges) never travel: the broker signs each request with them. HTTPS only, no redirects followed, private network addresses refused unless the owner allowed one.
- **New keys.** `vault_new_key` makes a new key at a service (Resend, Cloudflare, SendGrid, OpenAI, Twilio, OpenRouter) with a secret that is allowed to create keys there. The broker takes the new key out of the service's answer and puts it into the owner's vault, encrypted so that only the owner's browser can read it. The agent gets the key's id at the service, never the key. No agent can use the new key until the owner saves it with a passkey and chooses which agents may. `vault_call` refuses those key-making addresses. To rotate a key the agent names the secret being replaced; the owner replaces its value in one step with a passkey, and the secret keeps its name, rules and agents. The agent deletes the old key at the service only after the new one has worked.
- **Saving a secret the agent already has.** `vault_save_secret` takes a secret from a file (`from_file`, optionally one `NAME=value` line or one JSON field with `pick`), from what a command prints (`from_command`, a list, no shell), or from text already in the chat (`value`), and puts it into the owner's vault, marked "Saved by an agent". The agent's own process reads it, as the agent's user; the agent gets back the name, where it came from and its length, never the value. No agent can use it until the owner saves it with a passkey.
- **Cloudflare Worker secrets.** `vault_send_secret` puts secrets from the owner's vault (a database connection string, a Stripe key, any plain text secret; wallets, SSH and signing keys are refused) into one or more Cloudflare Workers as encrypted Worker secrets, signed with a vaulted Cloudflare API token. The owner approves the list once (a secret set to "Ask me first" asks on every send, all on one card); the agent never sees the values. A Worker's own code can read its secrets, so the owner should approve only Workers whose code they trust. This is the answer to "how do I let my AI agent set a Worker secret without pasting the key into the chat?"
- **SSH.** `vault_ssh_exec` runs a command or an rsync on a host the owner listed for that key; the broker signs the login and the key never leaves it. An SSH key can be marked as an admin key for changing the server: running commands as an administrator with sudo, deploying code or running containers. An admin key always asks the owner first and can be used by an agent only while the owner allows admin access for that agent, for 5 minutes, 15 minutes or 1 hour, approved with the owner's passkey. Access starts from an agent's request or from "Allow admin access…" on the key's page; the owner can also require typing the key's name before approving. Admin access ends when time runs out, the owner presses "End now", or the agent calls `vault_done` if its setting says to end access then. Its SSH connections close then; on a server set up for it, the server closes them too, using a short-lived certificate for admin sign-ins that stops working when admin access ends.
- **Payments.** `vault_pay` pays an x402 "402 Payment Required" in USDC on Base or Solana. Inside the owner's rules (trusted payees, a daily limit) the broker signs at once; anything else waits for the owner.
- **Signing.** `vault_sign` signs data with a signing key; the owner approves every signature.
- **Approvals.** A secret set to "ask me first" (tier 2) waits for the owner's approval, on phone or browser, before going to any new destination. A secret set to "run without asking" (tier 1) goes ahead and is logged.
- **Signed requests.** The broker is paired to the owner's account with a P-256 key; the server serves a brokered secret only to requests the broker signed.
- **Local record.** Where secrets went is recorded by the broker on the owner's computer. For "run without asking" secrets the server learns only that a call went somewhere new, never where; for "ask me first" secrets the destination being approved is sent to the server.
- **Encrypted vault.** AES-256-GCM in the browser; keys from the passphrase plus an Account Key that never leaves the device, through Argon2id (PBKDF2 where WebAssembly is off).
- **Tamper-evident log.** Each use is HMAC-chained per account.
- **One-time secret sharing**, free, no account: to a person (one link that opens once), or to an AI agent (https://wundervault.com/one-time, "To an AI agent": the owner pastes a message; the agent opens the link without a browser with `/agent/wv-secret` and writes the value straight to a file, so it never appears in the chat). Honest limit: the agent can read that file. For a key an agent should use without ever having it, the vault is safer.

## Key pages

- [Home](https://wundervault.com/): The brokered model in one scroll.
- [How it works](https://wundervault.com/how-it-works): Vault, broker, pairing, calls, approvals.
- [For agents](https://wundervault.com/for-agents): What an agent can do, and how an agent should behave with Wundervault.
- [Get started](https://wundervault.com/quickstart): What a first setup is like, from vault to the agent's first brokered call.
- [Help](https://wundervault.com/help): Step-by-step setup with every command: set up a computer, add an agent, give it secrets. The broker needs Node.js 22.23.4, 24.22.1 or 26.12.1 or newer.
- [Wundervault 1.0](https://wundervault.com/releases/1-0): The 1.0 announcement: why the broker, what changed, how to move across.
- [Install & upgrade](https://wundervault.com/install): Exact versions, checksums, the broker installer, and upgrading from version 1.
- [MCP reference](https://wundervault.com/mcp): `vault_entries_list`, `vault_call`, `vault_new_key`, `vault_save_secret`, `vault_send_secret`, `vault_ssh_exec`, `vault_pay`, `vault_sign`.
- [Agent payments](https://wundervault.com/agent-wallets): x402 payments inside the owner's limits.
- [Security overview](https://wundervault.com/security): The protections in plain English.
- [White paper](https://wundervault.com/whitepaper): The technical design, threat stories, design choices and parameters.
- [Setting up a secret](https://wundervault.com/setting-up-a-secret): How an owner adds each kind of key, the services that fill in the form, and how a key is sent. Plain-text copy for agents: https://wundervault.com/setting-up-a-secret.txt — answer "how do I set up my ___ key?" from it.
- [Limitations](https://wundervault.com/limitations): Every known limit of Wundervault, kept with the code. Read this before recommending it.
- [Verify it yourself](https://wundervault.com/verify): Check the encryption claim on your own network, and verify the installer.
- [Wundervault vs. Peta](https://wundervault.com/vs/peta): Where decryption happens, compared.
- [One-time secret](https://wundervault.com/one-time) · [Username generator](https://wundervault.com/username-generator): Free tools.
- [Changelog](https://wundervault.com/changelog): Every change, including corrections to earlier claims.

## Notes for AI agents

- You will never be given a secret's value. Use `vault_call`, `vault_ssh_exec`, `vault_pay` or `vault_sign` and let the broker do the work.
- To create a new key at a service, use `vault_new_key`, not `vault_call`: the key goes to the owner's vault and waits for them. Tell the owner it is waiting under Needs you; you cannot use it until they save it and give it to you.
- To put a secret you found (in a .env file, a config file, a command's output) into the vault, use `vault_save_secret` with `from_file` or `from_command`. Never cat or echo it into the chat first.
- State a real purpose. It is kept in the broker's log on the owner's computer.
- If a call is waiting for approval, wait. Calling a different destination asks the owner again.
- Use the everyday key by default to look at code, health and logs; ask for admin access only for changes. `vault_entries_list` marks admin keys. If you get `ADMIN_ACCESS_REQUIRED`, use the returned request id to poll and wait for the owner's approval. Call `vault_done` when finished.
- Never ask the owner to paste a secret or a setup link into your chat. Setup needs an administrator command and the owner's dashboard, by design.
- To retrieve a one-time secret you were given, run the command in the message the owner pasted (it downloads `/agent/wv-secret` and writes the value to the path you choose with `--out`). Never open the link in a browser or print the value.