Self-hosting

Run the enveil server yourself

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:

bash
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 root

The 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.

bash
docker run -d -p 8080:8080 --env-file .env enveil

Configuration

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.

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:

  1. The database, with your usual PostgreSQL tooling (pg_dump, volume snapshots, managed backups). Secret values in it are ciphertext.
  2. 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.

1

Stop the app

A running server holds the old key and fails to unwrap anything once the rotation commits.

2

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:

bash
NEW_ENCRYPTION_KEY=<the new key> enveil-server rotate-master-key

In 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.

3

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_URL to the public https:// URL,
  • leave SECURE_COOKIES at true,
  • set TRUST_PROXY_HEADERS=true, and make sure the proxy overwrites X-Forwarded-For rather 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.

bash
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:8080

Point 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:

bash
cargo run -p enveil --features server -- seed-demo

That command exists only in debug builds, so a deployment has no way to mint a credential from the command line.