Configuration

Optio is configured through environment variables, Helm chart values, and per-repository settings in the dashboard. This page covers all three layers.

Environment Variables

These are set on the API server. In Kubernetes, they are configured via the Helm chart's api.env section or directly as environment variables on the deployment.

Core

Concurrency & Tuning

Authentication

Generic OIDC Provider

Any OpenID Connect-compatible identity provider (Keycloak, Authentik, Authelia, Zitadel, Okta, Auth0, etc.) can be used via the generic OIDC provider. Set OIDC_ISSUER_URL to the issuer URL and configure the client credentials. The discovery document is fetched automatically from <issuer>/.well-known/openid-configuration.

OIDC_ISSUER_URL=https://auth.example.com/realms/optio
OIDC_CLIENT_ID=optio
OIDC_CLIENT_SECRET=your-client-secret
OIDC_DISPLAY_NAME="Company SSO"

# Register the callback URL in your IdP:
# {PUBLIC_URL}/api/auth/oidc/callback

Helm Chart Values

The Helm chart at helm/optio/ deploys the full stack. Here are the key configuration sections.

Database & Redis

# Use built-in instances (dev only)
postgresql:
  enabled: true
  auth:
    password: "optio_dev"
redis:
  enabled: true

# Use external managed services (production)
postgresql:
  enabled: false
externalDatabase:
  url: "postgresql://user:pass@your-db:5432/optio"
redis:
  enabled: false
externalRedis:
  url: "redis://your-redis:6379"

Encryption

# Generate a 32-byte hex key
openssl rand -hex 32

encryption:
  key: "your-64-character-hex-string-here"

Agent Images

agent:
  # For local dev (images loaded directly into K8s containerd)
  imagePullPolicy: Never

  # For production (images in a container registry)
  imagePullPolicy: IfNotPresent
  # or: Always

Ingress

ingress:
  enabled: true
  hosts:
    - host: optio.example.com
  tls: true

Services

# Local dev (NodePort for direct access)
api:
  service:
    type: NodePort
    nodePort: 30400
web:
  service:
    type: NodePort
    nodePort: 30310

# Production (ClusterIP behind ingress)
api:
  service:
    type: ClusterIP
web:
  service:
    type: ClusterIP

Auth

auth:
  # Disable for local development
  disabled: true

  # Production: configure OAuth providers
  github:
    clientId: "your-client-id"
    clientSecret: "your-client-secret"
  google:
    clientId: "your-client-id"
    clientSecret: "your-client-secret"

What the Chart Creates

• Namespace, ServiceAccount, and RBAC (pod/exec/secret management)
• API deployment + service with health probes
• Web deployment + service
• Conditional PostgreSQL and Redis deployments
• Configurable Ingress resource

Per-Repository Settings

Each connected repository has its own settings, configured in the dashboard under Repos → Settings.

General

Claude Settings

Review Settings

Prompt Templates

System prompts use a simple template language with variable substitution and conditionals.

Available Variables

Conditionals

{{#if AUTO_MERGE}}
After CI passes, the PR will be auto-merged.
{{else}}
Wait for manual review before merging.
{{/if}}

Priority Chain

Templates are resolved in order of specificity:

1. Per-repo override (repos.promptTemplateOverride)
2. Global default (prompt_templates table)
3. Hardcoded fallback in @optio/shared

Review prompts follow the same chain: repos.reviewPromptTemplate → default review template.

Secrets

Secrets are managed in the dashboard under Secrets and are encrypted at rest with AES-256-GCM. Key secrets to configure:

• CLAUDE_AUTH_MODE — api-key or oauth-token
• ANTHROPIC_API_KEY — Your API key (if using api-key mode)
• CLAUDE_CODE_OAUTH_TOKEN — OAuth token (if using oauth-token mode)
• GITHUB_TOKEN — GitHub personal access token for PR watching, issue sync, and repo detection

Next Steps