Runtime config

Overlay Web loads runtime configuration in this precedence order:

Environment variables.
OVERLAY_CONFIG_FILE, normally overlay.config.json.
Defaults in src/shared/config/defaultOverlayRuntimeConfig.ts.

Use environment variables for secrets. Use JSON config for non-secret deployment shape: provider choices, storage buckets, feature gates, compliance metadata, CSP additions, and model defaults.

Create A Config

cp docs/config/enterprise-private.example.json overlay.config.json
OVERLAY_CONFIG_FILE=overlay.config.json npm run check:config
npm run docs:health

For Docker-based enterprise source startup:

cp .env.enterprise.example .env
cp docs/config/enterprise-private.example.json overlay.config.json
docker compose pull
docker compose up -d

This uses the prebuilt ghcr.io/layernorm/overlay-web image by default while keeping the source checkout available for audit and customization. Use docker/docker-compose.build.yml only after editing source code.

Top-Level Shape

Section	Purpose
`configVersion`	Use `2` for explicit enterprise runtime config. Older config shapes are normalized internally.
`preset`	Deployment preset: `saas-default`, `onprem-minimal`, `enterprise-private`, or `dpdp-strict`.
`app`	Public URL, deployment environment, CSP connect-src additions, and public env keys.
`compliance`	Compliance profile, minor mode metadata, external processor policy, allowed processors/regions, and retention defaults.
`features`	Boolean gates for product areas and external processor surfaces.
`providers`	Grouped provider selectors for auth, database, storage, models, tools, telemetry, secrets, and rate limits.
`auth`, `billing`, `storage`, `llm`, `database`, `capabilities`	Backward-compatible provider/config sections still consumed by current adapters.

Presets

Preset	Intended use
`saas-default`	Current hosted WorkOS, Stripe, R2, OpenRouter-style deployment.
`onprem-minimal`	Shell/config smoke tests with risky providers disabled.
`enterprise-private`	OIDC, S3-compatible storage, direct model provider, no billing, no telemetry by default.
`dpdp-strict`	Minor-mode metadata, external processors disabled by default, and explicit allowlists for approved processors.

Example profiles

Validated examples live under docs/config. npm run docs:health checks that each one parses.

Profile	File	Use case
SaaS staging	saas-staging.example.json	WorkOS, Stripe test mode, R2, OpenRouter, API key infrastructure enabled.
On-prem minimal	onprem-minimal.example.json	No WorkOS, no Stripe, S3-compatible storage, no external LLM key. Good for shell and config smoke tests.
On-prem S3/OIDC/OpenAI	onprem-s3-oidc-openai.example.json	Enterprise OIDC, S3-compatible storage, no billing, OpenAI model gateway.
Enterprise private	enterprise-private.example.json	OIDC, S3, direct OpenAI model provider, no billing, no browser/sandbox/integrations/search/telemetry.
DPDP strict	dpdp-strict.example.json	Minor mode metadata, external processors disabled by default, no model routing/search/tools/telemetry.

The examples contain placeholders only. Replace every placeholder or replace_with value before a real deployment.

Feature Gates

Feature gates must be enforced in UI and server routes. Disabled server routes return capability_disabled.

Feature	Typical enterprise use
`chat`, `files`, `memory`, `knowledge`, `automations`	Core product surfaces that can be enabled independently.
`integrations`, `browserUse`, `sandboxes`, `webSearch`	External processor surfaces; disable by default until the enterprise approves the processor.
`analytics`, `errorReporting`	Telemetry surfaces; disable for private/no-telemetry deployments.
`billing`, `webhooks`, `apiKeys`, `vectorSearch`, `modelRouting`, `sso`	Commercial, platform, retrieval, model, and auth surfaces.
`multiTenant`	Reserved. The schema rejects enabling this until shared multi-tenant isolation exists.

Environment Overrides

Common overrides:

OVERLAY_CONFIG_VERSION=2
OVERLAY_CONFIG_PRESET=enterprise-private
OVERLAY_COMPLIANCE_PROFILE=enterprise-private
OVERLAY_ALLOW_EXTERNAL_PROCESSORS=false
OVERLAY_ALLOWED_PROCESSORS=models:openai,objectStorage:s3

OVERLAY_FEATURE_BROWSER_USE=false
OVERLAY_FEATURE_SANDBOXES=false
OVERLAY_FEATURE_INTEGRATIONS=false
OVERLAY_FEATURE_WEB_SEARCH=false
OVERLAY_FEATURE_ANALYTICS=false
OVERLAY_FEATURE_ERROR_REPORTING=false

OVERLAY_PROVIDER_BROWSER=none
OVERLAY_PROVIDER_SANDBOX=none
OVERLAY_PROVIDER_INTEGRATIONS=none
OVERLAY_PROVIDER_WEB_SEARCH=none
OVERLAY_PROVIDER_ANALYTICS=none
OVERLAY_PROVIDER_ERROR_REPORTING=none

Storage overrides:

STORAGE_PROVIDER=s3
S3_BUCKET_NAME=overlay-enterprise
S3_REGION=us-east-1
# On AWS, omit static keys and grant the workload role bucket-scoped access.
# For other S3-compatible providers, configure both key variables together.
S3_ENDPOINT_URL=https://s3.enterprise.example.com
S3_ACCESS_KEY_ID=replace_with_s3_access_key
S3_SECRET_ACCESS_KEY=replace_with_s3_secret
S3_FORCE_PATH_STYLE=false

Validation

Run these before booting or publishing config docs:

OVERLAY_CONFIG_FILE=overlay.config.json npm run check:config
npm run docs:health

The config parser rejects unsupported-but-declared providers with explicit boot errors. convex is the only accepted app-data provider; postgres and pgvector configs now fail validation with guidance toward convex. Private deployments still require billing.provider="none" and capabilities.billing=false until the billing parity phase. Values such as e2b or self-hosted-playwright still fail during config validation instead of silently falling back.

Overview

Install

Configure

Operate

Enterprise

Licensing

Create A Config

Top-Level Shape

Presets

Example profiles

Feature Gates

Environment Overrides

Validation

​Create A Config

​Top-Level Shape

​Presets

​Example profiles

​Feature Gates

​Environment Overrides

​Validation

Create A Config

Top-Level Shape

Presets

Example profiles

Feature Gates

Environment Overrides

Validation