How to Use Vaultwarden: The Beginner's Guide (First Compose, the Domain Rule, First Account, the Signups-Lock, and the Backup-Your-vw-data Rule)

CodexFuse Team · 2026-10-31T11:28:25.193Z · 15 min read

Learn how to use Vaultwarden: install the free self-hosted Bitwarden server on Docker, lock signups, guard the admin panel, and point the official apps at your domain.

How to Use Vaultwarden: The Beginner's Guide (First Compose, the Domain Rule, First Account, the Signups-Lock, and the Backup-Your-vw-data Rule)

Learning how to use Vaultwarden is how you keep every password in a vault you own instead of one you rent. Vaultwarden is a free, open-source, community-maintained Bitwarden-compatible server written in Rust (dani-garcia/vaultwarden on GitHub, v1.37.4 at the time of writing, AGPL-3.0) — a single Docker container that speaks the Bitwarden client API so faithfully that the official Bitwarden apps cannot tell the difference. Your vault stays encrypted on your own server, and the whole thing idles at roughly 10 MB of RAM. This vaultwarden tutorial walks the complete beginner arc in one sitting: the Docker Compose install, the DOMAIN rule that breaks half of all first-time setups, creating your first account, locking signups with SIGNUPS_ALLOWED, guarding the /admin panel with a hashed ADMIN_TOKEN, pointing the official clients at your server, enabling 2FA and push, and the backup rule that makes this safe for real passwords. If containers are new to you, start with our Docker beginner guide first; if you would rather use the hosted Bitwarden cloud than run a server at all, read our Bitwarden beginner guide instead — Bitwarden is the official-cloud lane, and this guide draws the self-hosted line so you only have to pick once. In short, the vaultwarden vs bitwarden choice is not about features — the apps are identical — it is about who holds the keys and who runs the server.

How do you use Vaultwarden for the first time?

The fastest beginner path is: point a DNS record at your server and bring up the two-container compose file (Vaultwarden plus Caddy), create your one account before anything else, flip SIGNUPS_ALLOWED to false so nobody else can register, set a hashed ADMIN_TOKEN and lock down the /admin panel, point the official Bitwarden apps at your domain, enable two-factor authentication, and set up the off-machine backup of the vw-data folder. That is the whole journey — everything else is polish and hardening.

1. Install it. One compose file: the vaultwarden/server image plus Caddy as the HTTPS front, with a single ./vw-data volume holding everything.
2. Create your account first. Your master password is unrecoverable — store it somewhere safe before you type it, because nobody can reset it for you.
3. Close signups immediately. Out of the box anyone who finds your URL can register; set SIGNUPS_ALLOWED=false right after your account exists.
4. Hash the admin token. Generate an Argon2 hash with the built-in hash command, double every $ sign for compose, and log in to /admin.
5. Point the official apps at your server. Choose self-hosted on the Bitwarden login screen and enter your https:// domain — no forks, no sideloading.
6. Turn on 2FA and save the recovery code. Then store the recovery code outside the vault it protects.
7. Back up vw-data off the machine. Use SQLite's online backup, not a raw file copy mid-write, and keep a copy somewhere other than the server.

What is Vaultwarden, and how is it different from Bitwarden?

Vaultwarden is a from-scratch reimplementation of the Bitwarden server API in Rust. Bitwarden the company ships an official self-hosted server too, but it is built for enterprises: multiple containers, a real SQL database, and roughly 2 GB of RAM at idle before you have stored a single password. Vaultwarden is the community's answer for everyone else — one container, SQLite by default, about 10 MB at idle, happy on a Raspberry Pi or the cheapest VPS tier. It is community-maintained and not affiliated with Bitwarden or 8bit Solutions, so there is no support contract; for a household, a small team, or a homelab, that is a trade most people take gladly. The official Bitwarden clients (browser extension, desktop app, iOS, Android) work with it unmodified — you only change the server URL.

One naming note before you read any other guide: Vaultwarden was called bitwarden_rs until v1.21.0 in 2021, when it was renamed to avoid trademark confusion. Same project, different name — if a tutorial tells you to pull bitwardenrs/server, it is out of date; the image is vaultwarden/server now.

What do I need before I install Vaultwarden?

You need three things: a Linux host with Docker and Docker Compose v2, a domain or subdomain with a DNS A record pointing at the server (a free DuckDNS subdomain works), and ports 80 and 443 reachable so the reverse proxy can fetch a Let's Encrypt certificate. The domain and HTTPS are not optional extras. Bitwarden clients rely on the browser's Web Crypto API, which browsers refuse to run over plain HTTP, and the mobile apps flat-out reject self-signed certificates — the classic "the app won't connect" evening always traces back to a self-signed cert the phone silently distrusted. The only exception is localhost, which browsers treat as a secure context for testing. For the host itself, see our guide on what is VPS hosting — even the smallest VPS tier is plenty for Vaultwarden.

How do I install Vaultwarden with Docker Compose?

The clean setup is two containers: Vaultwarden itself, and Caddy as a reverse proxy that fetches and renews Let's Encrypt certificates automatically. (Nginx Proxy Manager or Traefik work just as well if you already run one — the Vaultwarden config does not change.) Make a directory and create the compose file with the current pinned tag — at the time of writing that is 1.37.4, released 2026-10-05 as a security update. Do not run :latest in production: it will upgrade you to a new major version the next time you pull, sometimes when you were not expecting it.

mkdir -p ~/vaultwarden && cd ~/vaultwarden
nano docker-compose.yml

services:
  vaultwarden:
    image: vaultwarden/server:1.37.4
    container_name: vaultwarden
    restart: unless-stopped
    environment:
      DOMAIN: "https://vault.example.com"
      SIGNUPS_ALLOWED: "true"          # set to false after you create your account
    volumes:
      - ./vw-data:/data
    # no host ports published — Caddy reaches it over the compose network

  caddy:
    image: caddy:2
    container_name: caddy
    restart: unless-stopped
    ports:
      - 80:80
      - 443:443
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - ./caddy-data:/data
      - ./caddy-config:/config

Then docker compose up -d and watch the logs with docker compose logs -f vaultwarden. Give Caddy a few seconds to pull the certificate, then open https://vault.example.com — you should see the web vault login. Create your account now, because the next step turns off registration.

Why does the DOMAIN rule break so many Vaultwarden setups?

Because DOMAIN must exactly match the URL you visit, including the https:// prefix, and every client checks it against the TLS certificate. Set it to "https://vault.example.com" while your Caddyfile serves vault.example.com, or type http:// in the app's server field by habit, and the apps will refuse to connect with an unhelpful error. If anything refuses to connect after a fresh install, compare the DOMAIN value character-for-character against the URL in your browser's address bar before you touch anything else — the domain rule solves most day-one connection problems. For the HTTPS side of the setup, our Caddy beginner guide covers automatic certificates in more depth.

How do I put Vaultwarden behind HTTPS with Caddy?

The vaultwarden https setup is a single Caddyfile block: your domain, reverse-proxied to the Vaultwarden container on the compose network. Caddy obtains and renews the Let's Encrypt certificate by itself.

vault.example.com {
    reverse_proxy vaultwarden:80
}

That is it — if you have seen older Vaultwarden guides with a second reverse_proxy /notifications/hub block pointing at port 3012, ignore them. WebSockets have been served on the main port since v1.29.0, and port 3012 was removed entirely in v1.31.0. The old WEBSOCKET_ENABLED and WEBSOCKET_PORT variables are deprecated and ignored; notifications work out of the box.

How do I create my first Vaultwarden account?

Open the web vault at your domain and click Create Account. Enter your email and choose your master password — and understand the one rule that defines self-hosting: this password is unrecoverable. Bitwarden's cloud has account recovery flows; your server does not. Store the master password in writing somewhere safe (a printed sheet in a drawer beats nothing) before you click create, because a forgotten master password means a permanently locked vault. Verify the email if your server has SMTP configured, then log in — you now own your password manager.

How do I stop strangers from signing up for my Vaultwarden?

Fresh out of the box, anyone who finds your URL can register — close that immediately. Set SIGNUPS_ALLOWED: "false" in the compose file once your own account exists, then run docker compose up -d again. To add family later without reopening registration, set INVITATIONS_ALLOWED: "true" and invite them from the admin panel instead — that path needs SMTP configured for the invitation email. This is the single most-skipped step in every self-hosted password manager guide, and the single most consequential.

How do I secure the Vaultwarden admin panel?

Vaultwarden has an admin panel at /admin for managing users, SMTP, and server settings. It is disabled until you set an ADMIN_TOKEN — and that token must be an Argon2 hash, not plain text. Older guides tell you to set a plain-text token; do not. Vaultwarden logs a warning for plain-text tokens and prefers the PHC hash. Generate one with the built-in command:

docker exec -it vaultwarden /vaultwarden hash

It prompts for a password twice and prints an ADMIN_TOKEN= line. Now comes the gotcha that locks half of all beginners out of their own admin panel on day one: in a compose file, $ triggers variable interpolation, so pasting the hash as-is makes Compose eat half of it and you get "Invalid admin token" with no obvious reason. Double every dollar sign — $ becomes $:

environment:
  DOMAIN: "https://vault.example.com"
  ADMIN_TOKEN: "$argon2id$v=19$m=65540,t=3,p=4$RCpl3a...$d7UfKf..."

Then docker compose up -d again. Two more things trip people up: you log in with the password you typed into the hash command, not the hash string itself — the hash is just what the server stores. And saving anything through the admin UI writes a config.json in your data folder, which overrides your environment variables from then on; if you later change ADMIN_TOKEN in compose and it seems ignored, an old config.json is the reason. Finally, do not expose /admin to the whole internet if you can avoid it: restrict it by IP at the reverse proxy, or only reach it over a private mesh — our Tailscale beginner guide shows the VPN path. A public Vaultwarden also starts collecting brute-force login attempts within hours, so point Fail2Ban at it by adding LOG_FILE: "/data/vaultwarden.log" and LOG_LEVEL: "warn".

How do I connect the official Bitwarden apps to Vaultwarden?

This is the good part: you use the real Bitwarden apps, unchanged — no sideloading, no forks. Install Bitwarden from the App Store, Play Store, or your browser's extension store. On the login screen, before logging in, open the settings/region selector (the gear icon on desktop, the region option on mobile) and set the self-hosted server URL to your https:// domain. Then log in with the account you created. Autofill and browser integration behave exactly like Bitwarden cloud. If the app refuses to connect, it is almost always TLS: an untrusted or self-signed certificate, or a DOMAIN value that does not exactly match the URL you are hitting. Fix the cert, match the domain, and it connects.

How do I enable push notifications and two-factor authentication?

Two-factor authentication lives inside the web vault under Settings → Security → Two-step Login: enable an authenticator app, and — this is the part beginners skip — write down the recovery code and store it outside the vault it protects. A locked vault with the only recovery code inside it is a riddle, not a backup. The vaultwarden push lane is separate and works through Bitwarden's push relay: request an installation ID and key from bitwarden.com/host/, add them as PUSH_INSTALLATION_ID and PUSH_INSTALLATION_KEY in your compose file, and recreate. Set the effort expectation honestly: this is the one piece that still touches Bitwarden's infrastructure, and many self-hosters simply skip it and rely on manual sync — a password manager that syncs every few minutes instead of instantly is still a password manager.

How do I back up Vaultwarden?

The vaultwarden backup rule is simple: everything lives in the volume you mounted at ./vw-data: db.sqlite3, the RSA keys, attachments, sends, and config.json. Back up the whole folder — with one wrinkle. The SQLite database can tear if you copy it while the container is writing, so never copy the live file mid-write. Either stop the container for the copy, or use SQLite's online backup, which is safe on a live database:

docker exec vaultwarden sqlite3 /data/db.sqlite3 ".backup '/data/backup.sqlite3'"

Then copy backup.sqlite3 plus the attachments and keys off the machine. A backup sitting on the same disk as the thing it is backing up is not a backup. And test a restore at least once — self-hosting your passwords with untested backups is worse than using a cloud provider, because when it fails you have no one to call.

What are the beginner mistakes that break a Vaultwarden install?

Almost every dead-on-arrival install is one of five things. Check this table before you start over.

Sources

• GitHub — dani-garcia/vaultwarden releases API (v1.37.4 published 2026-10-05: security release with 8 advisories — organization member revocation GHSA-69q9-v8p6-xvx3 High 8.1, two-factor authentication GHSA-7jg8-8m5x-6j9r Medium 6.8, organization invitations GHSA-v576-3wvq-xh3c Medium 6.8, attachments GHSA-q5x6-grh5-fqgc Medium 6.5, organization event logs GHSA-64mc-4p6f-r7x9 Medium 4.3, cipher sharing GHSA-7ccc-c43j-4p36 Medium 4.3, organization API key GHSA-v576-3wvq-xh3c Low 3.8; upgrade note: IP_HEADER now uses the rightmost non-trusted address; legacy register/prelogin endpoints removed) — repository: AGPL-3.0, ~69,978 stars, 3,386 forks, created 2018-02-17. Fetched 2026-10-31.
• amarbhattarai.com — "Self-Host Bitwarden With Vaultwarden: Setup Guide" (published July 2026, crawled 2026-10-31): the two-container compose arc, the bitwarden_rs → Vaultwarden rename at v1.21.0, WebSockets on the main port since v1.29.0 with port 3012 removed in v1.31.0, the Argon2 ADMIN_TOKEN hash with the $ compose gotcha, the config.json override gotcha, the SQLite .backup rule, the TLS/Web Crypto requirement. Checked against the live releases page — the guide's "1.34/1.35 series" note is now stale (1.37.4 is current).
• Medium — Razo Xachikyan, "Self-Host Your Password Manager on a VPS: Vaultwarden + Caddy in 15 Minutes" (updated 3 days before 2026-10-31): the 100–200 MB RAM note, the localhost-only port binding, the SIGNUPS_ALLOWED flip immediately after account creation, the backup rule (encrypted off-server copy), the push relay keys.
• ithomelab.online — "Vaultwarden Docker Self-Hosted Password Manager" (103 days before 2026-10-31): the Tailscale branch, the gear-icon server URL in clients, the master-password warning, the vw-data backup.
• blog.byte-guard.net — "Self-Host Vaultwarden" (101 days before 2026-10-31): the client-connection arc, the 2FA and recovery-code warning.

Frequently asked questions

Is Vaultwarden safe for real passwords?

Yes, with the usual caveats of self-hosting anything sensitive. Your vault is encrypted client-side before it ever leaves your devices, so the server only ever stores ciphertext. Your real risks are operational, not cryptographic: no HTTPS, an exposed admin panel, or missing backups. Handle those three — a real domain with Let's Encrypt, ADMIN_TOKEN hashed and /admin restricted, and an off-machine tested backup — and it is solid.

Does Vaultwarden work with the official Bitwarden apps?

Yes — every official client (browser extension, desktop app, iOS, Android) works unmodified. You only change one thing: the self-hosted server URL on the login screen, set to your https:// domain before you sign in. Autofill, browser integration, and 2FA behave exactly like Bitwarden cloud afterward.

Can I run Vaultwarden without a domain or HTTPS?

Not usefully. Browsers block the Web Crypto API that Bitwarden clients need on insecure origins, and the mobile apps reject self-signed certificates, so clients refuse to connect. Use a real domain with a real certificate (Caddy gets you one free via Let's Encrypt). The only exception is localhost, which browsers treat as a secure context for local testing.

How much RAM does Vaultwarden need?

Very little. The container idles at roughly 10 MB and runs happily on a Raspberry Pi or the cheapest VPS tier — the reverse proxy beside it typically uses more memory than Vaultwarden does. The official self-hosted Bitwarden server, by contrast, needs around 2 GB at idle, which is the whole reason the lightweight lane exists.

What happens if I forget my Vaultwarden master password?

Your vault is locked permanently. Self-hosting means there is no Bitwarden support desk that can recover it — the encryption keys derive from the master password, and nobody, including you, can recreate it from nothing. Store the master password somewhere safe (written on paper beats a second digital copy in the same house) before you create the account, and keep the 2FA recovery code outside the vault.