Self-hosting Configuration

Critical Secret#

AUTH_SECRET is required in production. PROVON_AUTH_SECRET is an equivalent fallback, but use one name consistently.

This value:

• signs authentication state and sessions;
• derives application-level encryption for stored OAuth tokens, provider credentials, and Connector secrets;
• must be identical across runtime surfaces that read the same metadata store.

Generate at least 32 random bytes:

openssl rand -base64 32

Store and back it up as encryption key material. Replacing it invalidates sessions and can make existing encrypted credentials unreadable. Do not rotate it without an explicit credential re-encryption and user reauthorization plan.

Public Origin And HTTP#

For a same-origin Node deployment:

PROVON_WORKBENCH_ORIGINS=https://provon.example.com
PROVON_AUTH_TRUST_HOST=true

For split Cloudflare origins:

PROVON_WORKBENCH_ORIGINS=https://app.provon.example
PROVON_AUTH_COOKIE_DOMAIN=.provon.example
PROVON_AUTH_TRUST_HOST=true

Only trust forwarded hosts when the ingress removes client-supplied forwarding headers and writes its own values. Never enable PROVON_AUTH_SKIP_CSRF_CHECK in production.

Node Storage#

The directory containing PROVON_LOCAL_BLOB_DIR also holds persistent Node runtime state. Mount or back up the parent data directory, not only the visible blob files.

MotherDuck#

Use:

PROVON_TELEMETRY_DB_URL=motherduck:provon-telemetry
PROVON_TELEMETRY_TENANT_ISOLATION=shared
MOTHERDUCK_TOKEN=...

for one shared MotherDuck database. Use the default organization isolation with MOTHERDUCK_ADMIN_TOKEN when each organization should receive isolated MotherDuck resources.

Cloudflare Telemetry#

The Cloudflare runtime requires:

The default read model is:

PROVON_TELEMETRY_QUERY_SOURCE = "summaries"
PROVON_TELEMETRY_PAYLOAD_RETENTION = "all"

summaries requires the TELEMETRY_SUMMARY_QUEUE binding on telemetry writer runtimes. projected-only drops raw payload fields at the Cloudflare telemetry write boundary. Choose it only when projected evidence is sufficient for investigation and diagnosis.

Use the checked-in wrangler.*.example.toml files as the binding contract. Do not rename a binding without changing the corresponding runtime code.

OTLP And Background Work#

Defaults are suitable for development and moderate workloads. Tune only from measured body sizes, queue lag, write latency, and dependency limits.

Node also exposes:

Setting an interval to 0 disables the corresponding loop only where the implementation accepts a non-negative interval. Disabling a loop is an architecture change: assign its responsibility to another runtime before doing so.

Data Retention#

Project retention policy selects what should expire. Runtime variables control the maintenance job:

Cloudflare scheduled retention runs through the Jobs Worker and telemetry warehouse. R2 lifecycle, snapshot expiration, and compaction are separate platform maintenance controls.

Sign-in Providers#

Email and password remain available when no social provider is configured. A social provider is enabled only when both its client ID and client secret are present.

Register:

https://<api-origin>/api/auth/callback/github
https://<api-origin>/api/auth/callback/google
https://<api-origin>/api/auth/callback/apple

Account linking is disabled by default. Enable it only after confirming the provider guarantees ownership of the returned email address.

Enterprise OIDC#

Required:

• AUTH_OIDC_CLIENT_ID
• AUTH_OIDC_CLIENT_SECRET
• AUTH_OIDC_ISSUER or AUTH_OIDC_WELL_KNOWN

Optional controls include AUTH_OIDC_NAME, AUTH_OIDC_SCOPE, AUTH_OIDC_TOKEN_ENDPOINT_AUTH_METHOD, AUTH_OIDC_ALLOW_ACCOUNT_LINKING, and AUTH_OIDC_EMAIL_TRUST_POLICY.

The default email trust policy requires email_verified=true. Use trusted_provider only when the IdP contract guarantees email ownership. The callback provider ID is enterprise-oidc:

https://<api-origin>/api/auth/callback/enterprise-oidc

Enterprise SAML#

The configuration surface accepts:

• AUTH_SAML_IDP_METADATA or AUTH_SAML_IDP_METADATA_URL;
• AUTH_SAML_ACS_URL, normally https://<api-origin>/api/auth/saml/acs;
• optionally AUTH_SAML_ENTITY_ID;
• signing key and certificate variables when AuthnRequests must be signed.

Assertion signatures are required by default. The checked-in Node and Cloudflare entrypoints do not currently wire a production samlify schema validator, so SAML authentication fails closed in production. Use enterprise OIDC for production SSO until a real validator is supplied by the deployable runtime. AUTH_SAML_SKIP_SCHEMA_VALIDATION=true is a local-development bypass and must not be used in production.

Connector OAuth#

Login OAuth and Connector OAuth are separate applications. Connector credentials use the *_INTEGRATION_* prefix.

Register:

https://<api-origin>/v1/integrations/github/callback
https://<api-origin>/v1/integrations/slack/callback
https://<api-origin>/v1/integrations/notion/callback
https://<api-origin>/v1/integrations/jira/callback
https://<api-origin>/v1/integrations/linear/callback

See Connectors for project setup and default scopes.

Local Model Runtime#

Node stores local model state under PROVON_SELF_HOSTED_DIR. Advanced engine overrides include:

• PROVON_LLAMA_SERVER_PATH
• PROVON_STABLE_DIFFUSION_CPP_SERVER_PATH
• PROVON_DIFFUSERS_SERVER_PATH
• PROVON_DIFFUSERS_PYTHON_PATH
• PROVON_SENTENCE_TRANSFORMERS_SERVER_PATH
• PROVON_SENTENCE_TRANSFORMERS_PYTHON_PATH
• PROVON_SGLANG_PYTHON_PATH
• PROVON_SGLANG_DIFFUSION_SERVER_PATH
• PROVON_SGLANG_DIFFUSION_PYTHON_PATH

Use overrides only when the runtime cannot manage the default engine path. See Model providers.

Configuration Review#

Before production:

• compare staging and production variable names without comparing secret values;
• confirm every runtime reading one metadata store has the same AUTH_SECRET;
• verify exact Workbench origins and public callback URLs;
• verify storage paths or bindings point to durable production resources;
• keep body, queue, and retention limits consistent across producer and consumer surfaces;
• restart or redeploy all affected surfaces after a shared secret or binding change;
• record the configuration version with the application release.