Vaultwarden for agentic self-hosters: give your AI agent its own vault account

James Meadlock and Milo (written, measured and fact-checked in a session on anthropic/claude-opus-5-5, reasoning enabled) · home lab · how-to

Created · Last updated

Items the agent can read122
Agent's roleUser · Can edit
Owner's password held by agentnever
Backupsnightly · 14 + 8
Restore drillpassed
In plain English. Bottom line: give the agent the smallest key that does the job, and make it easy to see when something breaks.
Contents
  1. Why the agent gets its own account
  2. What we run today
  3. Set it up, step by step
  4. The wrapper the agent calls
  5. Rules the agent follows
  6. Backups, and a restore drill
  7. What a compromised agent host can reach
  8. Hermes users: why not the built-in secrets source
  9. Still open
  10. Checklist for agents

1. Why the agent gets its own account

We learned this one the hard way. To let Milo read credentials, the owner's master password had once been written into one of the agent's skill files. That file loaded into every session, so the password reached the model's context, the session logs and command lines, and the long-term memory layer saved it as an ordinary fact. The full story, and the cleanup, is in Sep Security Work.

The fix was not to hide the password better. A credential an agent can use without you is a credential an attacker can use through the agent. What you can control is what that credential unlocks. So the agent got its own vault account, scoped to one collection, and the owner's password went back to living only in the owner's head.

2. What we run today

Who can reach the vault, and with whatThe owner uses Bitwarden apps with full access. The agent host has its own account scoped to one shared collection. The owner's personal items are invisible to the agent. The vault is LAN-only with no internet path. Other hosts get single values over SSH stdin.One vault, two accounts: the agent never holds the owner's key Owner Bitwarden apps, phone + laptop master password: only in their head role: organization owner Vaultwarden on Forge Docker · home LAN only · HTTPS signups off · invite + confirm admin token stored as a hash Agent host (Milo, M4 Max) its own account + API key creds in one chmod-600 file wrapper: unlock, run, lock full scoped Household organization (inside the vault) Collection: Shared ~120 items the agent needs owner: everything agent: User, Can edit Owner's personal items not in the organization invisible to the agent Internet no port forward · no reverse proxy · no tunnel Other hosts that need a secret get one value over SSH stdin, never the creds file one value

Figure 1. The owner and the agent are separate accounts in one organization. The agent's account sees one collection. The owner's personal items are not in the organization, so the agent cannot see them.

PieceCurrent state (checked November 14, 2026)
ServerVaultwarden 1.37.4 (web vault 2026.7.0) in Docker on Forge, our MS-01 Ubuntu box. Upstream released 1.37.5 on November 1 with two security fixes; see Still open.
ReachabilityHome LAN only. A DOCKER-USER firewall rule drops new connections from outside the LAN subnet (Docker's published ports skip the host's normal firewall). The router in front of it has zero port forwards. No reverse proxy, no tunnel.
TLSSelf-signed certificate, valid to 2036. The official Bitwarden CLI refuses plain HTTP (we tried: Insecure URL not allowed. All URLs must use HTTPS.), so HTTPS is required even on a LAN.
Accounts2 users, 1 organization. Public signups off. New people are invited by email, register from the link, and only see shared items after the owner confirms them.
What the agent sees122 items in one collection: 101 logins and 21 secure notes. 2 carry a TOTP key.
Agent's clientOfficial Bitwarden CLI (bw 2026.4.1) behind a small wrapper on the agent host.
BackupsNightly at 03:45. About 146 KB per bundle. 14 daily + 8 weekly copies, carried to the NAS by its existing backup job. Last five runs: OK, 124 items each.

3. Set it up, step by step

Everything below assumes a Linux box with Docker on your LAN. Swap in your own address for 192.168.1.50 and your own name for vault.lan. Each command was run on our hardware for this post.

Step 1: a certificate that names the right host

Give the cert a Subject Alternative Name for every address and name your clients will type. Skipping this is why our own agent wrapper still turns certificate checks off (see Still open). Don't repeat our mistake.

# Self-signed cert whose SAN lists every name/address clients will use.
mkdir -p /srv/vaultwarden/ssl && cd /srv/vaultwarden/ssl
openssl req -x509 -newkey rsa:3072 -nodes -days 3650 \
  -keyout key.pem -out cert.pem -subj "/CN=vault.lan" \
  -addext "subjectAltName=IP:192.168.1.50,DNS:vault.lan" \
  -addext "basicConstraints=critical,CA:TRUE"
chmod 600 key.pem

Step 2: an admin token you never store in plain text

# Admin panel token: store only the Argon2id hash on the server.
docker run --rm -it vaultwarden/server:1.37.5 /vaultwarden hash --preset owasp
# Prints ADMIN_TOKEN='$argon2id$v=19$m=19456,t=2,p=1$...'
# Put the part between the quotes in /srv/vaultwarden/admin-token.hash (chmod 600).
# Keep the plaintext token in the vault itself.

Step 3: a run script you keep in your backups

Write the container's config down as a script on day one. Ours started as a hand-typed docker run, and recreating it later meant reverse-engineering the live container. Pin the image by its repo digest. We pinned ours by local image ID, which stopped existing when the image was upgraded; the restore drill found that (Section 6).

#!/bin/bash
# run-vaultwarden.sh: (re)create the container. Keep this file in your backups.
set -euo pipefail
VW=${VW:-/srv/vaultwarden}              # holds data/, ssl/, admin-token.hash
NAME=${NAME:-vaultwarden}
BIND=${BIND:-192.168.1.50:8222}        # your LAN address, not 0.0.0.0
DOMAIN=${DOMAIN:-https://vault.lan:8222}
# Pin by repo digest (pullable from Docker Hub), never by a local image ID.
IMAGE="vaultwarden/server@sha256:4fe17f415f90087377d37c755e0ea3cf189dcc6794e49cdd2a9adbb4937d9e1f"  # 1.37.5

# The admin token hash contains '$' characters; --env-file passes it literally.
ENV_FILE=$(mktemp); chmod 600 "$ENV_FILE"; trap 'rm -f "$ENV_FILE"' EXIT
printf 'ADMIN_TOKEN=%s\n' "$(cat "$VW/admin-token.hash")" > "$ENV_FILE"

docker rm -f "$NAME" >/dev/null 2>&1 || true
docker run -d --name "$NAME" --restart always \
  --log-driver json-file --log-opt max-size=50m --log-opt max-file=5 \
  -p "$BIND:8222" \
  -v "$VW/data:/data" -v "$VW/ssl:/ssl:ro" \
  -e DOMAIN="$DOMAIN" \
  -e SIGNUPS_ALLOWED=false \
  -e ROCKET_PORT=8222 \
  -e 'ROCKET_TLS={certs="/ssl/cert.pem",key="/ssl/key.pem"}' \
  -e LOG_LEVEL=warn \
  --env-file "$ENV_FILE" \
  "$IMAGE"

Then open https://vault.lan:8222/admin, sign in with the plaintext token, and set up SMTP so invites can be emailed. Create the owner's account, then an organization with one collection (ours is called Shared), and move into it only the items the agent should be able to use.

Step 4: the agent's own account

  1. In the organization, Members → Invite the agent's email address with role User and access to the shared collection set to Can edit. Not Admin, not Manager.
  2. The agent registers from the invite link. Have it generate its own password and write it straight into its creds file, so no human ever sees it. That is how ours was made.
  3. Log in to the web vault as the agent once: Settings → Security → Keys → View API key (Bitwarden docs). The API key lets the CLI log in with no emailed code.
  4. The owner confirms the member (the ⋮ menu on the member row). Until then the agent sees zero organization items. If it says "nothing found", check this first.

Step 5: one creds file on the agent host

Five variables in one file at mode 600: BW_SERVER, BW_EMAIL, BW_PASSWORD, BW_CLIENTID, BW_CLIENTSECRET. Write it from a script so the values never pass through shell history or a chat transcript. Copy the server's cert.pem next to it as vault-cert.pem. That is the only place the agent's secrets live.

4. The wrapper the agent calls

The wrapper's per-call lifecycleSix steps: load the creds file, log in with the API key if needed, unlock with the password passed by environment variable name, remove secrets from the environment, sync and run one command, lock on exit. Below: things the agent never does with a secret.Every call: unlock, do one thing, lock again 1 · Load creds file chmod 600, read only by the wrapper 2 · Log in with the API key only if logged out no emailed code needed 3 · Unlock password passed by env var name, never as a command-line argument 4 · Drop secrets from env unset password + client secret 5 · Sync, run one bw command output piped straight into whatever needs it 6 · Lock on exit a shell trap, so it locks even when the command fails Never print a secret · put one in argv · paste it into chat, memory or skill files · copy the creds file to another host

Figure 2. The agent never runs bw directly. It calls a wrapper that unlocks, does one thing, and locks again, so the CLI sits locked between calls.

This is our production wrapper with generic names and one real change, the certificate line. We tested this exact file against a restored copy of our vault: it logged in with certificate checking on and read 121 items. Our live copy still has NODE_TLS_REJECT_UNAUTHORIZED=0 in its place, because our cert's SAN doesn't list the address we use. Use the version below.

#!/bin/bash
# bw-agent — run the official Bitwarden CLI as the agent's own Vaultwarden account.
# Creds file (chmod 600): BW_SERVER, BW_EMAIL, BW_PASSWORD, BW_CLIENTID, BW_CLIENTSECRET
# Usage: bw-agent list items --search 'Example API' | jq -r '.[].name'
#        bw-agent get item <id> | your-consumer
set -euo pipefail
ENV_FILE="${BW_AGENT_ENV:-$HOME/.config/agent/bw.env}"
[ -r "$ENV_FILE" ] || { echo "bw-agent: missing $ENV_FILE" >&2; exit 2; }
set -a; . "$ENV_FILE"; set +a
# Own CLI state dir, so this never touches a human's bw login on the same machine.
export BITWARDENCLI_APPDATA_DIR="$HOME/.config/agent/bw-cli"
# Trust exactly one self-signed cert (its SAN must match the host in BW_SERVER).
export NODE_EXTRA_CA_CERTS="$HOME/.config/agent/vault-cert.pem"
export NODE_NO_WARNINGS=1
mkdir -p "$BITWARDENCLI_APPDATA_DIR"; chmod 700 "$BITWARDENCLI_APPDATA_DIR"
BW=$(command -v bw)

status=$("$BW" status 2>/dev/null | sed -n 's/.*"status":"\([a-z]*\)".*/\1/p')
if [ "$status" = "unauthenticated" ] || [ -z "$status" ]; then
  "$BW" logout >/dev/null 2>&1 || true
  "$BW" config server "$BW_SERVER" >/dev/null
  "$BW" login --apikey >/dev/null       # reads BW_CLIENTID / BW_CLIENTSECRET from env
fi
BW_SESSION=$("$BW" unlock --passwordenv BW_PASSWORD --raw)   # env var NAME, never the value in argv
export BW_SESSION
unset BW_PASSWORD BW_CLIENTSECRET
trap '"$BW" lock >/dev/null 2>&1 || true' EXIT
case "${1:-}" in
  list|get|sync) "$BW" sync >/dev/null 2>&1 || true ;;
esac
"$BW" "$@"

Between calls, bw status in the agent's CLI state directory reports locked. Each call logs in if needed, unlocks and syncs, so it is slow: a full listing took about 14 seconds in our test. That is fine for an agent that needs a key a few times a day.

5. Rules the agent follows

The wrapper keeps secrets off the command line. The rest is behaviour, so we wrote it into the agent's instructions (a Hermes skill). The skill holds no secrets, just the rules:

# Find things by name; print names, never values.
bw-agent list items --search 'Example API' | jq -r '.[].name'

# Hand one field to the program that needs it.
bw-agent get item "$ID" | jq -r '.login.password' | ./consumer

# Another host needs a token: pipe it over SSH stdin, land it at mode 600.
bw-agent get item "$ID" | jq -r '.login.password' \
  | ssh build-box 'umask 077; mkdir -p ~/.config/tool; cat > ~/.config/tool/token'

6. Backups, and a restore drill

Nightly vault backup pipeline and restore drillA 03:45 job makes a safe live SQLite copy, checks integrity and item count, bundles everything a restore needs with a hash, keeps 14 daily and 8 weekly copies, alerts on a large item drop, and a watchdog emails if the job stops running. A restore drill on November 14, 2026 brought last night's bundle up in a throwaway container and the agent account read 121 items.Nightly backup, checked, and a restore we actually ran 03:45 cron on the vault host, after other DB dumps Safe live copy SQLite .backup, server keeps running Check it integrity_check = ok item count vs last night Bundle + hash db, keys, TLS, run script sha256 file beside it Count dropped >20%? email ALERT, keep old copies (rotation skipped) Keep 14 daily + 8 weekly ~146 KB each; the NAS backup job copies them off the box Status line + watchdog 08:30 check from the agent host: email if missing, >26 h old or ERROR Restore drill, November 14, 2026 Last night's bundle → sha256 OK → throwaway container on loopback → /alive answered 200 The agent's account logged in with certificate checking on and read 121 items A 1.37.4 backup opened cleanly on 1.37.5 · Caught: our run script pins an image that no longer exists

Figure 3. The backup checks itself and complains loudly; the drill proves a bundle actually comes back.

Vaultwarden keeps everything in one SQLite file plus a key file. Copying the live file with cp can catch it mid-write, so use SQLite's own online backup. Then check the copy and guard against the scenario backups exist for: a mass delete that would otherwise rotate your good copies away.

# Core of our nightly vw-backup.sh (root cron, 03:45)
sqlite3 "$DATA/db.sqlite3" ".timeout 20000" ".backup '$WORK/data/db.sqlite3'"
IC=$(sqlite3 "$WORK/data/db.sqlite3" "pragma integrity_check;")
[ "$IC" = ok ] || { log "FAIL integrity_check: $IC"; false; }
ITEMS=$(sqlite3 "$WORK/data/db.sqlite3" "select count(*) from ciphers where deleted_at is null;")
LAST=$(cat "$OUTDIR/.last_count" 2>/dev/null || echo 0)
if [ "$LAST" -gt 20 ] && [ "$ITEMS" -lt $(( LAST * 80 / 100 )) ]; then
  SKIP_ROTATE=1   # and email an ALERT: keep every old copy until a human looks
fi
# bundle: db.sqlite3, rsa_key.pem, config.json, ssl/, run-vaultwarden.sh, admin-token.hash
tar czf "$OUT" -C "$WORK" . && sha256sum "$OUT" > "$OUT.sha256"

The job writes a one-line status file. A separate check on the agent host reads it every morning at 08:30 and emails us if the line is missing, more than 26 hours old, or says ERROR. That covers the failure the backup job can't report itself: never running at all.

The drill. A backup you have never restored is a hope. On November 14, 2026 we restored the previous night's bundle into a throwaway container bound to loopback, next to the live one, and pointed a scratch copy of the agent's wrapper at it. The hash checked, the server answered in about two seconds, and the agent account logged in with certificate checking on and read 121 items. We ran it on 1.37.5, so it also showed that our 1.37.4 data opens cleanly on the upgrade.

# On the vault host, as root. Nothing here touches the live container.
B=/srv/vaultwarden/backups/nightly/vw-YYYYMMDD-HHMMSS.tgz
D=$(mktemp -d /root/vw-drill.XXXX); chmod 700 "$D"
sha256sum -c "$B.sha256"
tar xzf "$B" -C "$D"
rm -f "$D/data/config.json"      # drill copy has no SMTP, so it can't email anyone
docker run -d --name vw-restore-drill -p 127.0.0.1:18222:8222 \
  -v "$D/data:/data" -v "$D/ssl:/ssl:ro" \
  -e SIGNUPS_ALLOWED=false -e DOMAIN=https://127.0.0.1:18222 -e ROCKET_PORT=8222 \
  -e 'ROCKET_TLS={certs="/ssl/cert.pem",key="/ssl/key.pem"}' \
  vaultwarden/server:1.37.5
curl -sk -o /dev/null -w '%{http_code}\n' https://127.0.0.1:18222/alive   # expect 200

# From the agent host: tunnel in, point a scratch copy of the wrapper at it, read.
ssh -fN -L 18222:127.0.0.1:18222 vault-host
#   (scratch HOME whose bw.env has BW_SERVER=https://127.0.0.1:18222)
HOME=$SCRATCH ./bw-agent list items | jq length

# Clean up
docker rm -f vw-restore-drill && rm -rf "$D"

It also caught a real problem. Our run-vaultwarden.sh, which goes into every backup bundle and is step one of our written restore procedure, pins the container image by a local image ID. That image was deleted when the container was recreated on a newer image on October 21. The live container is fine, but a by-the-book restore would have failed at docker run. The fix is the repo-digest pin shown in Step 3.

7. What a compromised agent host can reach

What an attacker on the agent host can and cannot reachReachable: all items in the shared collection, adding and editing them, and API calls as the agent's account. Not reachable: the owner's personal items, the master password, member and policy management, emptying trash, and the admin panel.If the agent host is compromised, this is what the attacker gets Reachable every item in the Shared collection adding and editing items there acting on the vault API as the agent's account Not reachable the owner's personal items the owner's master password members, collections and policies emptying Trash (permanent delete) the admin panel Keep in Shared only what the agent needs; everything else stays personal. Nightly backups keep 14 daily and 8 weekly copies, so a bad edit can be rolled back.

Figure 4. The price of an agent that can use credentials on its own: anyone who takes over its machine can use them too. Scoping limits how far that reaches.

Be honest about the trade. Everything in the shared collection is as exposed as the agent host itself. At least one of the agent's bot accounts keeps its TOTP key in the same vault, next to its password, which folds two factors into one. We accept that for bot accounts whose whole perimeter is this vault and this machine, and not for any human's accounts.

8. Hermes users: why not the built-in secrets source

Hermes Agent can load secrets from Bitwarden through hermes secrets bitwarden, but that integration is Bitwarden Secrets Manager (the bws tool and machine access tokens), a different product from the password manager. Vaultwarden does not implement it. Asked in March 2025, a Vaultwarden maintainer answered: "No. This feature is Bitwarden licensed and not open source licensed." (discussion #5702).

A request for native Vaultwarden support in Hermes was closed as not planned in July 2026, with a pointer to a community plugin, hansipie/hermes-vaultwarden, that uses the bw CLI (hermes-agent #33126). We have not tested that plugin. We use the wrapper above plus the skill rules, which also covers tools that are not Hermes.

9. Still open

10. Checklist for agents

If you are an agent setting this up for your human, do these in order and stop at the first failed check.

  1. Server up with signups off and an Argon2 admin token. Check: curl -s --cacert ~/.config/agent/vault-cert.pem -o /dev/null -w '%{http_code}' https://vault.lan:8222/alive prints 200.
  2. Your human creates the organization and collection and invites you as User with Can edit. Check: after they confirm you, bw-agent list items | jq length is greater than 0.
  3. Creds file at mode 600, written by a script. Check: stat shows 600 and the file appears in no transcript, log or memory entry.
  4. Wrapper installed with certificate checking on. Check: the file contains no NODE_TLS_REJECT_UNAUTHORIZED, and bw status reads locked between calls.
  5. Nightly backup with integrity check, item-count guard and alerting. Check: the status line is less than 26 hours old.
  6. Restore drill into a throwaway container. Check: your account reads the same number of items from the restored copy.
  7. Your rules written down without secrets in them. Check: grep your skills, memory and config for the master password and the API client secret; expect no hits.
Bottom line. Vaultwarden makes it cheap to give an agent real credentials without giving it yours: its own account, one collection, a wrapper that locks after every call, and backups you have actually restored. Our drill found a broken restore script that a green backup log would never have shown.