docs/reference/configuration.md

# Configuration reference

This page collects the most important config values.

## Root `.env` (Compose)

See `.env.example` for defaults and required values.

### `NEXT_PUBLIC_API_URL`

- **Where set:** `.env` (frontend container environment)
- **Purpose:** Public URL the browser uses to call the backend.
- **Gotcha:** Must be reachable from the *browser* (host), not a Docker network alias.

### `LOCAL_AUTH_TOKEN`

- **Where set:** `.env` (backend)
- **When required:** `AUTH_MODE=local`
- **Policy:** Must be non-placeholder and at least 50 characters.

### `WEBHOOK_MAX_PAYLOAD_BYTES`

- **Default:** `1048576` (1 MiB)
- **Purpose:** Maximum accepted inbound webhook payload size before the API returns `413 Content Too Large`.

### `RATE_LIMIT_BACKEND`

- **Default:** `memory`
- **Allowed values:** `memory`, `redis`
- **Purpose:** Selects whether rate limits are tracked per-process in memory or shared through Redis.

### `RATE_LIMIT_REDIS_URL`

- **Default:** _(blank)_
- **When required:** `RATE_LIMIT_BACKEND=redis` and `RQ_REDIS_URL` is not set
- **Purpose:** Redis connection string used for shared rate limits.
- **Fallback:** If blank and Redis rate limiting is enabled, the backend falls back to `RQ_REDIS_URL`.

### `TRUSTED_PROXIES`

- **Default:** _(blank)_
- **Purpose:** Comma-separated list of trusted reverse-proxy IPs or CIDRs used to honor `Forwarded` / `X-Forwarded-For` client IP headers.
- **Gotcha:** Leave this blank unless the direct peer is a proxy you control.

## Security response headers

These environment variables control security headers added to every API response. Set any variable to blank (`""`) to disable the corresponding header.

### `SECURITY_HEADER_X_CONTENT_TYPE_OPTIONS`

- **Default:** `nosniff`
- **Purpose:** Prevents browsers from MIME-type sniffing responses.

### `SECURITY_HEADER_X_FRAME_OPTIONS`

- **Default:** `DENY`
- **Purpose:** Prevents the API from being embedded in iframes.
- **Note:** If your deployment embeds the API in an iframe, set this to `SAMEORIGIN` or blank.

### `SECURITY_HEADER_REFERRER_POLICY`

- **Default:** `strict-origin-when-cross-origin`
- **Purpose:** Controls how much referrer information is sent with requests.

### `SECURITY_HEADER_PERMISSIONS_POLICY`

- **Default:** _(blank — disabled)_
- **Purpose:** Restricts browser features (camera, microphone, etc.) when set.
docs: add initial docs/ information architecture + stubs 2026-02-11 21:43:05 +00:00			`# Configuration reference`

			`This page collects the most important config values.`

			## Root `.env` (Compose)

			See `.env.example` for defaults and required values.

			### `NEXT_PUBLIC_API_URL`

			- Where set: `.env` (frontend container environment)
			`- Purpose: Public URL the browser uses to call the backend.`
			`- Gotcha: Must be reachable from the browser (host), not a Docker network alias.`

			### `LOCAL_AUTH_TOKEN`

			- Where set: `.env` (backend)
			- When required: `AUTH_MODE=local`
			`- Policy: Must be non-placeholder and at least 50 characters.`
docs: document security hardening changes from security review Add documentation for all user/operator-facing changes introduced by the security review branch: rate limits, security headers, webhook HMAC verification, payload size limits, gateway token redaction, non-root containers, agent token logging, and prompt injection mitigation. Updated: docs/reference/api.md, docs/reference/authentication.md, docs/reference/configuration.md, docs/deployment/README.md, docs/operations/README.md, docs/openclaw_gateway_ws.md, backend/README.md. Created: docs/reference/security.md (consolidated security reference). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> 2026-03-03 14:51:52 -07:00
fix(security): Close review follow-up gaps Rate-limit the optional agent bearer path after user auth resolution so mixed user/agent routes no longer leave an unthrottled PBKDF2 path. Stop logging token prefixes on agent auth failures and require a locally supplied token for backend/.env.test instead of committing one. Update tests and docs to cover agent bearer fallback, configurable webhook signature headers, and the operator-facing security settings added by the hardening work. Co-Authored-By: Claude <noreply@anthropic.com> 2026-03-07 23:40:50 +05:30			### `WEBHOOK_MAX_PAYLOAD_BYTES`

			- Default: `1048576` (1 MiB)
			- Purpose: Maximum accepted inbound webhook payload size before the API returns `413 Content Too Large`.

			### `RATE_LIMIT_BACKEND`

			- Default: `memory`
			- Allowed values: `memory`, `redis`
			`- Purpose: Selects whether rate limits are tracked per-process in memory or shared through Redis.`

			### `RATE_LIMIT_REDIS_URL`

			`- Default: _(blank)_`
			- When required: `RATE_LIMIT_BACKEND=redis` and `RQ_REDIS_URL` is not set
			`- Purpose: Redis connection string used for shared rate limits.`
			- Fallback: If blank and Redis rate limiting is enabled, the backend falls back to `RQ_REDIS_URL`.

			### `TRUSTED_PROXIES`

			`- Default: _(blank)_`
			- Purpose: Comma-separated list of trusted reverse-proxy IPs or CIDRs used to honor `Forwarded` / `X-Forwarded-For` client IP headers.
			`- Gotcha: Leave this blank unless the direct peer is a proxy you control.`

docs: document security hardening changes from security review Add documentation for all user/operator-facing changes introduced by the security review branch: rate limits, security headers, webhook HMAC verification, payload size limits, gateway token redaction, non-root containers, agent token logging, and prompt injection mitigation. Updated: docs/reference/api.md, docs/reference/authentication.md, docs/reference/configuration.md, docs/deployment/README.md, docs/operations/README.md, docs/openclaw_gateway_ws.md, backend/README.md. Created: docs/reference/security.md (consolidated security reference). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> 2026-03-03 14:51:52 -07:00			`## Security response headers`

			These environment variables control security headers added to every API response. Set any variable to blank (`""`) to disable the corresponding header.

			### `SECURITY_HEADER_X_CONTENT_TYPE_OPTIONS`

			- Default: `nosniff`
			`- Purpose: Prevents browsers from MIME-type sniffing responses.`

			### `SECURITY_HEADER_X_FRAME_OPTIONS`

			- Default: `DENY`
			`- Purpose: Prevents the API from being embedded in iframes.`
			- Note: If your deployment embeds the API in an iframe, set this to `SAMEORIGIN` or blank.

			### `SECURITY_HEADER_REFERRER_POLICY`

			- Default: `strict-origin-when-cross-origin`
			`- Purpose: Controls how much referrer information is sent with requests.`

			### `SECURITY_HEADER_PERMISSIONS_POLICY`

			`- Default: _(blank — disabled)_`
			`- Purpose: Restricts browser features (camera, microphone, etc.) when set.`