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 the database, bootstrap, AI, and encryption files plus its public URL. Environment values that end in _FILE name mounted files; they never contain the credential itself. YAML settings ending in _file follow the same rule.

Minimal YAML

server:
  public_url: "https://opencluster.example.com"
database:
  dsn_file: "/run/opencluster/database/postgres-dsn"
authentication:
  bootstrap_token_file: "/run/opencluster/credentials/bootstrap-token"
  encryption_key_file: "/run/opencluster/credentials/encryption-key"
ai:
  provider: "anthropic"
  model: "MODEL_ID"
  api_key_file: "/run/opencluster/credentials/model-key"

Pass the file with --config /etc/opencluster/opencluster.yaml or OC_CONFIG_FILE. Environment variables override YAML. Unknown YAML fields and additional documents stop startup, so misspelled configuration is never silently ignored.

Optional YAML

server:
  address: ":8080"
authentication:
  mode: "oidc"
  oidc:
    issuer: "https://identity.example.com"
    client_id: "opencluster"
    client_secret_file: "/run/opencluster/credentials/oidc-client-secret"
relay:
  address: ":8443"
  spki_pins: ["BASE64_SHA256_SPKI"]
telemetry:
  log_level: "info"
  otlp_endpoint: "collector.example.com:4317"
slack:
  client_id: "SLACK_CLIENT_ID"
  client_secret_file: "/run/opencluster/credentials/slack-client-secret"
  signing_secret_file: "/run/opencluster/credentials/slack-signing-secret"
github:
  app_id: "12345"
  app_private_key_file: "/run/opencluster/credentials/github-app-key"

Local authentication is the default. oidc adds the configured provider while local Admin recovery remains available. Relay is optional and listens separately from HTTP; customer Relays initiate outbound connections and pin the configured control-plane key.

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. 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 YAML file path.
`OC_SERVER_ADDRESS`	HTTP listen address; default `:8080`.
`OC_PUBLIC_URL`	Browser and webhook origin; default `http://localhost:8080`.
`OC_DATABASE_DSN_FILE`	PostgreSQL DSN file.
`OC_AUTH_MODE`	`local` or `oidc`.
`OC_BOOTSTRAP_TOKEN_FILE`	One-time first-User bootstrap token file.
`OC_OIDC_ISSUER`	HTTPS OIDC issuer.
`OC_OIDC_CLIENT_ID`	OIDC client ID.
`OC_OIDC_CLIENT_SECRET_FILE`	OIDC client-secret file.
`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_FILE`	AI provider credential file.
`OC_ENCRYPTION_KEY_FILE`	32-byte credential-encryption key file.
`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_FILE`	Slack App client-secret file.
`OC_SLACK_SIGNING_SECRET_FILE`	Slack request signing-secret file.
`OC_GITHUB_APP_ID`	Deployment GitHub App ID.
`OC_GITHUB_APP_PRIVATE_KEY_FILE`	GitHub App private-key file.

The OSS binary uses one mounted AI deployment for every Organization. The resolver keeps Organization explicit so a separate hosted composition can select managed or encrypted Organization BYOK without changing investigation behavior. This is a pre-release clean break. Existing databases and configuration from earlier builds must be recreated rather than migrated through compatibility settings. 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 selection, Integration verification, and one bounded Investigation.

Get started

Concepts

Integrations

Self-hosting

Security

API reference

Developers

Minimal YAML

Optional YAML

Model provider

Environment reference

​Minimal YAML

​Optional YAML

​Model provider

​Environment reference

Minimal YAML

Optional YAML

Model provider

Environment reference