Reference
Look up every supported Clearplane configuration setting.
The complete configuration catalog is generated from the validated application metadata and lists every setting's accepted values, default, supported sources, lifecycle, sensitivity, apply behavior, and UI location, with configuration examples.
The Docker label reference, environment variable reference, and REST API guide add worked examples and the rules the catalog does not cover.
Client addresses behind a proxy
In System โ Settings โ Edge โ Network, configure Trusted proxies and Client IP headers together. Both settings are staged; apply the saved configuration to Edge.
| Setting | Default | Behavior |
|---|---|---|
clearplane.edge.trusted-proxies |
Empty | Canonical IPv4 or IPv6 direct peer addresses or CIDR ranges permitted to supply the client address; /0 is forbidden. |
clearplane.edge.client-ip-headers |
X-Forwarded-For |
Ordered list of unique, case-insensitive HTTP header names, up to 256 characters each. X-Forwarded-For uses the existing right-to-left proxy-chain resolution. Any other name, such as CF-Connecting-IP, True-Client-IP or X-Real-IP, requires exactly one IP address. |
Edge uses the first non-empty configured header from a trusted peer. Missing or whitespace-only headers are skipped. A malformed selected value keeps the peer address and logs a warning, without trying later headers. If all configured headers are absent or empty, Edge keeps the peer address; lists containing a custom header also log a warning. The default X-Forwarded-For-only list keeps its existing silent behavior when absent.
A single-address value accepts IPv4 or IPv6, without a port, brackets, zone identifier or address list. Repeated single-address headers are malformed. X-Forwarded-For is used only when explicitly listed. Untrusted peers keep their peer address, and all their configured client IP headers are removed before forwarding upstream.
For proxies that can safely supply either header, an explicit priority list can be configured as:
clearplane.edge.client-ip-headers: "X-Real-IP X-Forwarded-For"
This prefers X-Real-IP and uses X-Forwarded-For only when the preferred header is absent or empty. Every listed header must be trustworthy from every trusted proxy: a fallback that the proxy passes through from a client can let that client choose its address. Keep a single entry when only one header is authoritative. In the UI, add headers in priority order; remove and re-add a header to move it last.
Cloudflare Tunnel example
For a dedicated Docker network with subnet 172.30.10.0/24 shared by Edge and cloudflared, place these labels on Edge:
services:
clearplane-edge:
labels:
clearplane.edge.trusted-proxies: "172.30.10.0/24"
clearplane.edge.client-ip-headers: "CF-Connecting-IP"
Replace the subnet with the dedicated network's actual canonical CIDR. Private subnets are accepted; /0 is rejected. A dedicated subnet survives container IP changes on restart, but every peer on it is trusted, so keep unrelated containers off it. Connect the tunnel directly to Edge on that network. See the client-address trust boundary before enabling it.
Language models and coding agents can start at /llms.txt.