---
type: plan
title: "credvault Phase 0 — Vaultwarden org, bot account, and CLI auth setup"
summary: Step-by-step plan to prepare the self-hosted Vaultwarden instance for AI credential management — organization, restricted collection, bot account, API-key auth lifecycle, and version/parity audit.
tags:
  - type/plan
  - project/credvault
  - tool/vaultwarden
  - domain/credential-management
scope: project
date: 2026-07-09
last_updated: 2026-07-09
related:
  - credvault-integration-master-plan
source: ruby-gems
---

# credvault Phase 0 — Vaultwarden Setup

Preconditions for everything else. Interactive (web vault + email), driven with the human.

## Steps

1. **Version audit**: record Vaultwarden server version and `bw --version` on the host that
   will run credvault. Check instance config for `TRASH_AUTO_DELETE_DAYS` (default: trash is
   never auto-purged) and `ORG_CREATION_USERS`/signup settings.
2. **Organization**: confirm or create a Vaultwarden Organization owned by the human account.
   Create collection `AI Managed Credentials`.
3. **Bot account**: invite `bot+jaredmswanson@gmail.com` (invite lands in the human's Gmail).
   Set a distinct master password (never reused). Log into web vault once; generate personal
   API key (Settings → Security → Keys). Confirm the account holds org role `User` with access
   to ONLY the `AI Managed Credentials` collection, Edit permission.
4. **Known limitation to accept**: Vaultwarden Edit permission includes item deletion; no org
   toggle restricts it. Posture is deter-and-detect: wrapper (no delete command) + plugin
   hooks + trash/export recovery (see [[credvault-security-backup-recovery-plan]]).
5. **CLI auth proof**: on the target host, as the user that will run credvault:
   `bw config server <url>` → `bw login --apikey` (BW_CLIENTID/BW_CLIENTSECRET) →
   `bw unlock --passwordfile <mode-600 file>` → `bw sync` → create/read/edit a test item in the
   collection → `bw lock`. Use `BITWARDENCLI_APPDATA_DIR=~/.config/credvault/bitwarden`.
6. **Verify assumptions empirically** (feeds the gem's adapter design):
   - Does `bw list items --collectionid <id>` include custom fields in JSON? (expected: yes,
     but search does NOT match custom fields — client-side filtering required)
   - Does editing via `bw edit` preserve password history? ("last 5" is client-written; verify)
   - Does org encrypted-JSON export work under the human account on this version?
7. **Record outputs**: org ID, collection ID, server URL → these become the gem's trusted
   config (`~/.config/credvault/config.yml`), never agent-supplied.

## Exit criteria

Bot account can create/read/edit (and, acknowledged, delete) items in exactly one collection;
cannot see the human's personal vault or other collections; full non-interactive auth cycle
proven on the target host; empirical answers to step 6 documented in the repo.