Configuration

The controller is configured with environment variables; most runtime settings (OIDC, SCIM, notifications, branding, policy) are managed in the web console and stored in Postgres.

Environment variables

Variable	Required	Default	Description
TESSERA_DATABASE_URL	yes (prod)	postgres://tessera:tessera@localhost:5432/tessera?sslmode=disable	Postgres connection string. A dev default is used if unset; effectively required in production.
TESSERA_ENC_KEY	yes (prod)	ephemeral	32-byte hex key for AES-GCM credential encryption.
TESSERA_JWT_SECRET	yes (prod)	ephemeral	32-byte hex secret for signing session JWTs.
TESSERA_PUBLIC_URL	recommended	https://localhost:8443	External URL of the controller — used for OIDC redirects and notification links.
TESSERA_HTTP_ADDR	no	:8443	Address the controller listens on.
TESSERA_TLS_CERT	no	—	Path to TLS certificate file. If the cert/key are unset, the controller generates an in-memory self-signed cert in any mode — terminate real TLS at a reverse proxy.
TESSERA_TLS_KEY	no	—	Path to TLS private key file.
TESSERA_HOST_KEY	no	./dev-data/ssh_host_ed25519_key	Path to the SSH host key used by the SSH proxy. Generated if absent in dev mode.
TESSERA_DEV	no	true locally	Dev mode: ephemeral keys, relaxed checks. Only affects locally built binaries — released/customer builds force it off, so the variable has no effect there.
TESSERA_METRICS_TOKEN	no	—	Bearer token to protect the Prometheus /metrics endpoint. Unset = unauthenticated.
TESSERA_LICENSE	no	—	Per-org license token from your portal. Also accepts @/path/to/file. Changing it and restarting installs the new licence; ignored while the controller is linked to the portal, which renews itself.
TESSERA_LICENSE_PUBKEY	no	— (empty)	Per-org Ed25519 public key pasted from the portal, used on the legacy/dev self-verify path. Release builds verify the license against a build-time-baked master key, so this is not used there.
TESSERA_PASSWORD_LOGIN	no	false	Break-glass: force-enable password login even when SSO-only is configured. Unset after recovery.
TESSERA_RECORDINGS_DIR	no	./dev-data/recordings	Directory for session .cast recordings.
TESSERA_AUDIT_RETENTION_DAYS	no	0 (keep forever)	Delete audit-log entries older than N days. A daily background job purges them; 0 disables purging.
TESSERA_RECORDING_RETENTION_DAYS	no	0 (keep forever)	Delete session replays (.cast files + their metadata) older than N days. 0 disables purging.
TESSERA_SESSION_TTL	no	60	One-time session token TTL in seconds.
TESSERA_OIDC_PROVIDERS	no	—	JSON array of OIDC provider configs (alternative to web console). See OIDC guide.

Generate secrets with openssl rand -hex 32.

Caution

In production, always set TESSERA_ENC_KEY and TESSERA_JWT_SECRET to stable values and back them up. With ephemeral keys, stored credentials can’t be decrypted after a restart.

Caution

TESSERA_JWT_SECRET must be cryptographically random (32 bytes from openssl rand). A weak or guessable secret allows forging admin tokens.

Console-managed settings

Configured under Settings (admin only) and persisted in the database:

• Authentication — OIDC providers, SCIM.
• Integrations — Telegram notifications, audit export, database query audit.
• Policy — read-only command lists, Kubernetes & database policies.
• Import — bulk import / export of infrastructure.
• License — install or refresh your edition license.
• Appearance — branding (name, subtitle, logo).

Endpoints

• / — web console (embedded SPA).
• /api/* — REST API (Bearer JWT).
• /connect — WSS tunnel (one-time session token).
• /oidc/* — OIDC login flow.
• /scim/v2/* — SCIM provisioning (Bearer token).
• /metrics — Prometheus metrics (optionally tokened).
• /healthz — health check.