> ## Documentation Index
> Fetch the complete documentation index at: https://getoverlay.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Runtime config

> Configure Overlay Web with overlay.config.json, feature gates, and environment overrides.

Overlay Web loads runtime configuration in this precedence order:

1. Environment variables.
2. `OVERLAY_CONFIG_FILE`, normally `overlay.config.json`.
3. 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

```bash theme={null}
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:

```bash theme={null}
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](https://getoverlay.io/docs/config/saas-staging.example.json) | WorkOS, Stripe test mode, R2, OpenRouter, API key infrastructure enabled. |
| On-prem minimal | [onprem-minimal.example.json](https://getoverlay.io/docs/config/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](https://getoverlay.io/docs/config/onprem-s3-oidc-openai.example.json) | Enterprise OIDC, S3-compatible storage, no billing, OpenAI model gateway. |
| Enterprise private | [enterprise-private.example.json](https://getoverlay.io/docs/config/enterprise-private.example.json) | OIDC, S3, direct OpenAI model provider, no billing, no browser/sandbox/integrations/search/telemetry. |
| DPDP strict | [dpdp-strict.example.json](https://getoverlay.io/docs/config/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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.