Wikibot: Migrated from services/VAULTWARDEN.md

2026-07-05T18:16:03Z

Migrated from services/VAULTWARDEN.md

New page

''As of: 2026-07-05 — migrated from `services/VAULTWARDEN.md`''

= Vaultwarden =

Self-hosted Bitwarden-compatible password manager. The '''human-facing''' credential store. (OpenBao is the machine-facing one — see <code>services/OPENBAO.md</code>.)

----

== Container & Endpoints ==

{| class="wikitable"
|-
! Item
! Value
|-
| Container
| <code>vaultwarden</code>
|-
| Compose
| <code>/library/vaultwarden-app/</code>
|-
| Public URL
| <code>https://vault.wilsoz.com</code> (via VPS nginx → Tailscale → stronghold)
|-
| Internal port
| 8080
|-
| Auth
| OAuth2 via Authentik (provider PK 10)
|-
| Master folder
| "Stronghold Infrastructure" (all infrastructure credentials)
|}

----

== Claude Code Integration ==

Claude reads Vaultwarden via the <code>bitwarden</code> MCP server (configured at the user level — works in every Claude session on this machine).

=== Files ===

{| class="wikitable"
|-
! File
! Mode
! Purpose
|-
| <code>~/.config/claude/vaultwarden.env</code>
| 600
| BW_URL, BW_CLIENTID, BW_CLIENTSECRET, BW_EMAIL, BW_PASSWORD
|-
| <code>~/.config/claude/bw-mcp-start.sh</code>
| 700
| Wrapper that unlocks vault and execs the MCP server
|-
| <code>~/.config/claude/bw-get.py</code>
| 700
| One-off shell helper (<code>bw-get.py "Item Name" [field]</code>)
|-
| <code>~/.claude.json</code> → <code>mcpServers.bitwarden</code>
| —
| Registers the MCP with Claude Code
|-
| <code>/snap/bin/bw</code>
| —
| Bitwarden CLI (snap-installed, official)
|-
| <code>/home/mnw/.nvm/versions/node/v22.12.0/lib/node_modules/@bitwarden/mcp-server/</code>
| —
| MCP server (npm-installed globally)
|}

=== How the wrapper works ===

# Reads <code>vaultwarden.env</code> via Python (avoids shell quoting issues with special chars in BW_PASSWORD).
# '''Refuses to start if <code>BW_URL != https://vault.wilsoz.com</code>''' — guard against accidentally authing to the wrong server.
# Runs <code>bw config server</code> (idempotent) so the CLI is pointed at the self-hosted instance.
# Logs in via <code>--apikey</code> (uses BW_CLIENTID/BW_CLIENTSECRET) if not already logged in.
# Unlocks with <code>bw unlock --passwordenv BW_PASSWORD --raw</code> and exports <code>BW_SESSION</code>.
# '''Execs <code>node <path>/dist/index.js</code>''' (not the <code>mcp-server-bitwarden</code> symlink — see Known Bugs below).

=== Available MCP tools ===

58 tools, covering: <code>lock</code>, <code>sync</code>, <code>status</code>, <code>list</code>, <code>get</code>, <code>generate</code>, <code>create_item</code>, <code>create_folder</code>, <code>edit_item</code>, <code>edit_folder</code>, <code>delete</code>, plus organization/group/policy/send management. Used like any other MCP — e.g., "list items matching voip" or "create a new item named X".

----

== Asking the User for Credentials ==

When you need a credential that isn't in Vaultwarden yet (e.g., a new third-party API key the user just got), '''never ask the user to paste it in chat'''. Instead:

=== Pattern: "Save it to Vaultwarden, then I'll fetch it" ===

Ask the user to do this:

:Please add it to Vaultwarden:
:1. Open https://vault.wilsoz.com
:2. New Item → Folder: '''Stronghold Infrastructure'''
:3. Name: <code><service-name></code> (e.g., <code>voip.ms</code>)
:4. Add fields:
: - <code>username</code> = …
: - <code>password</code> = …
: - Custom fields for anything else (e.g., <code>api-key</code>, <code>did</code>)
:5. Save, then tell me "done"
:
:I'll fetch it from Vaultwarden via the MCP — you never need to paste secrets here.

Then on your side:
<syntaxhighlight lang="text">
[use bitwarden MCP] list items matching "<service-name>"
[use bitwarden MCP] get item <id>
[use vault MCP] write secret/<service-name> with the retrieved fields
</syntaxhighlight>

=== Why this matters ===

* Chat transcripts are logged. Secrets in chat = secrets in logs forever.
'' The user has explicitly said: ''never store or surface credentials, use Vaultwarden + OpenBao.*
* If you accidentally print a secret (e.g., via <code>bash -x</code>, <code>set -x</code>, <code>cat env-file</code>, or echoing a fetched variable) — '''stop, tell the user immediately, and ask them to rotate that credential.'''

----

== Hard-Won Gotchas ==

=== 1. <code>mcp-server-bitwarden</code> symlink does not work (v2026.2.0) ===

The npm package installs a symlink at <code>…/bin/mcp-server-bitwarden</code> → <code>…/dist/index.js</code>. The script at the end of <code>index.js</code> checks <code>process.argv[1].endsWith('index.js')</code> to decide whether to start the server. The symlink path doesn't end in <code>index.js</code>, so the server never starts — it just exits silently with code 0.

'''Workaround:''' invoke via <code>node</code> with the full path:
<syntaxhighlight lang="bash">
exec node "$(npm root -g)/@bitwarden/mcp-server/dist/index.js"
</syntaxhighlight>

=== 2. Never use <code>bash -x</code> or <code>set -x</code> near <code>source vaultwarden.env</code> ===

Bash tracing prints every variable assignment to stderr, including BW_PASSWORD. '''This will leak the master password into your terminal scrollback, into logs, and into Claude conversation transcripts.''' Use targeted <code>echo</code> debugging or <code>python3</code> parsing instead.

=== 3. <code>bw login</code> defaults to <code>vault.bitwarden.com</code> ===

If the bw CLI's local config gets reset (<code>~/.config/Bitwarden CLI/data.json</code> deleted), it will default to the public Bitwarden cloud. Running <code>bw login</code> against the wrong server '''sends your credentials to Bitwarden, Inc.''' Always run <code>bw config server "$BW_URL"</code> first. The wrapper script enforces this with a refuse-to-start guard.

=== 4. <code>bw login</code> vs <code>bw unlock</code> ===

* <code>bw login</code> = authenticate the device to the server (once per device, persisted in <code>data.json</code>).
* <code>bw unlock</code> = decrypt the local vault cache (once per session, returns BW_SESSION).
* The MCP server needs both. The wrapper handles login idempotently; unlock runs on every start.

=== 5. <code>bw login</code> with email + password fails on Vaultwarden ===

Vaultwarden / Bitwarden self-hosted requires <code>bw login --apikey</code> (client credentials) rather than <code>bw login email password</code>. The email/password flow expects 2FA prompts and an interactive TTY.

----

== Rotating BW_PASSWORD ==

If the master password leaks (e.g., bash -x mistake):

# '''In Vaultwarden web UI:''' Account Settings → Change Master Password.
# '''On stronghold:''' Update <code>~/.config/claude/vaultwarden.env</code>:
```bash
# Edit the line: BW_PASSWORD='new-password-here'
chmod 600 ~/.config/claude/vaultwarden.env # verify mode still 600
```
# '''Re-login to bw:'''
```bash
bw logout
set -a; source ~/.config/claude/vaultwarden.env; set +a
bw config server "$BW_URL"
bw login --apikey
```
# '''Next Claude session''' will pick up the new password from the env file automatically.

The <code>BW_CLIENTSECRET</code> (API key) is a separate value — only rotate it if it leaks. Rotating it requires regenerating in Account Settings → Security → Keys → View API Key.

----

== Related Docs ==

* <code>services/OPENBAO.md</code> — the machine-facing companion store
* <code>services/OPENBAO.agent.md</code> — agent-focused decision tree for credential access

Services/Vaultwarden - Revision history

Wikibot: Migrated from services/VAULTWARDEN.md