The Passbox server is configured with environment variables. Every setting is also available as a command-line option. In the Docker Compose setup, add variables to the environment section of the passbox service. The Compose file already sets some of them from .env.
All settings
Basics and database
| Variable | Default | Meaning |
|---|---|---|
PASSBOX_BIND | 0.0.0.0:8080 | Address and port the server listens on |
PASSBOX_DATABASE_URL | required | PostgreSQL URL of the passbox_app role |
PASSBOX_MIGRATION_DATABASE_URL | same as PASSBOX_DATABASE_URL | URL of the passbox_migrator role for migrations |
PASSBOX_WORKER_DATABASE_URL | same as PASSBOX_DATABASE_URL | URL of the passbox_worker role for background jobs |
PASSBOX_DATABASE_MAX_CONNECTIONS | 10 | Connections per pool |
PASSBOX_AUTO_MIGRATE | true | Run migrations at start. false if you run passbox-server migrate yourself before rolling out |
PASSBOX_PUBLIC_URL | empty | Address where your users open Passbox. Needed for links in emails and for single sign-on |
PASSBOX_WEB_DIR | empty | Folder with the web app. The Docker image sets it |
PASSBOX_TRUST_PROXY | false | Read the client IP from X-Forwarded-For. Turn on only behind a reverse proxy that sets the header |
PASSBOX_AUTH_RATE_LIMIT | 60 | Sign-in and registration requests per IP and minute |
PASSBOX_METRICS_BIND | empty | Address for Prometheus metrics, such as 127.0.0.1:9090. Internal network only |
PASSBOX_LOG_FORMAT | pretty | pretty or json |
RUST_LOG | info | Log level, such as debug |
Email and administration
| Variable | Default | Meaning |
|---|---|---|
PASSBOX_SMTP_URL | empty | SMTP server for outgoing email. Without it, emails only go to the log |
PASSBOX_CAMELMAILER_API_KEY | empty | Instead of SMTP: send through the API of a Camelmailer server |
PASSBOX_CAMELMAILER_URL | https://app.camelmailer.com | Address of your own Camelmailer installation |
PASSBOX_MAIL_FROM | empty | Sender, such as Passbox <passbox@example.com>. Required once email is set up |
PASSBOX_ADMIN_EMAILS | empty | Comma-separated email addresses whose accounts may always manage the server |
Features and limits
| Variable | Default | Meaning |
|---|---|---|
PASSBOX_ICONS | on | Load website icons through the server. off turns this off |
PASSBOX_BREACH_PROXY | on | Route the password leak check through the server |
PASSBOX_BREACH_CATALOG | on | Load the public list of data breaches. off for servers without internet |
PASSBOX_BREACH_CATALOG_HOURS | 6 | Hours between two downloads of that list |
PASSBOX_HIBP_API_KEY | empty | Have I Been Pwned API key. Turns on breach monitoring for email addresses |
PASSBOX_HIBP_CHECK_HOURS | 24 | Hours between two checks of each monitored address |
PASSBOX_HIBP_RPM | 10 | Requests per minute your Have I Been Pwned subscription allows |
PASSBOX_BLOB_DIR | blobs, in the image /data/blobs | Folder for encrypted file attachments. Back it up with the database |
PASSBOX_ATTACHMENT_MAX_MB | 100 | Largest file in MiB |
PASSBOX_ATTACHMENT_QUOTA_MB | 0 | Attachment storage per account in MiB, 0 means unlimited |
PASSBOX_ORG_ATTACHMENT_QUOTA_MB | 0 | Attachment storage per organization in MiB, 0 means unlimited |
PASSBOX_FAMILY_MEMBER_LIMIT | 0 | Most people per family, guests excluded, 0 means unlimited |
PASSBOX_AGENT_LIMIT_PER_MEMBER | 0 | Active service accounts per member, 0 means unlimited. Can be overridden in the administration |
PASSBOX_WEBHOOK_ALLOW_PRIVATE | false | Allow organizations' webhooks to private addresses and over http, for example for a SIEM in your own network |
PASSBOX_SSO_ALLOW_HTTP_LOOPBACK | empty | 1 allows identity providers over http on localhost. For testing only |
An invalid SMTP URL or sender stops the server at startup, so typos show up right away.
Passbox sends invitations and security notices: sign-in from a new device, changed master password, changes to two-factor sign-in, recoveries, emergency access and breach alerts. Emails go out in English or German, in the language the person chose in Passbox.
You give the SMTP server as a URL:
| Example | Connection |
|---|---|
smtps://user:password@mail.example.com:465 | TLS from the start |
smtp://user:password@mail.example.com:587?tls=required | STARTTLS, required |
smtp://user:password@mail.example.com:587?tls=opportunistic | STARTTLS if offered (not recommended) |
smtp://localhost:25 | No encryption, only for a relay on the same host |
Percent-encode special characters in the user name and password, such as @ as %40:
PASSBOX_SMTP_URL='smtps://passbox%40example.com:app-password@smtp.example.com:465'
PASSBOX_MAIL_FROM='Passbox <passbox@example.com>'
PASSBOX_PUBLIC_URL='https://passbox.example.com'Emails go through a queue in the database. Requests never wait for the mail server, and emails survive restarts. Passbox retries temporary failures for about four hours. In the administration you see waiting and failed emails and send a sample with Send test email.
Instead of SMTP, you can send through the API of a Camelmailer server version 0.12 or later with PASSBOX_CAMELMAILER_API_KEY.
Single sign-on
For single sign-on and SCIM, set PASSBOX_PUBLIC_URL to the address where your users open Passbox. The identity provider sends users back to {PASSBOX_PUBLIC_URL}/api/v1/sso/callback. SCIM is served at {PASSBOX_PUBLIC_URL}/api/v1/scim/v2. The server must reach the provider over https.
Setting it up in Passbox and the guides for Entra ID, Google, Okta, Keycloak, authentik and ZITADEL are in Single sign-on and SCIM.
Website icons
The icons of about 3,500 well-known websites come with the apps. For all others, the apps ask your server, never the website itself. The server fetches the icon once, stores it for everyone and checks it again after 30 days.
- Storage: about 10 KB per website that is not built into the apps. 10,000 different websites take about 100 MB.
- Privacy: Your server learns the domains that are not built into the apps. The icon store keeps no account or session, and the log shows no domains. Websites see only the server's IP address, once per website.
- Connections: only port 443 of public addresses, at most three redirects, a three-second timeout, at most 200 KB.
PASSBOX_ICONS=off turns this off. The apps then show initials.
Leak check and Have I Been Pwned
- Leaked passwords (
PASSBOX_BREACH_PROXY, on): The apps send the first five characters of a hash to your server. It asks Have I Been Pwned and passes the answer on. Have I Been Pwned sees only your server's IP address. No key needed. - Breached websites (
PASSBOX_BREACH_CATALOG, on): The server downloads the public list of data breaches every six hours. The apps compare it on the device. Without internet, setoffand the apps use the list that ships with them. - Email breach monitoring (
PASSBOX_HIBP_API_KEY): needs a Have I Been Pwned subscription and working email. Users confirm their addresses with a code, the server checks them regularly and writes when new breaches appear.
File attachments
Attachments are stored encrypted in the folder PASSBOX_BLOB_DIR, in Docker in the volume passbox-blobs. Back up this folder together with the database. There is no built-in S3 storage. If you need object storage, mount it as a file system.
Requests from other origins
The API answers requests from any origin (CORS). The desktop app needs this. It is safe because Passbox checks every request with a token in a header and uses no cookies. If your reverse proxy adds its own CORS headers, remove them.