Configuration - OpenCluster

OpenCluster reads configuration from environment variables and validates it before starting. Variables that refer to credentials contain file paths, not secret values.

Storage and process

Variable	Required	Purpose
`OC_HTTP_ADDRESS`	Yes	Health, readiness, and metrics listen address.
`OC_PLACEMENTS`	Yes	Comma-separated `name=dsn-file-path` entries.
`OC_DEFAULT_PLACEMENT`	One placement rule required	Placement for organizations without an explicit assignment.
`OC_PLACEMENT_ASSIGNMENTS`	One placement rule required	Comma-separated `organization=placement` entries.
`OC_SHUTDOWN_TIMEOUT`	No	Graceful shutdown budget. Default: `15s`.
`OC_SERVICE_NAME`	No	Telemetry service name. Default: `oc-control-plane`.
`OC_OTLP_ENDPOINT`	No	OTLP trace collector as `host:port`. Empty disables trace export.

OC_DEFAULT_PLACEMENT or OC_PLACEMENT_ASSIGNMENTS must resolve every served organization. OpenCluster does not fall back to another placement after resolution fails.

Operator access

Variable	Required	Purpose
`OC_OPERATOR_ADDRESS`	No	Operator listener. Empty disables it.
`OC_OPERATOR_TOKEN_FILE`	With bootstrap access	File containing a token of at least 32 characters.
`OC_OPERATOR_TOKEN_ORGANIZATION`	With bootstrap token	Organization the token can access.
`OC_OPERATOR_TOKEN_ROLE`	No	Token role. Default: `admin`.
`OC_OPERATOR_PUBLIC_URL`	With browser sign-in	Public HTTPS origin used for identity-provider redirects.
`OC_OPERATOR_CONSOLE_URL`	With browser sign-in	Console URL used after sign-in.
`OC_OPERATOR_ALLOWED_ORIGINS`	With browser console	Origins allowed for cookie-authenticated unsafe requests.
`OC_SEALING_KEY_FILE`	With operator listener	File containing a 32-byte raw or base64 key for stored credentials. The operator surface can accept Slack credentials, so it refuses to start without this key.

The operator public and console URLs must share a registrable domain. Keep the operator listener private even when a browser-facing proxy is configured.

Intake and Relay

Variable	Required	Purpose
`OC_INTAKE_ADDRESS`	No	Alert intake listener. Empty disables intake.
`OC_INTAKE_PUBLIC_URL`	With intake	Public HTTPS origin used to generate webhook URLs.
`OC_RELAY_ADDRESS`	No	Relay listener. Empty disables Relay access.
`OC_RELAY_SPKI_PINS`	With Relay	Comma-separated public-key digests given to Relays at enrolment. Keep overlapping pins during rotation.
`OC_MINIMUM_RELAY_VERSION`	No	Version floor used to report outdated Relays.
`OC_INVENTORY_INTERVAL`	No	Requested Relay inventory interval. Default: `5m`; each Relay may apply a floor.
`OC_CHANGE_LEDGER_RETENTION_DAYS`	No	Kubernetes change-history retention. Default: `90`.

Integrations

Variable	Required	Purpose
`OC_SLACK_API_URL`	No	Slack API origin override. Empty uses Slack.
`OC_GITHUB_APP_ID`	With GitHub	GitHub App ID.
`OC_GITHUB_APP_PRIVATE_KEY_FILE`	With GitHub	File containing the App private key in PEM format.
`OC_GITHUB_API_URL`	No	GitHub API origin. Use `https://HOST/api/v3` for GitHub Enterprise Server.

The GitHub App ID and key file are required together. Slack requires OC_SEALING_KEY_FILE because its token is stored encrypted.

Investigations

Variable	Required	Purpose
`OC_MODEL_PROVIDER`	With investigations	`anthropic` or `zai`. Empty disables new investigations.
`OC_MODEL_NAME`	With provider	Exact provider model identifier.
`OC_MODEL_KEY_FILE`	With provider	File containing the provider API key.
`OC_MODEL_CONSENTED_PROVIDERS`	With provider	Comma-separated providers approved to receive investigation data. Must include the configured provider.
`OC_MODEL_EFFORT`	No	`low`, `medium`, `high`, `xhigh`, or `max`. Default: `high`.
`OC_MODEL_BASE_URL`	No	Provider endpoint override. HTTPS is required except for loopback.
`OC_MODEL_SPEND_CEILING_CENTS`	No	Positive per-investigation spend ceiling. Default: `500`.
`OC_INVESTIGATION_WINDOW_LEAD`	No	Time added before the incident start. Default: `2h`.
`OC_INVESTIGATION_MAX_TOOL_RUNS`	No	Maximum source reads. Default: `30`.
`OC_INVESTIGATION_MAX_TURNS`	No	Maximum reasoning turns. Default: `20`.

Provider consent is deployment-wide. Review what is sent to the model provider before enabling investigations.

Validation rules

Public URLs and vendor overrides require HTTPS except on loopback.
Partial GitHub or model-provider credentials refuse startup.
Enabling the operator listener requires a sealing key because the catalog accepts Slack credentials.
An unlisted model provider cannot receive investigation data.
The first invalid setting stops startup and names the variable to fix.

⌘I