# AGENTS.md — Build guide for Bitwarden ## Project scope Prepare a private Vaultwarden deployment using its documented configuration, HTTPS and official compatible clients. Provide preflight, start, consistent backup and restore-to-separate-volumes scripts rather than writing a vault server. Catalogue verdict: yes. If your goal is to stop paying hosted Bitwarden Premium, the core vault can be self-hosted or replaced with KeePass-style local storage; the caveat is security responsibility. Use the implementation prompt below to define the deliverable. Complete each phase's acceptance checks before extending the scope. ## Working agreement - Inspect the repository and its existing instructions before choosing paths, dependencies or commands. Keep one coherent stack and explain changes to the proposed architecture. - Plan a vertical slice that accepts a real input and produces the useful output described below. Persist only the state the prompt calls for; respect memory-only and upstream-managed workflows. Use fixtures only when they are clearly labelled. - After scaffolding, document the actual install, development, check and build commands in README and keep them synchronized with the package or project manifest. Do not report commands as successful unless they ran. - Work in small steps. At handoff, list implemented flows, checks actually performed, remaining blockers, and any credentials or provider setup the owner must supply. - Do not publish, spend money, contact customers, delete source data or run irreversible migrations without the project owner's authorization. ## Prerequisites - A user-owned Linux server, domain/DNS control, sufficient disk and memory, and the selected upstream release documentation. Record actual image names and required variables rather than guessing. - Implementation components: Docker Compose around the selected upstream application, pinned release/image digest and persistent volumes. Caddy for HTTPS, environment templates without secrets, and operator scripts for backups, upgrades and restore. - Scope boundary: Vaultwarden is a separate community implementation; official Bitwarden support and enterprise guarantees are not implied. ## Stack and architecture - Docker Compose around the selected upstream application, pinned release/image digest and persistent volumes. - Caddy for HTTPS, environment templates without secrets, and operator scripts for backups, upgrades and restore. - Operating records: pinned Vaultwarden release, server configuration, persistent database/files, client connections and backup inventory ## Security and data integrity - Generate unique administrator secrets, restrict exposed ports and disable public signup if the deployment is private. Keep backups encrypted and credentials outside the repository. - Correctness boundary: Never expose an unconfigured public vault or log unlock secrets; recovery must preserve every upstream-required persistent file, not only the SQL database. - Back up before each upgrade, retain the previous image and configuration, and check upstream schema migration notes; a container rollback alone may not reverse a database migration. - Capture the complete database and persistent file set consistently. Rehearse recovery into separate volumes and document the supported rollback point. ## Agent implementation rules - Project rule — operating records: pinned Vaultwarden release, server configuration, persistent database/files, client connections and backup inventory - Project rule — preserve this invariant: Never expose an unconfigured public vault or log unlock secrets; recovery must preserve every upstream-required persistent file, not only the SQL database. - Project rule — acceptance evidence: A restored isolated instance opens a known test vault through a compatible client; missing required backup files fail restoration visibly. ## Optional agent skills and references - Optional external skill: [sharp-edges](https://github.com/trailofbits/skills/blob/main/plugins/sharp-edges/skills/sharp-edges/SKILL.md) — Review security-sensitive APIs and configuration for dangerous defaults and easy-to-misuse interfaces. Review its instructions and compatibility before use; it does not grant deployment, data-access or publication permission. - Optional external skill: [agent-browser](https://github.com/vercel-labs/agent-browser/blob/main/skills/agent-browser/SKILL.md) — Automate browser interaction using accessibility snapshots, element references and reproducible navigation workflows. Review its instructions and compatibility before use; it does not grant deployment, data-access or publication permission. Read the linked SKILL.md and its dependencies before adding a skill. Select only the skills matching this project's runtime and task; their documentation does not supply API access, credentials or approval to perform external actions. Pin the reviewed revision where the tool supports it. Follow the chosen agent's documented project-level installation mechanism. ## Distribution ideas These are optional planning notes. Obtain the owner's approval before publishing or contacting anyone. - Demonstrate the actual Bitwarden-inspired workflow with owned or clearly labeled sample data: Prepare a private Vaultwarden deployment using its documented configuration, HTTPS and official compatible clients. Provide preflight, start, consistent backup and restore-to-separate-volumes scripts rather than writing a vault server. - Publish a reproducible walkthrough with this observable result: A restored isolated instance opens a known test vault through a compatible client; missing required backup files fail restoration visibly. - Explain who can operate this scoped tool, its setup and ongoing costs, and these remaining product gaps: Vaultwarden is a separate community implementation; official Bitwarden support and enterprise guarantees are not implied. Avoid guaranteed savings, performance scores or implied endorsement. ## Engineering roadmap 1. Phase 1 — Select and document the upstream release. Prepare a private Vaultwarden deployment using its documented configuration, HTTPS and official compatible clients. Provide preflight, start, consistent backup and restore-to-separate-volumes scripts rather than writing a vault server. Record the release, documented host requirements and upstream deployment reference. Start in an isolated staging directory. Keep these exclusions explicit: Vaultwarden is a separate community implementation; official Bitwarden support and enterprise guarantees are not implied. 2. Phase 2 — Configure the maintained application. Record pinned Vaultwarden release, server configuration, persistent database/files, client connections and backup inventory Configure supported environment variables, credentials, volumes and database connections. Use upstream installation and migration procedures; do not create a replacement application schema, authentication service or dashboard. Preserve this rule: Never expose an unconfigured public vault or log unlock secrets; recovery must preserve every upstream-required persistent file, not only the SQL database. 3. Phase 3 — Use the upstream workflow. Perform the stated workflow through the upstream interface or its documented CLI. Add an operator helper script only when the working slice explicitly calls for it; do not build a new input/review/output frontend. Back up before each upgrade, retain the previous image and configuration, and check upstream schema migration notes; a container rollback alone may not reverse a database migration. 4. Phase 4 — Review access and failure states. Generate unique administrator secrets, restrict exposed ports and disable public signup if the deployment is private. Keep backups encrypted and credentials outside the repository. Document health checks, reconnect/restart steps and how missing configuration is surfaced by the upstream service. Keep public and administrative endpoints separate. 5. Phase 5 — Recovery and upgrades. Capture the complete database and persistent file set consistently. Rehearse recovery into separate volumes and document the supported rollback point. Document upstream migration compatibility before an upgrade, the retained rollback point and the sequence for restoring configuration, data and files. 6. Phase 6 — Operator handoff and acceptance. A restored isolated instance opens a known test vault through a compatible client; missing required backup files fail restoration visibly. Record actual staging observations separately from these proposed checks. Deliver the pinned configuration, secret-free environment template, backup/restore runbook and any explicitly scoped helper scripts; do not claim equivalence to managed hosting. ## Paid-product capabilities outside this build - managed hosting - premium support - emergency access - polished admin - reduced security maintenance risk ## Implementation prompt WORKING SLICE Prepare a private Vaultwarden deployment using its documented configuration, HTTPS and official compatible clients. Provide preflight, start, consistent backup and restore-to-separate-volumes scripts rather than writing a vault server. Operate this scoped Bitwarden-inspired deployment through the maintained upstream application. Record its configuration and failure states; do not rebuild its schema, interface or services. Architecture - Docker Compose around the selected upstream application, pinned release/image digest and persistent volumes. - Caddy for HTTPS, environment templates without secrets, and operator scripts for backups, upgrades and restore. Prerequisites and limits A user-owned Linux server, domain/DNS control, sufficient disk and memory, and the selected upstream release documentation. Record actual image names and required variables rather than guessing. Outside this release: Vaultwarden is a separate community implementation; official Bitwarden support and enterprise guarantees are not implied. Configuration and correctness pinned Vaultwarden release, server configuration, persistent database/files, client connections and backup inventory Invariant: Never expose an unconfigured public vault or log unlock secrets; recovery must preserve every upstream-required persistent file, not only the SQL database. Back up before each upgrade, retain the previous image and configuration, and check upstream schema migration notes; a container rollback alone may not reverse a database migration. Security and privacy Generate unique administrator secrets, restrict exposed ports and disable public signup if the deployment is private. Keep backups encrypted and credentials outside the repository. Recovery and export Capture the complete database and persistent file set consistently. Rehearse recovery into separate volumes and document the supported rollback point. Implementation order 1. Phase 1 — Select and document the upstream release. Prepare a private Vaultwarden deployment using its documented configuration, HTTPS and official compatible clients. Provide preflight, start, consistent backup and restore-to-separate-volumes scripts rather than writing a vault server. Record the release, documented host requirements and upstream deployment reference. Start in an isolated staging directory. Keep these exclusions explicit: Vaultwarden is a separate community implementation; official Bitwarden support and enterprise guarantees are not implied. 2. Phase 2 — Configure the maintained application. Record pinned Vaultwarden release, server configuration, persistent database/files, client connections and backup inventory Configure supported environment variables, credentials, volumes and database connections. Use upstream installation and migration procedures; do not create a replacement application schema, authentication service or dashboard. Preserve this rule: Never expose an unconfigured public vault or log unlock secrets; recovery must preserve every upstream-required persistent file, not only the SQL database. 3. Phase 3 — Use the upstream workflow. Perform the stated workflow through the upstream interface or its documented CLI. Add an operator helper script only when the working slice explicitly calls for it; do not build a new input/review/output frontend. Back up before each upgrade, retain the previous image and configuration, and check upstream schema migration notes; a container rollback alone may not reverse a database migration. 4. Phase 4 — Review access and failure states. Generate unique administrator secrets, restrict exposed ports and disable public signup if the deployment is private. Keep backups encrypted and credentials outside the repository. Document health checks, reconnect/restart steps and how missing configuration is surfaced by the upstream service. Keep public and administrative endpoints separate. 5. Phase 5 — Recovery and upgrades. Capture the complete database and persistent file set consistently. Rehearse recovery into separate volumes and document the supported rollback point. Document upstream migration compatibility before an upgrade, the retained rollback point and the sequence for restoring configuration, data and files. 6. Phase 6 — Operator handoff and acceptance. A restored isolated instance opens a known test vault through a compatible client; missing required backup files fail restoration visibly. Record actual staging observations separately from these proposed checks. Deliver the pinned configuration, secret-free environment template, backup/restore runbook and any explicitly scoped helper scripts; do not claim equivalence to managed hosting. Acceptance A restored isolated instance opens a known test vault through a compatible client; missing required backup files fail restoration visibly. Use real source data or clearly labeled fixtures. Explain unsupported input and provider failures; do not fabricate analytics, delivery receipts, accuracy claims or security guarantees. Optional agent guidance Optional external skill: [sharp-edges](https://github.com/trailofbits/skills/blob/main/plugins/sharp-edges/skills/sharp-edges/SKILL.md) — Review security-sensitive APIs and configuration for dangerous defaults and easy-to-misuse interfaces. Review its instructions and compatibility before use; it does not grant deployment, data-access or publication permission. Optional external skill: [agent-browser](https://github.com/vercel-labs/agent-browser/blob/main/skills/agent-browser/SKILL.md) — Automate browser interaction using accessibility snapshots, element references and reproducible navigation workflows. Review its instructions and compatibility before use; it does not grant deployment, data-access or publication permission. Project rule — operating records: pinned Vaultwarden release, server configuration, persistent database/files, client connections and backup inventory Project rule — preserve this invariant: Never expose an unconfigured public vault or log unlock secrets; recovery must preserve every upstream-required persistent file, not only the SQL database. Project rule — acceptance evidence: A restored isolated instance opens a known test vault through a compatible client; missing required backup files fail restoration visibly. ## Completion evidence Demonstrate the prompt's acceptance scenarios against the scoped workflow. Include setup from a clean checkout and failure recovery. Check persistence across restart and export/restore only for the state the prompt says to store; for memory-only tools, confirm that temporary content is discarded as specified. Record actual results and remaining limitations. A detailed plan alone does not establish a working replacement.