The server is one binary that serves the dashboard, the token API, the MCP endpoint and these docs. It needs a PostgreSQL database, an SMTP server and one encryption key. There is no other state.
Requirements
- PostgreSQL. The local setup uses PostgreSQL 18. Schema migrations are embedded in the binary.
- SMTP. Sign-in sends a one-time code by email, and owners and admins are emailed when an identity trips its read budget.
- HTTPS in front of it, in production. See Reverse proxy and TLS.
- To build from source: the Rust toolchain pinned in
rust-toolchain.toml, Dioxus CLI 0.7.10 (cargo install dioxus-cli --version 0.7.10 --locked) and Bun for the stylesheet.
Build the image
app/Dockerfile does not compile anything. It packages a web bundle you built beforehand, so the image build takes seconds and cargo caching stays on the build machine:
cd app
bun install --frozen-lockfile
bun run styles # Tailwind CSS
dx bundle --web --release # writes target/dx/enveil-server/release/web/
cd ..
docker build -f app/Dockerfile -t enveil . # build context is the workspace rootThe image is debian:trixie-slim with that bundle copied to /app, run as an unprivileged user. It starts ./server, listening on 0.0.0.0:8080 (IP and PORT). Migrations and docs are compiled into the binary, so nothing else needs mounting. .github/workflows/deploy.yml in the repository does exactly this in CI and pushes the result to a registry.
Build on a machine whose glibc is not newer than Debian trixie's. The binary links against the build host's glibc; a bookworm base image fails on one built on a current Ubuntu.
docker run -d -p 8080:8080 --env-file .env enveilConfiguration
All configuration is environment variables. A .env file in the working directory is read too. The server refuses to start on a missing required variable or a value it cannot parse, rather than guessing.
Required
| Variable | Meaning |
|---|---|
DATABASE_URL |
PostgreSQL connection string, e.g. postgres://enveil:…@db:5432/enveil. |
BASE_URL |
The public URL, e.g. https://enveil.oxidt.com. It is the CSRF origin, the passkey Relying Party ID and the OAuth issuer advertised to MCP clients, so in production it must be the real public HTTPS URL. Changing its host invalidates every enrolled passkey. |
SESSION_SECRET |
Hex, at least 64 bytes. Signs session cookies. openssl rand -hex 64. |
ENCRYPTION_KEY |
The master key, 32 bytes base64. openssl rand -base64 32. See below. |
SMTP_HOST, SMTP_PORT, SMTP_FROM |
Mail server and sender address. |
ENCRYPTION_KEY wraps every project's data key. Losing it makes every stored secret unrecoverable. Back it up somewhere that is not the database: a backup that holds both is a backup that hands over every secret. The server will not start without it, rather than silently storing plaintext.
Optional
| Variable | Default | Meaning |
|---|---|---|
SMTP_USER, SMTP_PASSWORD |
empty | SMTP credentials. |
SMTP_SECURITY |
tls, or none when SMTP_HOST is localhost, 127.0.0.1, ::1 or mailpit |
tls (implicit TLS, port 465), starttls (port 587) or none. |
SECURE_COOKIES |
true |
Marks cookies Secure and sends HSTS. Set false only for plain-HTTP local development. |
TRUST_PROXY_HEADERS |
false |
Read the client address from X-Forwarded-For, X-Real-IP or Forwarded. Set true behind a reverse proxy, and only then: otherwise a client could pick its own address. Rate limits key on that address, and the audit trail only records a source IP when this is on. |
AUTH_MODE |
local |
local: email code plus passkeys stored in this database, nothing else to run. ferriskey: FerrisKey OIDC, for apps sharing one login. |
FERRISKEY_URL, FERRISKEY_REALM, FERRISKEY_CLIENT_ID, FERRISKEY_CLIENT_SECRET |
none | Required when AUTH_MODE=ferriskey, ignored otherwise. |
FERRISKEY_ISSUER_URL |
FERRISKEY_URL without a trailing /api |
Public OIDC issuer, if it differs. |
OPEN_REGISTRATION |
false |
true lets any address create an account. |
ALLOWED_REGISTRATION_EMAILS, ALLOWED_REGISTRATION_DOMAINS |
empty | Comma-separated. With registration closed, only these may sign up; with both empty, only the very first account can, which is how you bootstrap a private instance. |
CAPTCHA_URL, CAPTCHA_SITE_KEY, CAPTCHA_SECRET_KEY |
none | Bollwark captcha in front of registration. All three or none. A public instance with open registration should set them. |
TOS_VERSION |
none | Terms version users must accept at sign-in. Unset skips the step; changing it re-prompts everyone. |
COMING_SOON |
false |
true shows a waitlist page at /. Sign-in, docs and the dashboard stay reachable. |
DEV_LOGIN |
off | A fixed local sign-in for development. Compiled out of release builds, so it cannot be turned on in production. |
RUST_LOG |
info,enveil=debug |
Log filter. |
IP, PORT |
0.0.0.0, 8080 in the image |
Listen address. |
SENTRY_DSN, ENVIRONMENT |
none | Error reporting. Only in a build with --features sentry. |
Booleans accept true/false, 1/0 or yes/no, in any case. Anything else stops the boot: a typo must not quietly turn secure cookies off.
Migrations
Migrations run on every start, before the server accepts requests, inside the binary. There is no separate step. Each one is applied once and recorded in the database, so restarting is safe. Roll back by restoring a database backup, not by starting an older binary against a newer schema.
Backups
Back up two things, and keep them apart:
- The database, with your usual PostgreSQL tooling (
pg_dump, volume snapshots, managed backups). Secret values in it are ciphertext. ENCRYPTION_KEY, in a password manager or a secret store of its own.
Neither is useful without the other. That is the point of keeping them in different places, and why losing the key loses everything.
Rotating the master key
Rotation re-wraps each project's data key under a new master key, one column per project, in one transaction. Secret values are never decrypted or re-encrypted. Use it when the key may have leaked.
Stop the app
A running server holds the old key and fails to unwrap anything once the rotation commits.
Rotate
Generate the new key and store it before using it; the command prints only the new key's id, never the key. Then run the binary with the usual configuration, the current key still in ENCRYPTION_KEY, and the new one in NEW_ENCRYPTION_KEY:
NEW_ENCRYPTION_KEY=<the new key> enveil-server rotate-master-keyIn the image the binary is ./server. It connects to the database (running pending migrations) like a normal start, so it needs the full configuration. Running it again after it succeeded changes nothing.
Swap the key and start
Set ENCRYPTION_KEY to the new key, back it up, and start the app.
Reverse proxy and TLS
The server speaks plain HTTP. Put a reverse proxy in front that terminates TLS, then:
- set
BASE_URLto the publichttps://URL, - leave
SECURE_COOKIESattrue, - set
TRUST_PROXY_HEADERS=true, and make sure the proxy overwritesX-Forwarded-Forrather than passing through what the client sent.
HTTPS is not optional if anyone uses enveil run --proxy: the CLI refuses a plain-HTTP server except on loopback. Proxy mode needs no extra port; its traffic goes through the same API, and responses stream back, including SSE. See Proxy mode.
Running it locally
For development, from a checkout. Needs Rust, Dioxus CLI 0.7.10, Bun, Docker and just.
cd app
docker compose --profile standalone up -d # PostgreSQL on :5496, Mailpit SMTP :1096, UI :8096
just bootstrap # .env from .env.example, with a fresh SESSION_SECRET
just encryption-key # put the result in .env as ENCRYPTION_KEY
cd ..
just assets
just serve # http://localhost:8080Point DATABASE_URL and SMTP_PORT in .env at the ports above (the example file assumes 5432 and 1025). Sign-in codes land in Mailpit.
For a project, secrets and an agent token to try the CLI against:
cargo run -p enveil --features server -- seed-demoThat command exists only in debug builds, so a deployment has no way to mint a credential from the command line.