Secrets and Bitwarden¶

This document covers the credential management model for this repository.

Model¶

Bitwarden vault is the source of truth for all secrets. No credentials are committed to the repository.

.env is the local working copy. It is gitignored and lives only on your workstation. Secrets flow from Bitwarden into .env, and from .env into Docker containers at runtime via the Nix dev shell environment.

Bitwarden vault
    │
    │  just bw-env-hydrate (or per-service pull)
    ▼
.env  ──  Nix dev shell sources on entry  ──►  containers via Arion

Pull all secrets at once¶

just bw-env-hydrate pulls the full set of known integration secrets from Bitwarden into .env. Run it on first setup and after vault changes.

just bw-env-hydrate

It pulls credentials for: Home Assistant, Kagi, YouTube, Plex, Paperless, MQTT/ZigBee2MQTT, Google Workspace, SportIntel, Twitter/X, Bluesky, and Mastodon, Vault MCP, plus shared LLM API keys.

Per-service pulls¶

Use these when you change credentials for one service without touching others.

Command	What it pulls
`just bw-kagi-key-pull`	`KAGI_API_KEY`
`just bw-youtube-key-pull`	`YOUTUBE_API_KEY`
`just bw-paperless-api-pull`	`PAPERLESS_URL`, `PAPERLESS_API_KEY`
`just bw-mqtt-credentials-pull`	MQTT broker credentials
`just bw-plex-credentials-pull`	Plex credentials
`just bw-google-workspace-credentials-pull`	Google Workspace OAuth credentials
`just bw-sportintel-credentials-pull`	`ODDS_API_KEY`, `BALLDONTLIE_API_KEY`
`just bw-twitter-credentials-pull`	Twitter/X API credentials
`just bw-bsky-credentials-pull`	Bluesky credentials
`just bw-mastodon-credentials-pull`	Mastodon credentials
`just bw-vault-credentials-pull`	`VAULT_ADDR`, `VAULT_TOKEN`, `VAULT_NAMESPACE`
`just bw-ssh-gateway-key-pull`	Ed25519 keypair for SSH Gateway

Push and pull the full `.env` backup¶

The full .env is stored as a Bitwarden secure note named "Ezra .env" in the AI_Shared collection. This lets you restore .env on a new machine without re-running every per-service pull.

Push the current .env to Bitwarden (strips the ephemeral BW_SESSION first):

just bw-env-push

Pull .env from Bitwarden (fetches the note and appends a freshly unlocked session token):

just bw-env-pull

Bitwarden session token¶

Bitwarden MCP and the bw CLI require a BW_SESSION token in .env. Tokens expire. Regenerate when needed:

bw login
export BW_SESSION=$(bw unlock --raw)

Update .env with the new token, then push to vault:

just bw-env-push

Bitwarden item reference¶

Secret	Service	Bitwarden item name
`BW_SESSION`, `BW_CLIENT_ID`, `BW_CLIENT_SECRET`	Bitwarden MCP	`Ezra .env` (ai-sandbox / AI_Shared)
`GITHUB_PERSONAL_ACCESS_TOKEN`	GitHub MCP	—
`HA_URL`, `HA_TOKEN`	Home Assistant MCP	`Home Assistant Credentials`
`KAGI_API_KEY`	Kagi MCP	`Kagi API Key`
`YOUTUBE_API_KEY`	YouTube MCP	`Youtube API Key`
`MQTT_*`	MQTT and ZigBee2MQTT MCP	`MQTT MCP`
`PAPERLESS_URL`, `PAPERLESS_API_KEY`	Paperless MCP	`Paperless API`
`PLEX_URL`, `PLEX_TOKEN`	Plex MCP	`Plex MCP`
SSH keypair	SSH Gateway MCP	`SSH Gateway Identity`
`VAULT_ADDR`, `VAULT_TOKEN`, `VAULT_NAMESPACE`	Vault MCP	`HCP Vault Ezra`
`GOOGLE_OAUTH_CLIENT_ID`, `GOOGLE_OAUTH_CLIENT_SECRET`	Google Workspace MCP	`Google Workspace MCP`

Vault MCP credentials are minted by terraform-vault-bootstrap and then stored in Bitwarden item HCP Vault Ezra for hydration via just bw-vault-credentials-pull.

Security note¶

.env is in .gitignore. Secrets must flow through Bitwarden only. pre-commit hooks include a secret scanner (gitleaks) that fails commits containing credential patterns. Never bypass hooks with --no-verify.