> ## 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-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:

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