Runtime Config - Overlay Web

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

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
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. postgres app-data config is accepted when OVERLAY_DATABASE_URL is present. Private deployments still require billing.provider="none" and capabilities.billing=false until the billing parity phase. pgvector is supported with Postgres plus an embeddings provider and durable worker; values such as e2b or self-hosted-playwright still fail during config validation instead of silently falling back.

​Create A Config

​Top-Level Shape

​Presets

​Feature Gates

​Environment Overrides

​Validation