Vaultwarden — Administrator & Developer Guide

1. Architecture Overview

Vaultwarden is an unofficial, lightweight implementation of the Bitwarden server API written in Rust. It replaces the official multi-container .NET Bitwarden server with a single binary that implements the complete Bitwarden client API (268 endpoints), enabling compatibility with all official Bitwarden clients. The project is licensed under AGPL-3.0-only.

The server is built on the Rocket web framework with Diesel ORM for database access and supports SQLite, PostgreSQL, and MySQL/MariaDB backends. All authentication uses RS256 JWT tokens with an auto-generated RSA-2048 key pair. Configuration is driven entirely through environment variables processed by a custom make_config! macro that generates a type-safe configuration system with validation, admin panel integration, and runtime updates.

Architecture Diagram

┌─────────────────────────────────────────────────────────┐
│                    Bitwarden Clients                     │
│  (Browser, Desktop, Mobile, CLI)                        │
└──────────────────────┬──────────────────────────────────┘
                       │ HTTPS (via reverse proxy)
┌──────────────────────▼──────────────────────────────────┐
│                   Vaultwarden Binary                     │
│  ┌─────────────┐  ┌──────────┐  ┌────────────────────┐ │
│  │ Rocket HTTP  │  │ WebSocket│  │ Admin Panel (HBS)  │ │
│  │ Server       │  │ Hub      │  │                    │ │
│  └──────┬──────┘  └────┬─────┘  └────────┬───────────┘ │
│         │              │                  │              │
│  ┌──────▼──────────────▼──────────────────▼───────────┐ │
│  │                   API Layer                         │ │
│  │  /api/* (core)  /identity/* (auth)  /admin/*       │ │
│  │  /icons/*       /notifications/*    /events/*      │ │
│  └──────────────────────┬─────────────────────────────┘ │
│         │               │                │               │
│  ┌──────▼───┐  ┌───────▼────┐  ┌───────▼────────────┐  │
│  │ Auth/JWT  │  │ Diesel ORM │  │ Background Jobs    │  │
│  │ (RS256)   │  │            │  │ (job_scheduler_ng) │  │
│  └──────────┘  └──────┬─────┘  └────────────────────┘  │
│                        │                                 │
└────────────────────────┼─────────────────────────────────┘
                         │
              ┌──────────▼──────────┐
              │   Database Backend   │
              │  SQLite / PostgreSQL │
              │  / MySQL-MariaDB     │
              └─────────────────────┘

Note

Vaultwarden compiles database support via Cargo feature flags. The official Docker images include all three backends. Source builds must choose one: --features sqlite, --features postgresql, or --features mysql.

Component Inventory

Technology Stack

2. System Requirements

Hardware

Software

Supported Platforms

3. Configuration Reference

Vaultwarden uses a custom make_config! macro that generates a type-safe configuration system. All settings are environment variables (uppercased). Settings can also be modified at runtime through the admin panel (editable settings only) and are persisted to config.json in the data folder.

Important

Environment variables set at startup take precedence initially, but admin panel changes are persisted to config.json which overrides environment variables on subsequent startups. If a setting appears in both, the config.json value wins and a warning is logged listing the overridden variables.

Folders

WebSocket

Push Notifications

Important

Push relay and identity URIs must start with https://. All three push settings (enabled, ID, key) must be configured together.

Scheduled Jobs

All cron schedules use 6-field cron syntax (sec min hour day month weekday). Set a schedule to empty string to disable that job. Set JOB_POLL_INTERVAL_MS=0 to disable all scheduled jobs.

General Settings

Advanced Settings

OpenID Connect SSO Settings

Warning

SSO_CLIENT_ID, SSO_CLIENT_SECRET, and SSO_AUTHORITY must all be set when SSO_ENABLED=true. The authority URL must not include /.well-known/openid-configuration.

YubiKey Settings

Both YUBICO_CLIENT_ID and YUBICO_SECRET_KEY must be set together for custom YubiKey OTP support. Without them, the default YubiCloud service is used.

Duo Settings

All three Duo settings (DUO_IKEY, DUO_SKEY, DUO_HOST) must be set together for global Duo support. Individual users can also configure their own Duo credentials.

SMTP Email Settings

Caution

SMTP_DEBUG=true outputs full SMTP session data including credentials. Only use during active troubleshooting and disable immediately after.

Email 2FA Settings

Email 2FA requires a working mail transport (SMTP_HOST or USE_SENDMAIL). It is automatically enabled when SMTP is configured and a mail transport is available.

Other Environment Variables

4. Deployment & Scaling

Docker Deployment

Official images are built for four architectures from both Debian (trixie-slim) and Alpine (3.23) base images.

Production Docker Compose:

services:
  vaultwarden:
    image: vaultwarden/server:latest
    container_name: vaultwarden
    restart: unless-stopped
    environment:
      DOMAIN: "https://vw.example.com"
      SIGNUPS_ALLOWED: "false"
      ADMIN_TOKEN: "${ADMIN_TOKEN}"
      SMTP_HOST: "smtp.example.com"
      SMTP_FROM: "[email removed]"
      SMTP_PORT: "587"
      SMTP_SECURITY: "starttls"
      SMTP_USERNAME: "${SMTP_USER}"
      SMTP_PASSWORD: "${SMTP_PASS}"
      PUSH_ENABLED: "true"
      PUSH_INSTALLATION_ID: "${PUSH_ID}"
      PUSH_INSTALLATION_KEY: "${PUSH_KEY}"
    volumes:
      - ./vw-data/:/data/
    ports:
      - "127.0.0.1:8080:80"

Tip

Bind to 127.0.0.1 when running behind a reverse proxy to prevent direct external access to the unencrypted port.

S3 Storage

Set DATA_FOLDER to an S3 URL to store all data (database, attachments, sends, keys) in S3-compatible storage:

DATA_FOLDER=s3://my-vaultwarden-bucket/data

The s3 feature flag must be enabled (included in official Docker images). Vaultwarden uses the standard AWS credential chain via the official AWS SDK for credential resolution, supporting IAM roles, environment variables, SSO profiles, and credential files.

Reverse Proxy Configuration

Vaultwarden requires a reverse proxy for production HTTPS. Key considerations:

• Pass the X-Real-IP header (or set IP_HEADER to your proxy's header name)
• Forward WebSocket connections for real-time notifications
• The /alive endpoint is suitable for health checks

Healthcheck (used in Docker):

curl --insecure --fail --silent --show-error \
  "http://localhost:${ROCKET_PORT}/alive"

Source Build for Production

cargo build --release --features "sqlite,enable_mimalloc"

Available feature flags:

5. Operations

Background Jobs

Vaultwarden runs 9 scheduled background jobs in a dedicated scheduler thread:

Tip

All schedules use 6-field cron syntax (second minute hour day month weekday). Set any schedule to an empty string to disable that specific job. Set JOB_POLL_INTERVAL_MS=0 to disable all jobs.

Backup

SQLite backup methods:

1. CLI command: ./vaultwarden backup — creates db_YYYYMMDD_HHMMSS.sqlite3 in the data folder
2. Signal (Unix): kill -USR1 $(pidof vaultwarden) — triggers hot backup while running
3. File copy: Stop the server, copy db.sqlite3 and related WAL/SHM files

Note

The backup command and USR1 signal are SQLite-only. PostgreSQL and MySQL require native database backup tools (pg_dump, mysqldump).

Critical files to back up:

Monitoring

• Health endpoint: GET /alive — returns 200 when the server is running
• Log levels: Configure via LOG_LEVEL with per-module overrides

# Enable query logging (slow queries only)
LOG_LEVEL=info,vaultwarden::db::query_logger=warn

# Full query logging
LOG_LEVEL=info,vaultwarden::db::query_logger=debug

Tip

Query logger levels: warn = queries over 5 seconds, info = queries over 1 second, debug = all queries.

Signal Handling

6. Performance

Database Tuning

Memory Optimization

• Enable mimalloc via the enable_mimalloc feature flag for improved memory allocation performance
• The Rocket request limits are fixed: 20 MB for JSON, 525 MB for data-form and file uploads (matches Bitwarden Send max file size)

Icon Caching

7. Security

Authentication Architecture

Vaultwarden uses RS256 JWT tokens signed with an auto-generated RSA-2048 key pair stored at {DATA_FOLDER}/rsa_key.pem. If the key file doesn't exist, it is generated automatically on first startup.

Token types and lifetimes:

Warning

The RSA private key (rsa_key.pem) is the root of trust for all authentication. If this file is compromised, all tokens can be forged. Protect it with restrictive file permissions and include it in backup procedures.

Rate Limiting

Admin Panel Security

The admin token supports two formats:

1. Argon2id PHC string (recommended): Generated via vaultwarden hash
2. Plain text (insecure): Generates a startup warning recommending migration to Argon2id

Set DISABLE_ADMIN_TOKEN=true only when the admin panel is protected by an external authentication layer (e.g., reverse proxy auth).

Network Security

Caution

Disabling HTTP_REQUEST_BLOCK_NON_GLOBAL_IPS may expose internal network services to SSRF attacks through the icon fetching functionality.

Password Security

• Server-side hashing uses PBKDF2-SHA256 with PASSWORD_ITERATIONS (default: 600,000, minimum: 100,000)
• The iteration count is updated on login if the configured value changes
• SHOW_PASSWORD_HINT=true exposes password hints without authentication — not recommended for public instances

Two-Factor Authentication Security

• DISABLE_2FA_REMEMBER=true forces 2FA on every login
• AUTHENTICATOR_DISABLE_TIME_DRIFT=true accepts only the current 30-second TOTP window
• Incomplete 2FA attempts (correct password, missing 2FA) trigger email notifications after INCOMPLETE_2FA_TIME_LIMIT minutes
• WebAuthn requires DOMAIN to be set with an HTTPS scheme and a valid domain name

SSO Security Considerations

• SSO_ALLOW_UNKNOWN_EMAIL_VERIFICATION=true with SSO_SIGNUPS_MATCH_EMAIL=true creates an account takeover risk — only use with trusted identity providers
• SSO_PKCE=true (default) adds PKCE protection to the OIDC authorization flow
• SSO_AUDIENCE_TRUSTED accepts a regex — validate that it cannot match unintended audiences

8. Developer Internals

Repository Structure

vaultwarden/
├── src/
│   ├── main.rs                 Entry point, CLI, startup sequence
│   ├── config.rs               make_config! macro, env var processing
│   ├── auth.rs                 JWT authentication, request guards
│   ├── crypto.rs               PBKDF2, HMAC, random generation
│   ├── error.rs                Error types, API error formatting
│   ├── mail.rs                 Email sending (SMTP/sendmail)
│   ├── http_client.rs          Outbound HTTP with IP blocking
│   ├── ratelimit.rs            Rate limiting implementation
│   ├── sso.rs                  SSO/OIDC flow logic
│   ├── sso_client.rs           OIDC client configuration
│   ├── util.rs                 Shared utilities
│   ├── api/
│   │   ├── mod.rs              Route registration
│   │   ├── admin.rs            Admin panel routes
│   │   ├── icons.rs            Favicon proxy/cache
│   │   ├── notifications.rs    WebSocket hub
│   │   ├── web.rs              Static file serving
│   │   ├── identity/           Login, token, SSO endpoints
│   │   └── core/
│   │       ├── accounts.rs     User account management
│   │       ├── ciphers.rs      Vault item CRUD
│   │       ├── collections.rs  Collection management
│   │       ├── folders.rs      Folder management
│   │       ├── organizations.rs Organization management
│   │       ├── sends.rs        Bitwarden Send
│   │       ├── emergency_access.rs Emergency access
│   │       ├── events.rs       Event logging
│   │       └── two_factor/     2FA implementations
│   │           ├── authenticator.rs  TOTP
│   │           ├── webauthn.rs       WebAuthn/FIDO2
│   │           ├── duo.rs / duo_oidc.rs  Duo Security
│   │           ├── yubikey.rs        YubiKey OTP
│   │           └── email.rs          Email 2FA
│   └── db/
│       ├── mod.rs              Database pool, migrations
│       ├── schemas/            Diesel table schemas
│       └── models/             Entity models (User, Cipher, etc.)
├── migrations/                 Database migration files per backend
├── macros/                     Procedural macros (db_* derives)
├── docker/                     Docker build infrastructure
├── playwright/                 End-to-end browser tests
└── Cargo.toml                  Dependencies and feature flags

Configuration System Deep Dive

The make_config! macro in src/config.rs is the central configuration mechanism. It generates:

1. ConfigBuilder — a struct where all fields are Option<T>, populated from environment variables and config.json
2. ConfigItems — the resolved configuration with concrete types and defaults applied
3. Config — the thread-safe wrapper (RwLock<Inner>) exposed as a global CONFIG static
4. Admin panel data — prepare_json() serializes all settings for the web admin UI
5. Support diagnostics — get_support_json() masks sensitive values for diagnostic output

The config loading order is:

1. .env file (via dotenvy)
2. Environment variables → ConfigBuilder::from_env()
3. config.json → ConfigBuilder::from_file()
4. Merge: env ← config.json (config.json overrides env for editable settings)
5. Build: apply defaults, auto-computed values, and generated values
6. Validate: validate_config() checks constraints

Request Guard System

Rocket request guards enforce authentication and authorization at the type level:

API Surface

Vaultwarden implements 268 API endpoints across these mount points:

Database Migrations

Diesel migrations are organized per backend in the migrations/ directory. Migrations run automatically on startup. The application also performs data migrations in code:

• TwoFactor::migrate_u2f_to_webauthn() — migrates legacy U2F registrations to WebAuthn
• TwoFactor::migrate_credential_to_passkey() — migrates credentials to passkey format

Testing

End-to-end tests use Playwright in playwright/ and cover:

• SSO login flows
• 2FA setup and verification (TOTP, Email)
• Organization management
• Collection creation and assignment

Code Patterns

• Error handling: Custom make_error! macro generates a unified Error type wrapping 20+ source error types with err!() / err_handler!() macros for ergonomic error creation
• Lazy statics: LazyLock for global configuration, JWT keys, compiled regexes
• Atomic operations: OnceLock for RSA keys (initialized once, then immutable)
• Template rendering: Handlebars with custom helpers (case, to_json, webver, vwver)
• Feature flags: Compile-time (cfg(sqlite), cfg(s3)) and runtime (SUPPORTED_FEATURE_FLAGS for client-side flags)

9. Integration Points

Bitwarden Client Compatibility

Vaultwarden implements the Bitwarden API surface to be compatible with all official clients. The web vault version (v2026.2.0) is bundled and served by the server. Client version detection uses the Bitwarden-Client-Version header.

Push Notification Relay

Push notifications require registration with the Bitwarden push relay service:

1. Register at https://bitwarden.com/host to get installation ID and key
2. Set PUSH_ENABLED=true, PUSH_INSTALLATION_ID, and PUSH_INSTALLATION_KEY
3. Notifications are relayed through PUSH_RELAY_URI (default: https://push.bitwarden.com)

OIDC Identity Providers

Vaultwarden supports any OpenID Connect compliant provider. The callback URL is {DOMAIN}/identity/connect/oidc-signin.

Email Integration

28 email templates (HTML + plain text) are built in, covering all user lifecycle events. Templates use Handlebars and can be overridden by placing .hbs files in the templates folder.

HaveIBeenPwned

Set HIBP_API_KEY to enable password breach checking through the HaveIBeenPwned API.

Container Startup Hooks

Docker containers source shell scripts before starting:

1. /etc/vaultwarden.sh — single initialization script
2. /etc/vaultwarden.d/*.sh — directory of initialization scripts

Legacy paths (/etc/bitwarden_rs.sh, /etc/bitwarden_rs.d/) are supported with deprecation warnings.