clawdie/clawdie-ai
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: vaultwarden bootstrap flow + verification test (Sam & Hermes)

Browse source
This commit is contained in:
Sam & Hermes 2026-05-29 19:54:44 +02:00
parent fe2b2191ca
commit 0a8813f3dd
1 changed files with 50 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

51
docs/VAULTWARDEN-SETUP.md
View file

@ -9,7 +9,56 @@ Agents use the `bw` CLI to retrieve secrets programmatically — no passwords in
## Prerequisites
- Node.js (for npm install) or a pre-built `bw` binary
- Org API key from the operator (Samo or Hermes on debby)
- Org API key + master password from the operator (Samo)
## Bootstrap Flow
Vaultwarden has a circular bootstrap problem: an agent needs credentials to
access Vaultwarden, but those credentials can't be stored in Vaultwarden itself
as the only copy.
**Operator's role:**
1. Generate an org API key in Vaultwarden (Organization → Settings → API Keys).
2. Store a reference copy in Vaultwarden's `agent-secrets` collection for
recovery, but keep the authoritative copy offline (password manager, encrypted
USB, printed safe — anything outside Vaultwarden itself).
3. When onboarding a new agent: hand them three values directly via a secure
channel (file drop, not chat):
- `BW_CLIENTID` — org API key client ID
- `BW_CLIENTSECRET` — org API key client secret
- `BW_PASSWORD` — Vaultwarden master password
**Agent's role:**
1. Receive credentials, write them to a 0600 bootstrap file, use once.
2. Follow the Setup steps below to install `bw`, login, and unlock.
3. Shred the bootstrap file after the first successful `bw list items`.
4. Use `--passwordenv BW_PASSWORD` and `BW_SESSION` for all future access.
**Why not self-serve:** a brand-new agent cannot pull the org API key from
Vaultwarden because it needs the org API key to unlock Vaultwarden. The operator
is the only out-of-band channel.
## Verification Test
After onboarding, verify with this smoke test — run from the agent host:
```sh
# 1. Unlock and get session
export BW_CLIENTID="organization...."
export BW_CLIENTSECRET=*** login --apikey
bw unlock --passwordenv BW_PASSWORD
export BW_SESSION="..."
# 2. List items in agent-secrets collection
bw list items --session "$BW_SESSION" --collectionid 94ba61b8-633c-454e-b749-f115617eeac3
# 3. Retrieve the hermes-debby Forgejo password
bw list items --session "$BW_SESSION" --search "hermes-debby" | jq '.[0].login.username'
# Expected: "hermes-debby"
```
If the username resolves: Vaultwarden onboarding complete. Lock the vault (`bw lock`).
## Setup