Install, verify & upgrade

The MCP package

Install the exact version. The helper app only runs a copy installed in a system folder, never one inside your home folder: on Linux that means sudo; on macOS, Node.js from nodejs.org installs to a system folder already.

You need Node.js installed for the whole computer, not just your user (so not through nvm or a similar tool): the installer refuses a copy in a home folder. On Linux, a system that uses systemd, as almost all do.

Linux

sudo npm install -g @wundervault/mcp-server@2.5.0

macOS

npm install -g @wundervault/mcp-server@2.5.0

If npm stops with a permission error (EACCES), run it with sudo, naming node and npm in full so it works however sudo is set up:

sudo "$(command -v node)" "$(command -v npm)" install -g @wundervault/mcp-server@2.5.0

Windows

npm install -g @wundervault/mcp-server@2.5.0

npm checks every download against the fingerprint it holds for that version. To see that fingerprint, and compare it with the one on our GitHub release:

npm view @wundervault/mcp-server@2.5.0 dist.integrity

This shows npm's record. It proves your install matches what npm serves, not that npm serves what we published: that is what the GitHub release and the MCP Registry listing below are for.

Source, AGPL-3.0: github.com/wundervault/wundervault-mcp. The helper app and the browser encryption are open source.
Official MCP Registry: listed as io.github.wundervault/wundervault-mcp. The registry checks that the npm package and our GitHub organisation match.

The helper app

One administrator step per computer. The installer creates the helper app’s own account and its private folder. It downloads nothing and is short enough to read first.

Linux

sudo sh "$(npm root -g)/@wundervault/mcp-server/packaging/install-daemon.sh"
sudo /opt/wundervault/current/node /opt/wundervault/current/app/bin/wundervault-agent --pair

macOS

In Terminal:

cd "$(npm root -g)/@wundervault/mcp-server"
sudo sh packaging/install-daemon-macos.sh
sh packaging/verify-macos.sh
sudo /opt/wundervault/current/node /opt/wundervault/current/app/bin/wundervault-agent --pair

Windows

In an Administrator PowerShell:

Set-Location (Join-Path (npm root -g) "@wundervault\mcp-server")
powershell -ExecutionPolicy Bypass -File packaging\install-daemon-windows.ps1
powershell -ExecutionPolicy Bypass -File packaging\verify-windows.ps1
wundervault-agent --pair

The last line starts pairing: it prints a code and a fingerprint, and you finish in your vault under Computers (type the code, check the fingerprint matches). Run the pairing command the installer printed. Paths can differ: use the ones your installer printed. Full paths, because with sudo a bare name could be found in a folder your agents can write.

If a step fails, tell us what it printed.

Updating

When a new version is out, update on each computer your agents use. The vault tells you when one of them is behind, and the changelog says what changed.

On version 2.2.0 or newer: open Computers in your vault, choose Update now and confirm with your passkey. The helper app checks the update is signed by us, installs it and restarts. Nothing to type.

On an older version: update by hand, once, on each computer, with the commands below (they install the latest version). After that, updates are the Update now button.

Linux

sudo npm install -g @wundervault/mcp-server@latest
sudo sh "$(npm root -g)/@wundervault/mcp-server/packaging/install-daemon.sh"

macOS

In Terminal (this form of the first line works even when sudo can't find npm by itself):

sudo "$(command -v node)" "$(command -v npm)" install -g @wundervault/mcp-server@latest
cd "$(npm root -g)/@wundervault/mcp-server"
sudo sh packaging/install-daemon-macos.sh

Windows

In an Administrator PowerShell:

npm install -g @wundervault/mcp-server@latest
Set-Location (Join-Path (npm root -g) "@wundervault\mcp-server")
powershell -ExecutionPolicy Bypass -File packaging\install-daemon-windows.ps1

You don't need to pair again. The installer keeps this computer's pairing. It ends by printing the steps for a new computer: if this computer is already listed under Computers in your vault, skip them.
Then quit and reopen your agent apps, so they use the new version.
Still on version 1 (1.7.1 or older)? Version 2 is not a one-line update: upgrading from version 1.

Upgrading from version 1

Version 2 moves your secrets into the helper app. Your account, vault and passkeys carry over as they are. Agents still on version 1 can't use your secrets, so move each one.

Install version 2: sudo npm install -g @wundervault/mcp-server@2 on Linux, npm install -g @wundervault/mcp-server@2 on macOS and Windows.
Install the helper app and pair it (above).
As your normal user (no sudo), run the move command the installer printed last: wundervault-agent --migrate.
Quit and reopen each agent app (Claude Code, Claude Desktop, OpenClaw, Hermes…). An app that stays open keeps running the old copy, and that copy holds the agent's place, so the new one can't start.
For each agent: open Agents in your vault, choose Repair and this computer, then paste the message you get into the agent's chat (or run wundervault-agent --enrol and enter its claim code yourself).
When every agent has moved: wundervault-agent --migrate --finish removes the old credential store.
Your vault marks each secret your agents could read before version 2 with a blue dot and Replace it. Replace those secrets at the services that issued them: treat them as seen.

The onboarding script

The script, its signature and the key below all come from this website, so on their own they can't prove this website wasn't tampered with. The same script and key are published on GitHub; Verify it yourself shows how to compare them.

You need this only if your vault gives you an agent setup command because no computer is paired yet; with a paired computer, adding an agent uses the helper app instead. The onboarding script is served at wundervault.com/onboard. Download it first — pipe mode (curl ... | python3) is hard-blocked by the script, which detects it and exits immediately.

Linux

curl -fsSL https://wundervault.com/onboard -o /tmp/wv-onboard.py
curl -fsSL https://wundervault.com/onboard.sig -o /tmp/wv-onboard.py.sig

macOS

curl -fsSL https://wundervault.com/onboard -o /tmp/wv-onboard.py
curl -fsSL https://wundervault.com/onboard.sig -o /tmp/wv-onboard.py.sig

Windows

In PowerShell (curl.exe, not curl, which PowerShell treats as something else):

curl.exe -fsSL https://wundervault.com/onboard -o "$env:TEMP\wv-onboard.py"
curl.exe -fsSL https://wundervault.com/onboard.sig -o "$env:TEMP\wv-onboard.py.sig"

SHA-256 Checksum

Current checksum of the onboarding script (computed live):

bc2a6c422bec64fbeb575f37bb90cee9aa04f7135928f69edbc88ee1932645f5  wv-onboard.py

Verify locally after downloading:

Linux

sha256sum /tmp/wv-onboard.py

macOS

shasum -a 256 /tmp/wv-onboard.py

Windows

Get-FileHash "$env:TEMP\wv-onboard.py" -Algorithm SHA256

Then run the exact command your vault gave you: it starts with python3 /tmp/wv-onboard.py (on Windows, python %TEMP%\wv-onboard.py) followed by your agent's own setup values.

Ed25519 Signature

The script also carries an ed25519 signature, available at wundervault.com/onboard.sig. The script verifies this automatically on startup — if the signature check fails, it aborts before doing anything.

Public key for independent verification:

3yhfVM5ABcBHPGSuZSQuIxr0C9QkHnFKoGMWwcWpooY=

Verify manually with Python:

python3 - <<'EOF'
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
from cryptography.exceptions import InvalidSignature
import base64, pathlib

pubkey_b64 = "3yhfVM5ABcBHPGSuZSQuIxr0C9QkHnFKoGMWwcWpooY="
script = pathlib.Path("/tmp/wv-onboard.py").read_bytes()
sig_b64  = pathlib.Path("/tmp/wv-onboard.py.sig").read_text().strip()

pub = Ed25519PublicKey.from_public_bytes(base64.b64decode(pubkey_b64))
try:
    pub.verify(base64.b64decode(sig_b64), script)
    print("✅ Signature valid")
except InvalidSignature:
    print("❌ Signature invalid — do not run this script")
EOF

The cryptography package is required: pip install cryptography