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_AUTH_ORIGIN=https://provon.example.com
PROVON_WORKBENCH_ORIGINS=https://provon.example.com
PROVON_AUTH_TRUST_HOST=true

For split Cloudflare origins:

PROVON_AUTH_ORIGIN=https://api.provon.example
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. Forwarded origins that do not exactly match PROVON_AUTH_ORIGIN are ignored.

Node Storage#

Metadata, metering, and telemetry must use distinct database URLs.

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

Model Services#

The Node runtime can optionally control standalone Python services for local inference and fine-tuning. These services run outside the Node process and communicate over HTTP.

When the inference URL is unset, the runtime still operates but cannot serve self/ targets. When the fine-tuning URL is unset, fine-tuning API routes return 503.

The Python services themselves accept:

• PROVON_HOST / PROVON_PORT for binding;
• PROVON_API_KEY for authentication;
• PROVON_MODELS_DIR for the inference model cache;
• PROVON_LLAMA_CPP_PATH for GGUF export in the fine-tuning service.

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:

Gateway reservation cleanup exposes additional controls:

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

Google and GitHub identities require verified provider email claims. To link another identity, sign in first and use Account settings → Sign-in methods. Anonymous email-based account linking is not supported.

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

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.

Model Runtime#

The model runtime stores local model weights under PROVON_MODELS_DIR and keeps its process state in a fixed file at <data-dir>/data/model-runtime.json. The data directory is resolved from the parent of PROVON_BLOBS_DIR, or from XDG_DATA_HOME when no blob directory is configured.

Node controls standalone Python inference and fine-tuning services over HTTP:

• PROVON_PYTHON_INFERENCE_URL
• PROVON_PYTHON_INFERENCE_API_KEY
• PROVON_PYTHON_FINE_TUNING_URL
• PROVON_PYTHON_FINE_TUNING_API_KEY
• PROVON_MODEL_FINE_TUNING_WORK_DIR
• PROVON_TRANSFORMERS_DEVICE
• PROVON_TRANSFORMERS_DTYPE
• PROVON_TRANSFORMERS_TRUST_REMOTE_CODE=1

Node stages immutable training data under PROVON_MODEL_FINE_TUNING_WORK_DIR. The fine-tuning service writes its checkpoint under the same job directory, then Node atomically imports the standalone model into PROVON_MODELS_DIR. When the services run in separate containers, mount the training work directory at the same absolute path in both containers. 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.