clawhub

Wundervault Vault

Read passwords, API keys, and credentials from a Wundervault zero-knowledge, multi-agent vault, and run authorized shell commands with secrets injected — wit...

view source

installs

1,369

stars

karma

SkillRank score ↗

8.3/ 10

evaluated by implexa, claude-haiku-4-5 · 2026-07-28

wundervault-vault exposes encrypted credentials to agents via mcp tools without exposing plaintext in chat, supporting secret injection into shell commands, config files, and remote deployments with tiered approval workflows.

structure

9.0

trigger phrases

8.0

procedure

9.0

edge cases

8.0

documentation

8.0

strengths

view original SKILL.md from clawhubclick to expand

---
name: wundervault-vault
description: Read passwords, API keys, and credentials from a Wundervault zero-knowledge, multi-agent vault, and run authorized shell commands with secrets injected — without exposing them in chat. Requires a Wundervault account — request early access at wundervault.com.
---

# Wundervault Vault

Wundervault is an encrypted, self-hosted secret vault that exposes secrets to agents via MCP tools. Secrets never appear in chat — they are decrypted server-side and injected directly into commands or written to config files. **The plaintext of a secret is never returned to the agent.**

## Check Setup First

Always call `vault_entries_list` before doing anything vault-related. Use the result to determine where the user is in setup:

| Result | What it means | What to do |
|--------|--------------|------------|
| Returns a list of entries | Vault is connected and ready | Proceed |
| Returns empty list | Connected but no secrets yet | Tell the user to add secrets at wundervault.com |
| Returns auth/credentials error | MCP server installed but not onboarded | Walk through onboarding (see below) |
| Tool not available | MCP server not wired to this agent | Walk through setup (see INSTALL.md) |

### First-run onboarding

If the vault tools are missing or credentials are invalid, tell the user:

> "Wundervault isn't set up yet. Here's how to get started:
> 1. Request access via the [contact form](https://wundervault.com/contact)
> 2. Once approved, set up your account and onboard your agent at wundervault.com
> 3. Verify the MCP server package using the checksums at [wundervault.com/install](https://wundervault.com/install)
> 4. Come back and I'll verify the connection"

Do not attempt to use any vault tools until `vault_entries_list` succeeds.

## Tools

### `vault_entries_list`
List all vault entries available to this agent. Returns entry IDs and names only — no secret values.

```
vault_entries_list()
→ [{ id: "abc123", name: "ResendApiKey", tier: "full" }, ...]
```

Use this first to get the entry ID before calling any other tool.

### `vault_entry_get`
Retrieve and burn a secret. The secret is decrypted server-side and **never returned to the agent** — you will receive a burn confirmation only.

```
vault_entry_get(entry_id: "abc123", purpose: "confirm secret exists")
→ "✅ Secret retrieved and burned."
```

Use this only to confirm a secret exists or to acknowledge retrieval. To actually use a secret in a command or file, use `vault_exec` or `vault_entry_inject_env` instead.

### `vault_exec`
Execute a shell command with a vault secret injected as an environment variable — the secret is never exposed in chat or logs.

```
vault_exec(entry_id: "abc123", purpose: "publish package", command: "npm publish --access public")
```

**Two tiers:**
- **Tier 1** (standard): runs immediately
- **Tier 2** (restricted): the call is denied until the owner approves. The denial carries a request id and the owner is emailed automatically; approval is scoped to this agent + secret (single-use, or a 15/60-minute window). Retry after approval — do not treat the denial as an error.

Shell escape sequences (`$()`, backticks, `bash -c`, `eval`) and file-writing redirects (`>`, `>>`, `tee`) are hard-blocked before the secret is decrypted. To put a secret into a file, use `vault_entry_inject_env` — do not redirect it with the shell. (These blocks are a guardrail, not a sandbox; the real protection is that plaintext is never returned to you.)

**Remote execution via SSH:** Pass `remote_host` to run the command on a remote machine. The secret is injected inside the remote shell via SSH stdin — no `AcceptEnv`/`SendEnv` config required on the remote host. Use `ssh_key_entry_id` to load the SSH key from the vault itself.

```
vault_exec(
entry_id: "abc123",
purpose: "check subscribers on prod",
command: "curl -s -u \"admin:$DB_PASSWORD\" http://localhost:9000/api/subscribers",
inject_as: { env_key: "DB_PASSWORD" },
remote_host: { host: "192.168.1.50", user: "opc", ssh_key_entry_id: "ssh-key-entry-id" }
)
```

**Remote command with only an SSH key (no secret injected):** `entry_id` is optional. To run a command on a remote host using just a vaulted SSH key — without injecting any secret as an env var — omit `entry_id` and pass `remote_host.ssh_key_entry_id`.

```
vault_exec(
purpose: "restart the service on prod",
command: "sudo systemctl restart wundervault",
remote_host: { host: "prod.example.com", user: "opc", ssh_key_entry_id: "ssh-key-entry-id" }
)
```

### `vault_entry_inject_env`
Write a secret directly into an environment file (`.env`) as an environment variable, without it passing through chat.

**Disabled by default.** To use this tool, enable it in Settings > Agent Capabilities at wundervault.com. You can disable it again at any time.

```
vault_entry_inject_env(
entry_id: "abc123",
purpose: "inject API key into app config",
file_path: "/home/user/app/.env",
env_key: "RESEND_API_KEY"
)
```

Note: `file_path` and `env_key` are the correct parameter names.

**Why you'd enable it:** Writing secrets directly to `.env` files is the standard way to configure apps, containers, and deploy pipelines. Without this tool, you'd need to paste secrets manually — exposing them in your terminal or chat history. `vault_entry_inject_env` lets agents wire up credentials automatically while keeping plaintext out of the conversation entirely.

**Risks to understand before enabling:**
- An agent can write a secret to any `.env` path it can reach — including paths outside your project directory
- If an agent is compromised or acting on a malicious prompt, it could inject credentials into unexpected locations
- Written secrets are no longer burn-on-read — they persist on disk in the target file
- File permissions on the `.env` are your responsibility; the tool writes the value but does not set restrictive permissions automatically

### `vault_rsync`
Sync a local directory to a remote host via rsync over SSH, with the SSH key fetched from the vault. The key is written to a temp file for the transfer duration and deleted immediately after.

```
vault_rsync(
ssh_key_entry_id: "ssh-key-entry-id",
purpose: "deploy static files to prod",
local_path: "/home/user/app/dist/",
remote_user: "opc",
remote_host: "prod.example.com",
remote_path: "/var/www/html"
)
```

### `vault_entry_forget`
Discard a vault entry reference from context. Does not delete the vault entry.

```
vault_entry_forget(entry_id: "abc123")
→ ✔️ Reference discarded.
```

## Common Patterns

**Run a command with a secret (Tier 1):**
```
1. vault_entries_list() → find entry ID for the secret you need
2. vault_exec(entry_id: "abc123", purpose: "...", command: "...")
```

**Run a command with a Tier 2 entry (deploy, publish, infrastructure change):**
```
1. vault_entries_list() → find entry ID
2. vault_exec(entry_id: "abc123", purpose: "...", command: "...")
```
Note: Tier 2 calls are denied until the owner approves from the wundervault.com dashboard — the owner is emailed automatically and the denial includes a request id. Retry after approval.

**Sign an x402 payment with a vaulted wallet key (you never see the key):**
```
1. vault_entries_list() → find the wallet key entry (keep wallet keys at Tier 2)
2. vault_exec(entry_id: "...", purpose: "sign x402 payment for <api>", command: "node sign-payment.mjs", inject_as: { env_key: "X402_WALLET_KEY" })
3. Denied with a request id? The owner has been emailed — retry after they approve.
```
The signing script reads the key from its environment and prints only the signed `X-PAYMENT` header. A verified end-to-end run (402 → approval → signed → settled on Base Sepolia) is at [wundervault.com/agent-wallets](https://wundervault.com/agent-wallets).

**Write a secret to a config file:**
```
1. vault_entries_list() → find entry ID
2. vault_entry_inject_env(entry_id: "abc123", purpose: "...", file_path: "/app/.env", env_key: "MY_KEY")
```

**Deploy files to a remote server:**
```
1. vault_entries_list() → find SSH key entry ID
2. vault_rsync(ssh_key_entry_id: "...", local_path: "./dist/", remote_user: "opc", remote_host: "prod.example.com", remote_path: "/var/www/html")
```

## Multi-Agent Setup

Wundervault is designed for multi-agent environments. Each agent gets its own scoped identity and token — they are fully isolated from each other at the daemon level.

- Each agent authenticates with its own token file (`~/.wundervault/agents/{AgentName}.token`)
- Agents can only access entries they have been explicitly granted
- The vault owner controls which agents exist and what they can reach from the wundervault.com dashboard
- Agents cannot see each other's tokens, identities, or access scopes
- Audit logs are per-agent, so you can trace exactly which agent accessed which secret and when

This makes Wundervault suitable for setups where multiple specialized agents (a coding agent, a deploy agent, a partner agent, etc.) share infrastructure but must not share credentials.

## Security Notes

- Secrets are end-to-end encrypted; plaintext is never returned to the agent
- The zero-knowledge claim is independently verifiable — no source access needed: [wundervault.com/verify](https://wundervault.com/verify) (browser DevTools walkthrough or mitmproxy canary test, with a published transcript)
- The onboarding script verifies its own ed25519 signature on startup and exits if the check fails. Pipe mode (`curl ... | python3`) is hard-blocked — the script detects it and refuses to run. Pinned version, SHA-256 checksum, and public key are at [wundervault.com/install](https://wundervault.com/install).
- Agents never hold credentials directly — only a scoped token is stored locally. The local daemon manages the actual credentials and exposes them only through its controlled interface, enforcing tier checks and audit logging on every request. Compromise of an agent token does not grant direct access to vault credentials.
- `vault_exec` and `vault_rsync` are the correct tools for using secrets — not `vault_entry_get`
- Tier 2 entries are configured by the vault owner; agents cannot escalate a Tier 1 entry
- Tier 2 access is enabled server-side by the user via the wundervault.com dashboard
- The `inject_as` override lets you specify which env var name receives the secret if the vault entry has no exec_config set

## More Info

- npm: `@wundervault/mcp-server`
- Vault UI: [wundervault.com](https://wundervault.com)

related skills

semantically similar in the cross-vendor index

clawhub

75% match

Agentvault

Encrypted credential vault and persistent memory for AI agents. Install from npm, sandbox agent access to secrets, store and query encrypted memory, run an M...

don't have the plugin yet? install it then click "run inline in claude" again.

Wundervault Vault

intent

use wundervault to retrieve and inject secrets (api keys, passwords, ssh keys, wallet keys) into shell commands and config files without ever exposing plaintext in chat, logs, or agent memory. secrets are decrypted server-side and injected directly into execution environments. use this skill when you need to authenticate to external services, deploy code, run remote commands, transfer files, or sign transactions without handling credentials directly. wundervault enforces access tiers (immediate execution for tier 1, owner approval for tier 2 on sensitive ops like deploys and publishes) and audit-logs every secret access per agent.

inputs

wundervault account and mcp server:

early access request at wundervault.com (required, not open signup)
npm package @wundervault/mcp-server installed in your agent's environment
mcp server wired to your agent runtime (see INSTALL.md for setup)

local wundervault daemon:

running on localhost (default port 3000, configurable)
agent token file at ~/.wundervault/agents/{AgentName}.token (auto-created on first onboarding)
ed25519 signature verification on startup (detects man-in-the-middle attacks)

vault entries (secrets stored in wundervault.com):

entry id: unique identifier for each secret (returned by vault_entries_list)
entry name: human-readable label (e.g. "ResendApiKey", "ProdSSHKey")
tier: tier 1 (immediate) or tier 2 (requires owner approval via email)
scope: agent can only access entries explicitly granted by vault owner

remote execution (optional):

remote host ssh credentials (loaded from vault, never exposed to agent)
remote user and host (e.g. "opc@prod.example.com")
command to run remotely (executed with secret injected into remote shell via stdin)

environment file injection (optional, must be enabled in settings):

file path: destination .env file on local filesystem
env key name: environment variable name to write (e.g. "RESEND_API_KEY")
file permissions: your responsibility (tool does not set restrictive perms automatically)

rsync deployment (optional):

local path: source directory to sync
remote user and host: rsync destination
remote path: target directory on remote server
ssh key entry id: vault entry containing private ssh key

procedure

1. verify vault is connected and ready

call vault_entries_list() with no arguments
input: none
output: array of vault entries with id, name, and tier fields, or error
decision: see decision points section below

2. find the vault entry id for the secret you need

input: result from step 1 (list of entries)
action: scan the entry name and tier to locate the secret you need (e.g. find "ResendApiKey" for email, "ProdSSHKey" for deployments)
output: entry id (string, e.g. "abc123")

3. choose your execution method based on use case

input: entry id, purpose (one-line string describing why you need the secret), command or file operation
see procedure steps 3a-3e below for each method
output: result or error from the vault tool

3a. run a command with injected secret (most common)

input: entry id, purpose, command (shell command as string)
call vault_exec(entry_id: "abc123", purpose: "publish npm package", command: "npm publish --access public")
optional: set inject_as: { env_key: "MY_VAR_NAME" } if the vault entry has no exec_config defined
output: command stdout/stderr, or tier 2 denial with request id (see step 5)
edge case: shell escape sequences and file redirects are hard-blocked; use step 3c to write to files instead

3b. run a command on a remote host with injected secret

input: entry id (secret to inject), purpose, command, remote_host object (host, user, ssh_key_entry_id)
call vault_exec(entry_id: "abc123", purpose: "check prod db", command: "curl -u \"admin:$DB_PASSWORD\" http://localhost:9000/api/subscribers", inject_as: { env_key: "DB_PASSWORD" }, remote_host: { host: "192.168.1.50", user: "opc", ssh_key_entry_id: "ssh-key-entry-id" })
secret is injected into remote shell via SSH stdin; no SendEnv/AcceptEnv config needed on remote host
output: remote command output, or network/auth error
edge case: network timeout or ssh key expiry will fail; vault owner controls ssh key rotation

3c. run a remote command using only an ssh key (no secret injection)

input: purpose, command, remote_host object with ssh_key_entry_id (entry_id is optional/omitted)
call vault_exec(purpose: "restart service on prod", command: "sudo systemctl restart wundervault", remote_host: { host: "prod.example.com", user: "opc", ssh_key_entry_id: "ssh-key-entry-id" })
output: remote command output or error
use case: simple remote ops that only need ssh auth, no secret injection

3d. write a secret to a .env file (requires enabling in settings)

input: entry id, purpose, file path (e.g. "/app/.env"), env key name (e.g. "RESEND_API_KEY")
call vault_entry_inject_env(entry_id: "abc123", purpose: "inject api key into app config", file_path: "/home/user/app/.env", env_key: "RESEND_API_KEY")
secret is written directly to disk, not returned to agent
output: success confirmation or file write error
edge case: agent can write to any path it can reach; vault owner is responsible for file permissions after write

3e. sync a directory to a remote server via rsync over ssh

input: ssh key entry id, purpose, local path, remote user, remote host, remote path
call vault_rsync(ssh_key_entry_id: "ssh-key-entry-id", purpose: "deploy static files to prod", local_path: "/home/user/app/dist/", remote_user: "opc", remote_host: "prod.example.com", remote_path: "/var/www/html")
ssh key is written to temp file, rsync executes, key is deleted immediately after
output: rsync summary or transfer error
edge case: large transfers may timeout; rsync stdout shows progress

4. confirm secret was retrieved (optional, rarely needed)

call vault_entry_get(entry_id: "abc123", purpose: "confirm secret exists") only to confirm a secret is present in the vault
input: entry id, purpose
output: burn confirmation (plaintext never returned to agent)
note: this tool is for verification only; use steps 3a-3e to actually use the secret

5. handle tier 2 approval workflow (if the command is restricted)

input: vault_exec call on a tier 2 entry
output: denial response with request_id and message (not an error)
action: tell the user that the vault owner has been emailed a request for approval, including the request_id, the agent name, and the command purpose
do not retry immediately; wait for the vault owner to approve at wundervault.com dashboard
once approved, retry the same vault_exec call (approval is scoped to this agent + entry + purpose for 15/60 minutes or single-use depending on owner settings)
outcome: command executes with secret injected after approval

6. discard vault entry reference from agent context (cleanup, optional)

call vault_entry_forget(entry_id: "abc123") to drop the entry from memory if you are done using it
input: entry id
output: confirmation message
note: does not delete the vault entry itself, only discards the agent's reference to it

decision points

if vault_entries_list() returns a list of entries:

vault is connected and ready. proceed to step 2 (find the entry you need).

if vault_entries_list() returns an empty list:

vault is connected but has no secrets yet. tell the user to log into wundervault.com and add vault entries (secrets) in the UI. verify that the user's account is set up and the agent is onboarded.

if vault_entries_list() returns an auth or credentials error (e.g. invalid token, token expired):

mcp server is installed but the agent token is missing or invalid. the user must complete first-run onboarding. walk through the onboarding steps (below).

if vault_entries_list() tool is not available (tool not found in mcp runtime):

mcp server is not wired to the agent. the user must follow INSTALL.md to install @wundervault/mcp-server and configure it in the mcp runtime. do not attempt any vault tool calls until this is resolved.

if a vault_exec call is denied with a tier 2 request_id:

the entry is restricted (tier 2). do not treat this as an error or retry loop. instead, inform the user that the vault owner has been emailed a request with the request_id. the owner must approve at wundervault.com. once approved (within the approval window, typically 15/60 minutes or single-use), retry the same call. the approval is scoped to this agent + entry + purpose.

if a vault_exec or vault_rsync call fails with a network error (ssh timeout, host unreachable, connection reset):

remote host is unreachable or ssh connection failed. verify the remote host is running, the network path is open, and the ssh key entry id is correct. do not retry blindly; inform the user of the network error.

if a vault_exec call fails because the command contains shell escape sequences or file redirects:

the vault tool hard-blocks backticks, $(), bash -c, eval, >, >>, and tee before decrypting the secret. if you need to write the secret to a file, use vault_entry_inject_env (step 3d) instead. if you need to chain commands, wrap them in a script file and pass the script path to vault_exec.

if you need to use a secret but don't know which entry contains it:

call vault_entries_list() and scan the entry names. if no entry matches, ask the user to add the secret to their vault at wundervault.com. the vault owner controls which entries exist and which agents can access them.

if the .env file does not exist (for vault_entry_inject_env):

the tool will create the file if it does not exist. verify that the parent directory is writable by the agent. after the tool writes the secret, file permissions are your responsibility (the tool does not set restrictive perms).

if vault_entry_inject_env is not available (disabled in settings):

the vault owner has disabled this tool. tell the user to enable it at wundervault.com under Settings > Agent Capabilities > vault_entry_inject_env. explain the risks (agent can write to any path it can reach, secrets persist on disk, file perms are manual). once enabled, retry the call.

output contract

success for vault_entries_list():

returns json array of objects: [{ id: string, name: string, tier: "1" | "2" }, ...]
example: [{ id: "abc123", name: "ResendApiKey", tier: "1" }, { id: "xyz789", name: "ProdSSHKey", tier: "2" }]

success for vault_exec() (tier 1):

command executes with secret injected as env var
returns stdout and stderr of the command
example: npm notice Publishing to registry...

success for vault_exec() (tier 2, waiting for approval):

denial response with structure: { denied: true, request_id: string, message: string, agent: string, purpose: string }
example: { denied: true, request_id: "req_abc123", message: "tier 2 entry requires owner approval", agent: "deploy-bot", purpose: "npm publish" }
vault owner receives email with request_id and can approve at wundervault.com

success for vault_exec() (tier 2, after approval):

same as tier 1: command executes and returns stdout/stderr

success for vault_entry_inject_env():

secret written to file at file_path, env var set with name env_key
returns confirmation: { ok: true, file: "/path/to/.env", env_key: "RESEND_API_KEY" }

success for vault_rsync():

rsync transfer completes, files synced to remote_path
returns rsync summary: { sent: number, received: number, deleted: number }

success for vault_entry_get():

secret retrieved and burned (not returned)
returns confirmation: ✅ Secret retrieved and burned.

success for vault_entry_forget():

returns confirmation: ✔️ Reference discarded.

error responses (all tools):

{ error: string, code: string } on auth, network, or permission failure
example: { error: "invalid token", code: "AUTH_FAILED" }

outcome signal

command executed with secret: you see the command's output (stdout/stderr) without the secret visible anywhere. the secret was injected server-side and never passed through the agent or chat.
tier 2 approval waiting: you receive a denial message with a request_id. the vault owner has been emailed. once approved, retry and the command executes.
secret written to .env: file exists on disk with the secret value set as an env var. verify with a tool that can read .env files (do not cat or expose the file in chat).
files synced to remote: remote directory now contains the synced files. verify with a remote ls command (e.g. vault_exec with ssh_key_entry_id only, no secret injection).
secret confirmed to exist: you receive a burn confirmation; the secret is present and accessible.
entry forgotten: reference is dropped from agent context.
setup incomplete: you are prompted to complete onboarding. follow the steps and retry vault_entries_list() when done.

first-run onboarding

if the vault tools are missing or credentials are invalid, share this with the user:

wundervault isn't set up yet. here's how to get started:

request early access via the contact form at https://wundervault.com/contact

once approved, log into https://wundervault.com and onboard your agent (Settings > Agents)

verify the mcp server package using the checksums at https://wundervault.com/install

install @wundervault/mcp-server via npm in your agent's environment

wire the mcp server to your agent runtime (see INSTALL.md)

come back and i'll verify the connection by calling vault_entries_list()

do not attempt any vault tool calls until vault_entries_list() succeeds.

common patterns

pattern: run a command with a tier 1 secret (immediate execution)

1. vault_entries_list() → find entry id for the secret (e.g. "ResendApiKey")
2. vault_exec(entry_id: "...", purpose: "send welcome email", command: "node send-email.js")
→ command executes with secret injected, output returned

pattern: deploy code with a tier 2 secret (requires owner approval)

1. vault_entries_list() → find entry id (e.g. "NpmPublishToken")
2. vault_exec(entry_id: "...", purpose: "publish v1.2.3 to npm registry", command: "npm publish")
→ denied with request_id; vault owner is emailed
3. (wait for vault owner to approve at wundervault.com)
4. retry the same vault_exec call
→ command executes with secret injected after approval

pattern: sign a payment with a vaulted wallet key (x402, web monetization, etc.)

1. vault_entries_list() → find wallet key entry (keep wallet keys at tier 2)
2. vault_exec(entry_id: "wallet-key-prod", purpose: "sign x402 payment for api.example.com", command: "node sign-payment.mjs", inject_as: { env_key: "X402_WALLET_KEY" })
→ denied with request_id (tier 2); owner is emailed
3. (owner approves)
4. retry
→ signing script reads key from env, signs, prints only the X-PAYMENT header (key never exposed)

reference implementation: https://wundervault.com/agent-wallets

pattern: write credentials to a config file

1. vault_entries_list() → find entry id (e.g. "DatabasePassword")
2. vault_entry_inject_env(entry_id: "...", purpose: "wire db credentials into app config", file_path: "/app/.env", env_key: "DB_PASSWORD")
→ secret written to /app/.env as DB_PASSWORD=<secret>
3. app reads .env and uses DB_PASSWORD

pattern: run a command on a remote server with injected secret

1. vault_entries_list() → find secret entry id (e.g. "ProdDbPassword") and ssh key entry id (e.g. "ProdSSHKey")
2. vault_exec(entry_id: "ProdDbPassword", purpose: "check subscriber count on prod", command: "curl -u \"admin:$DB_PASSWORD\" http://localhost:9000/api/subscribers", inject_as: { env_key: "DB_PASSWORD" }, remote_host: { host