How to Self-Host Vaultwarden: Complete Guide to Installation, HTTPS, Security, and Remote Access

What Is Vaultwarden?

Vaultwarden (formerly known as bitwarden_rs) is an unofficial, community-maintained alternative implementation of the Bitwarden server API, written in Rust. It was created by dani-garcia and is currently maintained by a small team of contributors. Vaultwarden is not affiliated with Bitwarden Inc., but one of its active maintainers is employed by Bitwarden and contributes to the project independently in their own time.

What makes Vaultwarden special is the combination of full Bitwarden client compatibility with dramatically lower resource usage. The official Bitwarden server requires 11 separate Docker containers and substantial RAM to run. Vaultwarden runs as a single container and uses under 50 MB of RAM at idle, making it practical to run on a Raspberry Pi alongside other services.

Vaultwarden vs Bitwarden vs 1Password

Why HTTPS Is Mandatory for Vaultwarden

Vaultwarden uses the Web Crypto API in the browser to perform all encryption and decryption of vault data on the client side. The Web Crypto API is only available in secure contexts. A secure context means either http://localhost (same machine only) or any https:// URL. There is no workaround or configuration option to bypass this.

In practice this means: you cannot access your Vaultwarden instance from any other device using plain HTTP. If you try, the web vault UI will load but all cryptographic operations will silently fail. You must serve Vaultwarden over HTTPS for it to work from any device other than localhost.

There are three ways to get HTTPS for a self-hosted Vaultwarden:

• Own a domain + Let's Encrypt: Traditional approach. Requires a domain, a reverse proxy (Caddy or Nginx), and open ports 80/443 on your router. Does not work behind CGNAT.
• Self-signed certificate: Works but requires manually trusting the certificate on every device. Causes browser warnings and breaks most mobile apps.
• Localtonet tunnel (recommended for home use): Localtonet provides a public HTTPS URL instantly. No domain needed, no port forwarding, works behind CGNAT. This is the method this guide focuses on.

Requirements

Installation: Docker Compose

Step 1: Install Docker

# Linux (Ubuntu, Debian, Raspberry Pi OS 64-bit):
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker $USER
# Log out and back in, then verify:
docker --version
docker compose version

Expected output:

Docker version 27.x.x, build xxxxxxx
Docker Compose version v2.x.x

Step 2: Generate the ADMIN_TOKEN (Argon2)

The ADMIN_TOKEN protects the Vaultwarden admin panel at /admin. Since Vaultwarden version 1.28.0, plain-text tokens trigger a security warning in the logs. The correct method is to generate an Argon2id hash using the Vaultwarden binary itself:

# Run a temporary Vaultwarden container just to generate the hash:
docker run --rm -it vaultwarden/server:latest /vaultwarden hash

You will be prompted to enter and confirm a password. Use a strong password (this is what you will type to log into the admin panel). Expected output:

Generate an Argon2id PHC string using the 'bitwarden' preset:
Password:
Confirm Password:
ADMIN_TOKEN='$argon2id$v=19$m=65540,t=3,p=4$SomeRandomSalt$SomeHashString'

Copy the hash string (everything between the single quotes, without the quotes themselves). You will use it in the next step.

Step 3: Create project directory and .env file

mkdir ~/vaultwarden && cd ~/vaultwarden

Create the .env file. Paste your Argon2 hash as-is, with no escaping, no quotes:

cat > .env << 'ENVEOF'
# Replace the value below with your actual Argon2 hash (no quotes, no $$ escaping):
ADMIN_TOKEN=$argon2id$v=19$m=65540,t=3,p=4$YourSaltHere$YourHashHere

# Set to false after creating your account:
SIGNUPS_ALLOWED=true

# Will be set to your Localtonet public URL in a later step:
DOMAIN=https://localhost

# Timezone:
TZ=Europe/Istanbul
ENVEOF

Step 4: Create docker-compose.yml

cat > docker-compose.yml << 'EOF'
services:
  vaultwarden:
    image: vaultwarden/server:latest
    container_name: vaultwarden
    restart: unless-stopped
    ports:
      - "127.0.0.1:8080:80"
    volumes:
      - ./vw-data:/data
    env_file: .env
    environment:
      - ADMIN_TOKEN=${ADMIN_TOKEN}
      - SIGNUPS_ALLOWED=${SIGNUPS_ALLOWED}
      - DOMAIN=${DOMAIN}
      - TZ=${TZ}
      - LOG_FILE=/data/vaultwarden.log
      - LOG_LEVEL=warn
      - EXTENDED_LOGGING=true
EOF

Notice that the port binding is 127.0.0.1:8080:80, not 0.0.0.0:8080:80. This means Vaultwarden only accepts connections from the local machine. External access goes through the Localtonet tunnel, which connects to localhost. This is more secure than binding to all interfaces.

Step 5: Start Vaultwarden

docker compose up -d

# Verify the container is running:
docker compose ps

Expected output:

NAME          IMAGE                      STATUS
vaultwarden   vaultwarden/server:latest  Up 30 seconds

# Check startup logs for any errors:
docker compose logs vaultwarden

Expected log output (no errors):

[vaultwarden::config] Running on 0.0.0.0:80
[vaultwarden::api] Starting web server on 0.0.0.0:80

At this point Vaultwarden is running on http://localhost:8080. You can open it in a browser on the same machine to verify it loads. It will not work fully yet because HTTPS is required for the Web Crypto API. The next step adds HTTPS via Localtonet.

Setting Up HTTPS with Localtonet

Localtonet creates an encrypted outbound tunnel from your machine to a public HTTPS endpoint. Vaultwarden running on localhost:8080 becomes accessible at a public https:// URL. This satisfies the Web Crypto API secure context requirement, and the Bitwarden mobile apps and browser extensions can connect from any network. No port forwarding, no domain purchase, works behind CGNAT.

# Linux / Raspberry Pi OS:
curl -fsSL https://localtonet.com/install.sh | sh

# Verify:
localtonet --version

localtonet --authtoken YOUR_TOKEN_HERE

# Edit .env and change:
DOMAIN=https://myvault.localto.net

docker compose restart vaultwarden

sudo localtonet --install-service --authtoken YOUR_TOKEN_HERE
sudo localtonet --start-service --authtoken YOUR_TOKEN_HERE

First Login and Critical Security Steps

Create your account

Open your public HTTPS URL (e.g. https://myvault.localto.net) in your browser. Click Create Account and register with your email and a strong master password. This is the password that encrypts your vault. Write it down and store it somewhere physically safe. There is absolutely no way to recover a lost master password.

Disable open registration immediately

After creating your account (and any other accounts for family or team members), disable open registration so no one else can create an account on your instance:

# Edit .env and change:
SIGNUPS_ALLOWED=false

# Restart:
docker compose restart vaultwarden

Alternatively, you can manage this from the admin panel. Navigate to https://myvault.localto.net/admin, enter the password you used to generate the Argon2 hash, go to General Settings, uncheck Allow new signups, and click Save.

Enable Two-Factor Authentication

Log into your vault, go to Settings → Security → Two-step Login. Vaultwarden supports TOTP (authenticator apps like Aegis, Google Authenticator, Authy), email codes, and FIDO2/WebAuthn hardware keys. Enable at least TOTP. Scan the QR code with your authenticator app and confirm with a code before saving.

Invite additional users from the admin panel

With SIGNUPS_ALLOWED=false, new users cannot self-register. Instead, invite them from /admin: go to Users → Invite User, enter their email address, and they receive an invitation link. Invitations require SMTP email to be configured; alternatively, you can create accounts by temporarily setting SIGNUPS_ALLOWED=true, having them register, then setting it back to false.

Connecting Bitwarden Clients to Your Vaultwarden

Vaultwarden works with all official Bitwarden clients without modification. You just need to tell each client the server URL. Bitwarden clients default to the official Bitwarden cloud; you change this once during login setup and the client remembers it.

Raspberry Pi Installation

Vaultwarden is one of the best services to run on a Raspberry Pi. It is so lightweight that it runs comfortably even on a Pi Zero 2W (512 MB RAM). The Pi 4 and Pi 5 are ideal for running Vaultwarden alongside other services.

Install Docker on Raspberry Pi

sudo apt update && sudo apt upgrade -y

# Install Docker:
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker pi
# Log out and back in

# Verify:
docker --version
docker compose version

Install Vaultwarden on Raspberry Pi

The Docker Compose setup from the installation section above works on Raspberry Pi without any changes. The vaultwarden/server:latest image includes an ARM64 build and Docker automatically pulls the correct architecture.

mkdir ~/vaultwarden && cd ~/vaultwarden
# Create .env and docker-compose.yml as shown above
docker compose up -d

# Check resource usage on Pi:
docker stats vaultwarden --no-stream

Expected output (Pi 4, idle):

NAME          CPU %   MEM USAGE / LIMIT   MEM %
vaultwarden   0.00%   48MiB / 3.7GiB      1.27%

Keep Vaultwarden always running on Pi

The restart: unless-stopped directive in docker-compose.yml already handles restarts on crash. To ensure it starts on boot, enable Docker to start at boot:

sudo systemctl enable docker

Docker Compose services with restart: unless-stopped start automatically when Docker starts. No additional configuration is needed.

Storing vault data on an external drive (Pi)

The vault database and attachments are stored in ./vw-data (the bind mount). On a Pi, this defaults to the SD card. For reliability, move it to a USB SSD:

# Mount USB SSD:
sudo mkdir -p /mnt/vault-data
sudo mount /dev/sda1 /mnt/vault-data

# Make permanent:
echo "UUID=$(sudo blkid -s UUID -o value /dev/sda1)  /mnt/vault-data  ext4  defaults,nofail  0  2" | sudo tee -a /etc/fstab

# Update the volume path in docker-compose.yml:
# Change: - ./vw-data:/data
# To:     - /mnt/vault-data:/data

docker compose down && docker compose up -d

Backing Up Vaultwarden

Vaultwarden stores all data in the /data directory inside the container (mounted as ./vw-data on the host). This directory contains:

Backup script (runs without stopping Vaultwarden)

#!/bin/bash
# Save as ~/vaultwarden/backup.sh
# Add to cron: 0 2 * * * ~/vaultwarden/backup.sh

BACKUP_DIR=~/vaultwarden-backups/$(date +%F_%H%M)
mkdir -p "$BACKUP_DIR"

# 1. Create a consistent SQLite backup using the .backup command:
sqlite3 ~/vaultwarden/vw-data/db.sqlite3 \
  ".backup '$BACKUP_DIR/db.sqlite3'"

# 2. Back up attachments, sends, config, and RSA keys:
rsync -a ~/vaultwarden/vw-data/attachments/ "$BACKUP_DIR/attachments/" 2>/dev/null || true
rsync -a ~/vaultwarden/vw-data/sends/ "$BACKUP_DIR/sends/" 2>/dev/null || true
cp ~/vaultwarden/vw-data/config.json "$BACKUP_DIR/" 2>/dev/null || true
cp ~/vaultwarden/vw-data/rsa_key* "$BACKUP_DIR/" 2>/dev/null || true

# 3. Back up the .env file (contains ADMIN_TOKEN):
cp ~/vaultwarden/.env "$BACKUP_DIR/.env.backup"

echo "Backup complete: $BACKUP_DIR"

# 4. Keep only last 14 days of backups:
find ~/vaultwarden-backups -maxdepth 1 -type d -mtime +14 -exec rm -rf {} +

# Make executable and test:
chmod +x ~/vaultwarden/backup.sh
~/vaultwarden/backup.sh

# Add to cron (runs at 2 AM daily):
(crontab -l 2>/dev/null; echo "0 2 * * * ~/vaultwarden/backup.sh") | crontab -

Restore from backup

# Stop Vaultwarden first:
docker compose down

# Remove existing database files (including WAL):
rm ~/vaultwarden/vw-data/db.sqlite3*

# Copy the backup database:
cp ~/vaultwarden-backups/YYYY-MM-DD_HHMM/db.sqlite3 ~/vaultwarden/vw-data/db.sqlite3

# Restore attachments and other files:
rsync -a ~/vaultwarden-backups/YYYY-MM-DD_HHMM/attachments/ ~/vaultwarden/vw-data/attachments/
cp ~/vaultwarden-backups/YYYY-MM-DD_HHMM/config.json ~/vaultwarden/vw-data/

# Start Vaultwarden:
docker compose up -d

Fail2Ban: Protecting Against Brute-Force Attacks

Vaultwarden logs failed login attempts to /data/vaultwarden.log (when LOG_FILE and LOG_LEVEL=warn are set). Fail2Ban reads this log and bans IP addresses that make too many failed attempts. The Docker Compose setup below adds Fail2Ban as a sidecar container.

# Add to docker-compose.yml services section:

  fail2ban:
    image: crazymax/fail2ban:latest
    container_name: fail2ban
    restart: unless-stopped
    network_mode: host
    cap_add:
      - NET_ADMIN
      - NET_RAW
    volumes:
      - ./vw-data:/vaultwarden/data:ro
      - ./fail2ban:/data

# Create Fail2Ban jail config:
mkdir -p ./fail2ban/jail.d

cat > ./fail2ban/jail.d/vaultwarden.local << 'EOF'
[vaultwarden]
enabled = true
port = 80,443,8080
filter = vaultwarden
logpath = /vaultwarden/data/vaultwarden.log
maxretry = 5
bantime = 14400
findtime = 14400

[vaultwarden-admin]
enabled = true
port = 80,443,8080
filter = vaultwarden-admin
logpath = /vaultwarden/data/vaultwarden.log
maxretry = 3
bantime = 14400
findtime = 14400
EOF

# Create Fail2Ban filters:
mkdir -p ./fail2ban/filter.d

cat > ./fail2ban/filter.d/vaultwarden.conf << 'EOF'
[Definition]
failregex = ^.*Username or password is incorrect\. Try again\. IP: .*$
            ^.*Failed to verify the CAPTCHA\. IP: .*$
ignoreregex =
EOF

cat > ./fail2ban/filter.d/vaultwarden-admin.conf << 'EOF'
[Definition]
failregex = ^.*Invalid admin token\. IP: .*$
ignoreregex =
EOF

docker compose up -d fail2ban

Updating Vaultwarden

Vaultwarden releases updates frequently. Updating is a two-command operation with Docker Compose:

cd ~/vaultwarden

# Pull the latest image:
docker compose pull vaultwarden

# Recreate the container with the new image:
docker compose up -d vaultwarden

# Confirm the new version:
docker exec vaultwarden /vaultwarden --version

Vaultwarden handles database migrations automatically on startup. No manual migration steps are required for most updates. Always run your backup script before pulling a new version:

~/vaultwarden/backup.sh && docker compose pull && docker compose up -d

Important Environment Variables Reference

Troubleshooting

Frequently Asked Questions