Configuration

OpenCluster uses safe defaults for server addresses, local authentication, logs, telemetry, investigation limits, concurrency, retention, retries, request timeouts, and shutdown. A normal installation supplies database, AI, and encryption files plus its public URL. Supply the bootstrap credential only for initial setup, then remove it. OpenCluster resolves configuration in this order:

Built-in defaults.
The optional YAML file named by OC_CONFIG_FILE.
OC_* environment variables.

Environment variables override only the corresponding file values. Unknown YAML fields, invalid values, and additional YAML documents stop startup instead of being ignored.

Minimal configuration

export OC_DATABASE_DSN_FILE=/run/secrets/postgres_dsn
export OC_BOOTSTRAP_TOKEN_FILE=/run/secrets/bootstrap_token
export OC_ENCRYPTION_KEY_FILE=/run/secrets/sealing_key
export OC_AI_PROVIDER=anthropic
export OC_AI_MODEL=claude-sonnet-5
export OC_AI_API_KEY_FILE=/run/secrets/model_key
controlplane

Direct alternatives are the same names without _FILE, for example OC_AI_API_KEY. Use direct values for local development and mounted files for production when practical. Never set both forms of one secret. Remove the bootstrap input after initial setup.

Configuration file

Set OC_CONFIG_FILE to load product-oriented YAML. Plaintext secrets are not accepted in YAML; reference mounted files instead:

server:
  address: ":8080"
  publicURL: "https://opencluster.example"
telemetry:
  logLevel: info
  otlpEndpoint: "otel-collector:4317"
database:
  dsnFile: /run/secrets/postgres_dsn
session:
  lifetime: 12h
relay:
  address: ":8443"
  spkiPins:
    - "BASE64_SHA256_PIN"
ai:
  provider: anthropic
  model: claude-sonnet-5
  apiKeyFile: /run/secrets/model_key
  contextWindow: 200000
  maxOutputTokens: 32000
investigations:
  workers: 8
  maxPendingPerOrganization: 100
oidc:
  issuer: "https://id.example.com"
  clientID: opencluster
  clientSecretFile: /run/secrets/oidc_secret
slack:
  clientID: slack-client
  clientSecretFile: /run/secrets/slack_client_secret
  signingSecretFile: /run/secrets/slack_signing_secret
github:
  appID: "12345"
  privateKeyFile: /run/secrets/github_private_key
security:
  encryptionKeyFile: /run/secrets/encryption_key
  bootstrapTokenFile: /run/secrets/bootstrap_token

Omit optional sections that the deployment does not use. Values are strings except relay.spkiPins (an array), ai.contextWindow, ai.maxOutputTokens, investigations.workers, and investigations.maxPendingPerOrganization (integers). session.lifetime is a Go duration such as 12h. Relative secret paths in YAML are resolved from the configuration file’s directory. _FILE environment paths remain process-relative. An environment list setting such as OC_RELAY_SPKI_PINS replaces the entire YAML list.

Applying changes

Configuration and secret files are read once at startup. A file update does not reload a running process. For Compose, recreate the control plane with docker compose -f deploy/compose/compose.yaml up -d --force-recreate control-plane. For Helm, ordinary values change the Deployment and trigger rollout. After updating an existing Secret, run kubectl rollout restart deployment/<release>-opencluster, then kubectl rollout status deployment/<release>-opencluster. Confirm /readyz and a bounded Investigation before considering the change complete. Set OC_LOG_LEVEL to debug, info, warn, or error; the default is info. Use OC_OTLP_ENDPOINT when exporting traces to a collector. Local authentication is always available. OIDC is enabled when its issuer, client ID, and client secret are all configured; a partial OIDC configuration stops startup. Relay is optional and listens separately from HTTP; customer Relays initiate outbound connections and pin the configured control-plane key. OC_SESSION_LIFETIME_SECONDS is deployment-owned and defaults to 43,200 seconds. Organizations start with 90 days of audit retention and can configure it independently; browser credential lifetime remains deployment-owned.

Model provider

OSS v0.1 supports deployment-level Anthropic or Z.AI credentials. Set OC_AI_PROVIDER to anthropic or zai, set OC_AI_MODEL to an exact model identifier accepted by that provider, and set OC_AI_API_KEY_FILE to the mounted credential file. Organization-level BYOK is not part of the OSS v0.1 contract. OpenCluster supplies the exact context and maximum output limits for the shipped model IDs: claude-sonnet-5, claude-opus-5, claude-haiku-4-5-20251001, and glm-4.7.

Advanced: custom models

For a custom provider model ID, set both OC_AI_CONTEXT_WINDOW_SIZE and OC_AI_MAX_OUTPUT_SIZE. These advanced overrides may lower a shipped model’s limits but cannot exceed its published capacity. Restart the control plane, wait for /readyz, and run one bounded Investigation. Startup proves that the file is readable; only a completed Investigation proves that the selected provider and model satisfy the structured result contract. For authentication, quota, rate-limit, or unsupported-model errors, correct the provider account or model and start a new Investigation. OpenCluster sends bounded Investigation context, Tool summaries, and the structured result contract. It does not persist or expose model chain-of-thought. Review the security model and the provider’s retention, regional processing, and training terms before production use.

Environment reference

Variable	Purpose
`OC_CONFIG_FILE`	Optional strict YAML configuration file.
`OC_SERVER_ADDRESS`	HTTP listen address; default `:8080`.
`OC_PUBLIC_URL`	Browser and webhook origin; default `http://localhost:8080`.
`OC_DATABASE_DSN` / `OC_DATABASE_DSN_FILE`	PostgreSQL DSN file. Direct value or file; do not set both.
`OC_SESSION_LIFETIME_SECONDS`	Browser session lifetime in seconds; default `43200`, range `300`–`2592000`.
`OC_BOOTSTRAP_TOKEN` / `OC_BOOTSTRAP_TOKEN_FILE`	Optional one-time first-User bootstrap token file. Omit after setup to disable initialization. Direct value or file; do not set both.
`OC_OIDC_ISSUER`	HTTPS OIDC issuer.
`OC_OIDC_CLIENT_ID`	OIDC client ID.
`OC_OIDC_CLIENT_SECRET` / `OC_OIDC_CLIENT_SECRET_FILE`	OIDC client-secret file. Direct value or file; do not set both.
`OC_RELAY_ADDRESS`	Optional Relay gRPC listen address.
`OC_RELAY_SPKI_PINS`	Comma-separated control-plane SPKI pins.
`OC_AI_PROVIDER`	Native AI provider: `anthropic` or `zai`.
`OC_AI_MODEL`	Exact model identifier.
`OC_AI_API_KEY` / `OC_AI_API_KEY_FILE`	AI provider credential file. Direct value or file; do not set both.
`OC_AI_CONTEXT_WINDOW_SIZE`	Optional advanced model context-window override; required for a custom model ID.
`OC_AI_MAX_OUTPUT_SIZE`	Optional advanced model output-limit override in tokens; required for a custom model ID.
`OC_INVESTIGATION_WORKERS`	Concurrent Investigation workers per replica; default `8`.
`OC_MAX_PENDING_INVESTIGATIONS_PER_ORGANIZATION`	Maximum unclaimed Investigations per Organization; default `100`.
`OC_ENCRYPTION_KEY` / `OC_ENCRYPTION_KEY_FILE`	32-byte credential-encryption key file. Direct value or file; do not set both.
`OC_LOG_LEVEL`	Log level; default `info`.
`OC_OTLP_ENDPOINT`	Optional OTLP collector host and port.
`OC_SLACK_CLIENT_ID`	Deployment Slack App client ID.
`OC_SLACK_CLIENT_SECRET` / `OC_SLACK_CLIENT_SECRET_FILE`	Slack App client-secret file. Direct value or file; do not set both.
`OC_SLACK_SIGNING_SECRET` / `OC_SLACK_SIGNING_SECRET_FILE`	Slack request signing-secret file. Direct value or file; do not set both.
`OC_GITHUB_APP_ID`	Deployment GitHub App ID.
`OC_GITHUB_APP_PRIVATE_KEY` / `OC_GITHUB_APP_PRIVATE_KEY_FILE`	GitHub App private-key file. Direct value or file; do not set both.

The OSS binary uses one mounted AI deployment for every Organization. Back up retained installation data before replacing a pre-release deployment. This baseline requires a fresh application database and does not import retained data from an older schema. The shared HTTP server allows 10 seconds for headers, 30 seconds to read a request, 30 seconds to write a response, and 60 seconds for an idle connection. Restart after a change, then verify /healthz, /readyz, sign-in, Organization access, Integration verification, and one bounded Investigation.

Webhook admission limits

Each control-plane process allows a shared burst of 600 webhook requests and restores 10 requests per second before authentication. This protects both alert and Slack intake; changing an Integration identifier or forwarding header does not create fresh capacity. During overload, alert webhooks receive 503 and Slack receives 429; both include Retry-After. The budget is process-wide and multiplies across replicas. Integration identifiers and credentials do not create separate in-memory quotas. The metrics endpoint exposes oc.webhooks.requests by surface and bounded result, oc.webhooks.alert_events for newly committed Alert Events, and oc.webhooks.slack_ack_duration for Slack acknowledgement latency. OC_MAX_PENDING_INVESTIGATIONS_PER_ORGANIZATION separately bounds the durable pending Investigation queue; its default is 100. Automatic alert Investigations, manual Investigations, and Conversation turns share this Organization-wide capacity across replicas. Claimed Investigations no longer consume pending capacity. When a model provider is configured, an alert delivery that opens new Incidents must fit all their automatic Investigations. If the current backlog cannot fit them, the whole delivery is refused with 503 and Retry-After; a delivery needing more slots than the configured limit receives permanent 400. Without a model provider, alert intake records Incident state without reserving Investigation capacity.

Get started

Concepts

Integrations

Self-hosting

Security

API reference

Developers

Minimal configuration

Configuration file

Applying changes

Model provider

Advanced: custom models

Environment reference

Webhook admission limits

​Minimal configuration

​Configuration file

​Applying changes

​Model provider

​Advanced: custom models

​Environment reference

​Webhook admission limits

Minimal configuration

Configuration file

Applying changes

Model provider

Advanced: custom models

Environment reference

Webhook admission limits