Environment¶
The server is configured through .env. Only one variable is strictly required.
Required¶
| Variable | Purpose |
|---|---|
JWT_SECRET |
Signs session tokens. Generate with openssl rand -hex 32. |
The bundled compose.yml provides a Postgres database and sensible defaults for everything else. You can override the variables below in .env; compose.yml forwards each one to the server, except HANDLES_FROM_EMAIL (see its row).
Self-hosted mode is automatic¶
The server runs in self-hosted mode whenever LEMONSQUEEZY_API_KEY is unset (which is the default). In that mode:
- Every paid feature is unlocked for every user — teams, team vaults, terminal sharing, audit logs.
- No 14-day trial countdown on new accounts.
- The
/v1/billing/*checkout, portal, seats, cancel and resume endpoints return503;GET /v1/billing/subscriptionstill reports the account's tier. - The Lemon Squeezy webhook is disabled.
GET /v1/metareports{"self_hosted": true, "billing_enabled": false}so the admin dashboard (if you run it) can hide its billing widgets.
There is no SELF_HOSTED flag to set. The absence of Lemon Squeezy configuration is the signal.
Optional¶
| Variable | Default | Purpose |
|---|---|---|
DATABASE_URL |
bundled Postgres | Postgres connection string. |
POSTGRES_IMAGE_TAG |
16-alpine |
Tag of the bundled postgres image. Changing the major version does not upgrade an existing data volume — Postgres refuses to start on it. |
HOST_PORT |
14372 |
Host port to expose. |
POSTGRES_USER / POSTGRES_PASSWORD / POSTGRES_DB |
voltius / voltius / voltius |
Credentials and database name of the bundled Postgres; DATABASE_URL is built from them. |
RUST_LOG |
info |
Server log level. |
ALLOW_MULTIPLE_INSTANCES |
false |
The server takes a Postgres advisory lock and refuses to start if another instance holds it; true skips the check. The bundled compose.yml does not forward it. |
CORS_ORIGINS |
allow all | Comma-separated allow-list. Set to your domain in public deployments. |
TRUSTED_PROXIES |
unset | Comma-separated IPs or CIDRs of your reverse proxy. Required for rate limiting to see real client IPs behind a proxy — a container proxy needs its network's subnet, e.g. 172.22.0.0/16, not a single address. The older single-address name TRUSTED_PROXY_IP is read only when TRUSTED_PROXIES is absent from the environment, which the bundled compose.yml never allows, so use TRUSTED_PROXIES. |
SYNC_BLOB_RETENTION_DAYS |
90 |
Days since a sync blob was last written before it is deleted, once a newer blob from the same account exists. The latest blob is never deleted. |
TEAM_OBJECTS_MIN_CLIENT_VERSION |
unset | Minimum desktop version allowed to write team vault objects, e.g. 0.33.0. Older clients get 426 Upgrade Required on writes; reads are never gated. Set it only once your users have updated. |
ADMIN_SECRET |
unset | Required only if you run the optional admin dashboard. Must match the same value in the dashboard's .env. |
Email¶
The server sends account verification emails, team invitations and security notices (a changed master password) through Resend or any SMTP server. Without either, those emails are not sent; accounts still work.
| Variable | Default | Purpose |
|---|---|---|
EMAIL_PROVIDER |
inferred | resend, smtp or disabled. Left unset, it is resend when RESEND_API_KEY is set, smtp when SMTP_HOST is set, and disabled otherwise. With both set and no EMAIL_PROVIDER, the server refuses to start. |
VOLTIUS_APP_URL |
https://app.voltius.app |
Base URL of the web portal that opens the links in verification and invitation emails (/verify-email and /invite/<token>). The server does not serve those pages: run the web portal image next to it and point this at it, or the links lead to the hosted service, which cannot verify accounts on your server. |
VOLTIUS_MARKETING_URL |
https://voltius.app |
Website link in the email footer. |
RESEND_LOGO_URL |
https://voltius.app/logo.png |
Logo shown in email headers, whichever provider sends them. |
Resend¶
| Variable | Default | Purpose |
|---|---|---|
RESEND_API_KEY |
unset | API key of your Resend account. |
RESEND_FROM |
Voltius <noreply@voltius.app> |
Sender address. Set this if you use Resend: Resend only sends from a domain you have verified, so the default fails for every self-host and no email arrives. |
RESEND_WEBHOOK_SECRET |
unset | Signing secret (whsec_…) of a Resend webhook pointed at https://<your-host>/v1/webhooks/resend with the email.bounced and email.suppressed events. With it, an address that bounces is flagged and the app asks the user to fix it, instead of resending into Resend's suppression list. |
SMTP¶
Use your own mail server or relay: Postfix, Mailcow, Microsoft Exchange, or a provider's SMTP endpoint.
| Variable | Default | Purpose |
|---|---|---|
SMTP_HOST |
unset | Host name of the SMTP server. |
SMTP_SECURITY |
starttls |
starttls upgrades the connection before sending anything and fails if the server does not offer it. tls connects over TLS from the start. none sends in clear and is meant for a relay on the same host or private network; it refuses SMTP_USERNAME/SMTP_PASSWORD so a password never crosses the network in clear. |
SMTP_PORT |
from SMTP_SECURITY |
587 for starttls, 465 for tls, 25 for none. |
SMTP_USERNAME, SMTP_PASSWORD |
unset | Credentials for SMTP authentication. Set both, or neither for a relay that accepts this host without logging in. The password is never written to the logs. |
SMTP_FROM |
required | Sender, as Voltius <voltius@example.com> or a bare address. Most servers only accept a sender the account owns. |
SMTP_TIMEOUT_SECS |
30 |
Seconds the whole submission may take, from connecting to the server accepting the message. A server that stops answering fails the send after this long. |
EMAIL_PROVIDER=smtp
SMTP_HOST=mail.example.com
SMTP_SECURITY=starttls
SMTP_USERNAME=voltius@example.com
SMTP_PASSWORD=change-me
SMTP_FROM=Voltius <voltius@example.com>
VOLTIUS_APP_URL=https://voltius.example.com
An invalid combination (an unknown SMTP_SECURITY, a username without a password, a SMTP_FROM that is not an address) stops the server at startup with a message naming the variable. A valid one is logged at startup, without the password, as Email delivery transport=smtp mail.example.com:587 (StartTls, authenticated), from Voltius <voltius@example.com>.
When the SMTP server refuses a message (wrong credentials, a sender it rejects, a timeout), the error reaches the request that sent it: resending a verification email answers 502, and a team invitation reports email_sent: false.
SMTP has no equivalent of the Resend bounce webhook. The server knows the SMTP server accepted the message, not that it reached the inbox: a message that bounces later goes back to SMTP_FROM, and the app does not hear about it.
Testing delivery¶
Send a test message with the same configuration the server uses, without creating an account:
It prints Accepted for delivery to you@example.com by: smtp mail.example.com:587 … when your provider accepted the message, or the provider's error and exit code 1 when it did not. Check the inbox and the spam folder: acceptance is not delivery.
Access¶
REGISTRATION_ENABLED and TEAM_INVITES_ENABLED default to true; turn them off to run a closed instance that is still reachable from the Internet. HANDLES_FROM_EMAIL defaults to false.
| Variable | Default | Purpose |
|---|---|---|
REGISTRATION_ENABLED |
true |
false refuses new accounts with 403 {"error": "REGISTRATION_DISABLED"}. Existing accounts keep logging in and syncing. To add someone, invite them by email: the invitation lets that one address create an account. |
TEAM_INVITES_ENABLED |
true |
false refuses new team invitations, direct adds and join links with 403 {"error": "TEAM_INVITES_DISABLED"}. Invitations and links already issued stay usable until they expire or are revoked; listing, accepting, declining and revoking keep working. |
HANDLES_FROM_EMAIL |
false |
true gives every new account the handle from its email address: jnovak@corp.cz becomes @jnovak, and dots become dashes (jan.novak@ becomes @jan-novak). If that handle is taken, reserved or was used before, the account gets a generated handle, which you can fix from the admin dashboard. Users can no longer change their own handle (403 {"error": "HANDLE_MANAGED"}). Existing accounts keep their handles until they verify an email or you run Handles → Apply in the dashboard. The bundled compose.yml does not forward this variable yet: add HANDLES_FROM_EMAIL: ${HANDLES_FROM_EMAIL:-} under server.environment before setting it in .env. |
With HANDLES_FROM_EMAIL=true, handles come only from verified addresses: if the server sends verification emails, a new account keeps a generated handle until its owner clicks the verification link, then switches to the email-derived one if it's still free; without email delivery the handle is derived at sign-up. Any account still on a generated handle — new or existing — switches to its email-derived handle when it verifies an email, unless the derived handle is taken. Handles → Apply renames the remaining verified accounts oldest-created first and lists unverified ones as "email not verified — renamed once verified"; on servers without email delivery, an account that changes email becomes unverified with no way to verify it again, so set its handle by hand. The switch assumes a single-organization instance — only the part before the @ is used, so jnovak@gmail.com and jnovak@corp.cz would both want @jnovak, with the first verified account claiming it at sign-up or verification and the oldest at Apply. Keep registration closed or invite only your own people, and note that derived handles count as chosen handles, so every account on the server can find them by partial search.
Any other value than true/false (or 1/0, yes/no, on/off) stops the server at startup rather than guessing. GET /v1/meta reports all three as registration_enabled, team_invites_enabled and handles_from_email.
Two-factor authentication¶
| Variable | Default | Purpose |
|---|---|---|
TOTP_ENC_KEY |
unset | Lets accounts turn on two-factor authentication. 32 random bytes, base64: generate with openssl rand -base64 32. It encrypts each account's authenticator secret in the database. Unset, the server does not offer two-factor and the app hides the option. A value that is not 32 bytes of base64 stops the server at startup. |
Back this key up and never change it
Without the key the server can no longer check anyone's codes. Accounts that turned two-factor on are then refused at the code step, not let through: each one needs a recovery code, or an administrator to clear its two-factor from the admin dashboard. Store the key with JWT_SECRET, outside the database backups.
GET /v1/meta reports it as two_factor. The bundled compose.yml forwards the variable; if your compose file is older than the feature, add TOTP_ENC_KEY: ${TOTP_ENC_KEY:-} under server.environment.
| Variable | Default | Purpose |
|---|---|---|
WEBAUTHN_RP_ID |
unset | Lets accounts use a passkey as a second factor. Set it to the domain the web portal is served on, or a parent of it: with VOLTIUS_APP_URL=https://app.example.com, either app.example.com or example.com. Unset, the server offers no passkeys and the app hides the option. A value that does not cover VOLTIUS_APP_URL stops the server at startup. |
Passkeys are created and used in the browser, on the web portal, so three things must hold:
- The portal is deployed and reachable over HTTPS at
VOLTIUS_APP_URL. A portal onhttp://localhostworks for testing only. - The portal's origin is in
CORS_ORIGINS. - The portal is the version that has the
/2fa/passkeypage.
Choose WEBAUTHN_RP_ID once
Every passkey is bound to this value. Changing it later makes all registered passkeys unusable: their owners fall back to an authenticator code or a recovery code, and have to add their passkeys again. It is a domain name, not a secret, and needs no backup beyond your configuration. A parent domain such as example.com survives moving the portal to another subdomain.
GET /v1/meta reports it as passkeys. It works without TOTP_ENC_KEY: accounts can then use passkeys and recovery codes, but no authenticator app. If your compose file is older than the feature, add WEBAUTHN_RP_ID: ${WEBAUTHN_RP_ID:-} under server.environment.
Two more things to know before the first user enrols:
- Rolling the server back to a version from before two-factor makes it ignore the second factor: enrolled accounts sign in with the password alone until you roll forward again.
- Users need Voltius 0.54.0 or later for codes and 0.55.0 or later for passkeys. An older app cannot show the step: on an account that only has passkeys, 0.54.0 accepts a recovery code and nothing else.
Rate limits¶
The defaults are fine for most deployments. Limits keyed per IP depend on TRUSTED_PROXIES being right behind a proxy.
| Variable | Default | Purpose |
|---|---|---|
AUTH_RATE_LIMIT |
10 |
Login and challenge requests per minute per IP. Token refresh has its own budget of three times this value, so a device whose session was ended cannot use up the sign-in budget by retrying. |
REGISTER_RATE_LIMIT |
20 |
New registrations per day per IP. |
WAITLIST_RATE_LIMIT |
10 |
Waitlist submissions per hour per IP. |
SYNC_RATE_LIMIT |
10000 |
Authenticated API requests per hour per user (sync, teams, presence, sessions). |
INVITE_RATE_LIMIT |
20 |
Team invitations per hour per user. |
USER_SEARCH_RATE_LIMIT |
60 |
User directory searches per minute per user. |
STRANGER_KNOCK_RATE_LIMIT |
20 |
Terminal-sharing invites to people outside your teams, per hour per sender. |
Limits with an hourly or daily window (registrations, waitlist, invitations, stranger knocks, and the fixed limits on short codes, join grants, enrolment and verification emails) are counted in the database, so restarting the server does not reset them. To clear them, for example on a test server, run DELETE FROM rate_limit_hits; against the database. The per-minute limits and SYNC_RATE_LIMIT are kept in memory and reset on restart.
Shutdown¶
| Variable | Default | Purpose |
|---|---|---|
SHUTDOWN_GRACE_SECS |
8 |
On stop, how long the server waits for open requests, sync streams and shared terminals to close before exiting. Keep it below your container's stop timeout (Docker's default is 10 seconds). Shared terminal sessions end on every restart; participants are told the server is restarting. |
Production database & backups
The bundled Postgres is convenient but has no backup story — if its volume is lost, so is your data. For a durable setup, point DATABASE_URL at a Postgres you run yourself. server/compose.db.yml is the stack Voltius' own production database runs on: pinned Postgres, WAL-G continuous archiving and base backups to S3-compatible storage, pg_dump rotation mirrored off-box, a freshness watchdog, and an optional Supabase Studio profile for browsing tables. Configure it from .env.db.example; the restore runbook covers point-in-time recovery.
Migrations¶
Run automatically on every server start. No manual step.
Full reference¶
The complete annotated file lives at server/.env.example.