> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open-cluster.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Configure an OpenCluster deployment with a small, file-backed surface.

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

```yaml theme={null}
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

```yaml theme={null}
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](/security/overview) 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.