> ## Documentation Index
> Fetch the complete documentation index at: https://docs.suji.fr/llms.txt
> Use this file to discover all available pages before exploring further.

# Vaultwarden

> Self-hosted, Bitwarden-compatible password manager. Install, create your account, and lock it down.

[Vaultwarden](https://github.com/dani-garcia/vaultwarden) is a lightweight, self-hosted password manager that speaks the Bitwarden protocol — so the official Bitwarden **browser extensions, desktop, mobile, and CLI clients all work against it unchanged**. It's a single container with a small SQLite database, so it's one of the lightest apps in the catalog.

This page covers running Vaultwarden on Suji end-to-end. Vaultwarden is maintained upstream; Suji provides the [marketplace packaging](https://github.com/suji-hq/suji-templates/tree/main/vaultwarden).

<Note>
  The first person to open the URL can create an account. Register yours immediately after install, then close sign-ups (see [Lock it down](#lock-it-down)).
</Note>

***

## Install

Dashboard → **Apps** → **Vaultwarden** → **Install**:

| Field              | Required | Notes                                                                                  |
| ------------------ | -------- | -------------------------------------------------------------------------------------- |
| VM                 | yes      | Single container, \~512 MB. Fits any VM size.                                          |
| Subdomain          | no       | Suggestion is `vault`. Reached at `https://<subdomain>.suji.fr`.                       |
| Allow new sign-ups | no       | Leave **Yes** to register your account, then switch to **No** afterwards.              |
| Admin panel token  | no       | Leave blank to keep `/admin` disabled (recommended). Set a strong secret to enable it. |

You don't enter a URL — Suji wires the public `https://<subdomain>.suji.fr` into Vaultwarden's `DOMAIN` automatically, which is what makes WebAuthn / two-step login and attachments work.

Click **Deploy**. When the install is `running`, it's live at `https://vault-<random>.suji.fr` over HTTPS through the tunnel.

***

## First connection — create your account

1. Open the install URL (`https://vault-<random>.suji.fr`).
2. Click **Create account** and register (email + master password).
3. Install a [Bitwarden client](https://bitwarden.com/download/) (browser extension, desktop, or mobile).
4. In the client, **before logging in**, open settings and set the **Server URL** (self-hosted) to your `https://vault-<random>.suji.fr` address.
5. Log in with the account you just created. Your vault syncs.

<Warning>
  Your **master password cannot be recovered**. If you lose it, the vault is unreadable — that's by design (Vaultwarden never sees it). Store it somewhere safe and consider setting up a recovery method in the client.
</Warning>

***

## Lock it down

Vaultwarden ships with sign-ups **open** so you can create your first account. As soon as you (and anyone you intend to invite) have registered:

1. Go to the install detail page → **Edit Install**.
2. Set **Allow new sign-ups** to **No**.
3. Redeploy.

Now nobody else can register against your vault. Existing accounts keep working.

To invite users after closing sign-ups, enable the admin panel: set a strong **Admin panel token** in **Edit Install**, redeploy, then open `https://vault-<random>.suji.fr/admin`, log in with that token, and send invites from there.

***

## Two-step login (2FA)

Because Suji wires the public `DOMAIN` for you, security keys (WebAuthn / FIDO2 / passkeys) and authenticator-app (TOTP) two-step login work out of the box — enable them from the web vault under **Settings → Security → Two-step login**.

<Note>
  Email-based 2FA and password-hint / invite emails need an SMTP server, which isn't configured by default — see [Email](#email).
</Note>

***

## Email

Vaultwarden sends email for invites, password hints, and email-based 2FA — but **no mail provider is configured by default**, so those won't send until you add SMTP. The network blocks outbound SMTP on ports 25 and 465; use port 587 or an HTTP-based provider. Add the `SMTP_*` env vars yourself via **Edit Install → environment variables**, then redeploy.

***

## Day-to-day management

| Want to…                          | Where                                                                    |
| --------------------------------- | ------------------------------------------------------------------------ |
| Manage your passwords             | The web vault (`https://vault-<random>.suji.fr`) or any Bitwarden client |
| Invite / manage users             | `/admin` panel (set an Admin panel token first)                          |
| View container logs               | Dashboard → Logs (pick Vaultwarden)                                      |
| Open a shell inside the container | Dashboard → Terminal (pick Vaultwarden)                                  |
| Restart the app                   | Install detail page → Restart                                            |
| Upgrade to a newer version        | Install detail page → Upgrade (when available)                           |
| Remove the install + its data     | Install detail page → Uninstall                                          |

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="A Bitwarden client won't connect">
    Set the **Server URL** in the client to your full `https://vault-<random>.suji.fr` address **before** logging in — not the default Bitwarden cloud server.
  </Accordion>

  <Accordion title="Security-key / passkey 2FA fails">
    WebAuthn needs the public `DOMAIN`, which Suji sets only when the install is **exposed**. Make sure exposure is on (it is by default) and you're reaching the vault over its `https://…suji.fr` URL, not an internal address.
  </Accordion>

  <Accordion title="I can't reach /admin">
    The admin panel is disabled unless an **Admin panel token** is set. Add one via Edit Install, redeploy, then log in at `/admin` with that exact value.
  </Accordion>

  <Accordion title="Invite / hint emails aren't sending">
    Expected until you configure SMTP — see Email above (use port 587; 25/465 are blocked upstream).
  </Accordion>
</AccordionGroup>

***

## Where things live

| What                                | Service       | Named volume       |
| ----------------------------------- | ------------- | ------------------ |
| Vault db, attachments, keys, config | `vaultwarden` | `vaultwarden-data` |

Uninstalling deletes the volume by default — **that's every vault**. Choose **keep data** during uninstall to preserve it, and keep your own export as a backup.

***

## Recommended size

* **Any size.** Vaultwarden is a single lightweight container (\~512 MB) and runs comfortably on the smallest VM.
* Storage grows mainly with file attachments; the password data itself is tiny.

***

## Reporting issues

| Class                                                         | Where                                                                               |
| ------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| Vaultwarden bug (vault, sync, admin panel)                    | [dani-garcia/vaultwarden issues](https://github.com/dani-garcia/vaultwarden/issues) |
| Marketplace packaging bug (compose / manifest / install form) | [suji-hq/suji-templates issues](https://github.com/suji-hq/suji-templates/issues)   |
| Suji platform bug (dashboard, billing, network)               | Support ticket from the dashboard                                                   |