Helm Chart Reference

The Optio Helm chart (helm/optio/, chart version 0.1.0) deploys the full stack — API server, web UI, PostgreSQL, Redis, RBAC, and Ingress — to any Kubernetes cluster.

All values can be passed via --set key=value on the command line or via a custom values.yaml file passed with -f my-values.yaml. For production deployments, a values file is recommended to keep configuration under version control.

API server

api.*

Value	Type	Default	Description
`api.image.repository`	string	`optio-api`	Container image repository for the API server. Override with a registry path for production (e.g. `ghcr.io/your-org/optio-api`).
`api.image.tag`	string	`latest`	Image tag. Pin to a specific version for reproducible deployments.
`api.image.pullPolicy`	string	`IfNotPresent`	Image pull policy. Use `Never` for local development (images loaded into containerd locally). Use `IfNotPresent` or `Always` for registry images.
`api.replicas`	number	`1`	Number of API server replicas. Multiple replicas are safe — BullMQ workers use Redis-backed leader election so each job is delivered to exactly one worker.
`api.port`	number	`4000`	Container port the API server listens on.
`api.service.type`	string	`ClusterIP`	Kubernetes service type. Set to `NodePort` for local development (Docker Desktop, kind, minikube).
`api.service.nodePort`	string	`""`	Fixed NodePort number when `api.service.type=NodePort`. Example: `30400`.
`api.resources.requests.cpu`	string	`250m`	CPU request for the API pod.
`api.resources.requests.memory`	string	`512Mi`	Memory request for the API pod.
`api.resources.limits.cpu`	string	`1`	CPU limit for the API pod.
`api.resources.limits.memory`	string	`1Gi`	Memory limit for the API pod.
`api.env.LOG_LEVEL`	string	`info`	Log verbosity. Accepts `debug`, `info`, `warn`, `error`.
`api.antiAffinity`	string	`soft`	Pod anti-affinity for spreading replicas across nodes. `soft` = preferred scheduling, `hard` = required scheduling, `""` = disabled.

Web UI

web.*

Value	Type	Default	Description
`web.image.repository`	string	`optio-web`	Container image repository for the web UI. Override with a registry path for production.
`web.image.tag`	string	`latest`	Image tag.
`web.image.pullPolicy`	string	`IfNotPresent`	Image pull policy. Use `Never` for local development.
`web.replicas`	number	`1`	Number of web UI replicas.
`web.port`	number	`3000`	Container port the Next.js server listens on.
`web.service.type`	string	`ClusterIP`	Kubernetes service type. Set to `NodePort` for local development.
`web.service.nodePort`	string	`""`	Fixed NodePort number when `web.service.type=NodePort`. Example: `30310`.
`web.resources.requests.cpu`	string	`100m`	CPU request for the web pod.
`web.resources.requests.memory`	string	`256Mi`	Memory request for the web pod.
`web.resources.limits.cpu`	string	`500m`	CPU limit for the web pod.
`web.resources.limits.memory`	string	`512Mi`	Memory limit for the web pod.
`web.antiAffinity`	string	`soft`	Pod anti-affinity. Same options as `api.antiAffinity`.

Agent containers

agent.*

Agent containers are the Kubernetes pods provisioned per repository by the API server. They are not deployed as a Deployment — the API creates them dynamically.

Value	Type	Default	Description
`agent.image.repository`	string	`optio-base`	Image repository for agent pods. For production, use a registry path (e.g. `ghcr.io/your-org/optio-agent-base`). Individual repos can override this with a different preset (`optio-node`, `optio-python`, `optio-go`, `optio-rust`, `optio-full`).
`agent.image.tag`	string	`latest`	Image tag for agent pods.
`agent.image.pullPolicy`	string	`Never`	Image pull policy for the `agent.image` setting.
`agent.imagePullPolicy`	string	`Never`	Primary pull policy applied to dynamically created agent pods. Set to `IfNotPresent` or `Always` for registry images. Do not use `Never` in production.
`agent.pvc.storageClass`	string	`""`	Storage class for agent pod PersistentVolumeClaims. Empty string uses the cluster default storage class.
`agent.pvc.size`	string	`10Gi`	PVC size per agent pod instance. Each pod instance gets its own PVC.
`agent.pvc.accessModes`	list	`[ReadWriteOnce]`	PVC access modes.

agent.imagePullPolicy=Never is the default for local development. If left as Never in a production cluster, agent pods will fail to start because the images are not present in the node’s local container store. Always set this to IfNotPresent or Always in production.

PostgreSQL

postgresql.*

The chart includes an in-cluster PostgreSQL deployment for development convenience. For production, disable it and use a managed database.

Value	Type	Default	Description
`postgresql.enabled`	boolean	`true`	Deploy an in-cluster PostgreSQL instance. Set to `false` for production — use `externalDatabase.url` instead.
`postgresql.image.repository`	string	`postgres`	PostgreSQL image repository.
`postgresql.image.tag`	string	`16`	PostgreSQL version. Optio requires PostgreSQL 16+.
`postgresql.storage.size`	string	`5Gi`	PVC size for the PostgreSQL data volume.
`postgresql.auth.database`	string	`optio`	Database name.
`postgresql.auth.username`	string	`optio`	Database username.
`postgresql.auth.password`	string	`""`	Database password. Required when `postgresql.enabled=true` and `auth.disabled=false`. The chart will fail to install if this is left empty with auth enabled. Generate with: `openssl rand -hex 16`.
`postgresql.resources.requests.cpu`	string	`100m`	CPU request.
`postgresql.resources.requests.memory`	string	`256Mi`	Memory request.
`postgresql.resources.limits.cpu`	string	`500m`	CPU limit.
`postgresql.resources.limits.memory`	string	`512Mi`	Memory limit.

In-cluster PostgreSQL is not recommended for production. It has no replication, no automated backups, and no HA. Use a managed service (RDS, Cloud SQL, Supabase, Neon) and set postgresql.enabled=false.

Redis

redis.*

The chart includes an in-cluster Redis deployment for development convenience. For production, disable it and use a managed Redis service.

Value	Type	Default	Description
`redis.enabled`	boolean	`true`	Deploy an in-cluster Redis instance. Set to `false` for production — use `externalRedis.url` instead.
`redis.image.repository`	string	`redis`	Redis image repository.
`redis.image.tag`	string	`7-alpine`	Redis version. Optio requires Redis 7+.
`redis.resources.requests.cpu`	string	`50m`	CPU request.
`redis.resources.requests.memory`	string	`128Mi`	Memory request.
`redis.resources.limits.cpu`	string	`250m`	CPU limit.
`redis.resources.limits.memory`	string	`256Mi`	Memory limit.

In-cluster Redis is not recommended for production. Use a managed service (ElastiCache, Upstash, Redis Cloud) and set redis.enabled=false.

External database and Redis

externalDatabase.* / externalRedis.*

Used when the in-cluster deployments are disabled.

Value	Type	Default	Description
`externalDatabase.url`	string	`""`	PostgreSQL connection URL. Required when `postgresql.enabled=false`. Format: `postgres://user:pass@host:5432/dbname`.
`externalRedis.url`	string	`""`	Redis connection URL. Required when `redis.enabled=false`. Format: `redis://host:6379` or `rediss://host:6380` for TLS.

Authentication

auth.*

Optio uses multi-provider OAuth for web UI and API authentication. At least one provider must be configured unless auth.disabled=true.

Value	Type	Default	Description
`auth.disabled`	boolean	`false`	Skip all authentication checks. Do not set to `true` in production. Intended only for local development.
`auth.github.clientId`	string	`""`	GitHub OAuth application client ID.
`auth.github.clientSecret`	string	`""`	GitHub OAuth application client secret.
`auth.google.clientId`	string	`""`	Google OAuth application client ID.
`auth.google.clientSecret`	string	`""`	Google OAuth application client secret.
`auth.gitlab.clientId`	string	`""`	GitLab OAuth application client ID.
`auth.gitlab.clientSecret`	string	`""`	GitLab OAuth application client secret.

To enable a provider, set both its clientId and clientSecret. A provider with either field empty is treated as not configured.For self-hosted GitLab, add GITLAB_OAUTH_BASE_URL as an environment variable on the API deployment pointing to your GitLab instance URL.OAuth callback URLs to register with each provider:

Provider	Callback URL
GitHub	`{API_PUBLIC_URL}/api/auth/github/callback`
Google	`{API_PUBLIC_URL}/api/auth/google/callback`
GitLab	`{API_PUBLIC_URL}/api/auth/gitlab/callback`

Encryption

encryption.*

Value	Type	Default	Description
`encryption.key`	string	`""`	Required. AES-256-GCM encryption key for secrets stored in the database (API keys, OAuth tokens, webhook secrets). Generate with: `openssl rand -hex 32`. Store this value securely — losing it means stored secrets cannot be decrypted.

The chart will not function without encryption.key. If the key changes between deployments, all previously stored secrets will be unreadable and will need to be re-entered.

GitHub webhook

webhook.*

Value	Type	Default	Description
`webhook.githubSecret`	string	`""`	Shared secret for validating GitHub webhook signatures. Must match the secret configured in your GitHub webhook settings. Generate with: `openssl rand -hex 32`.

Ingress

ingress.*

Value	Type	Default	Description
`ingress.enabled`	boolean	`false`	Create a Kubernetes Ingress resource. Required for production to expose the web UI and API externally.
`ingress.className`	string	`nginx`	Ingress class name. Matches the `kubernetes.io/ingress.class` annotation or `ingressClassName` field.
`ingress.annotations`	object	`{}`	Additional annotations added to the Ingress resource.
`ingress.certManager.enabled`	boolean	`false`	Automatically add the `cert-manager.io/cluster-issuer` annotation and generate TLS blocks for each host.
`ingress.certManager.clusterIssuer`	string	`letsencrypt-prod`	cert-manager `ClusterIssuer` name to use for certificate provisioning.
`ingress.hosts`	list	see below	List of host rules. Each entry has `host` and `paths`. Default paths route `/` to the web service and `/api` + `/ws` to the API service.
`ingress.tls`	list	`[]`	Manual TLS configuration. Only needed when `certManager.enabled=false`. Each entry has `secretName` and `hosts`.

Default host configuration:

ingress:
  hosts:
    - host: optio.example.com
      paths:
        - path: /
          pathType: Prefix
          service: web
        - path: /api
          pathType: Prefix
          service: api
        - path: /ws
          pathType: Prefix
          service: api

The /ws path must route to the API service — it is required for live log streaming and real-time event delivery.

Namespace, resource quotas, and service account

namespace / resourceQuota.* / serviceAccount.*

Value	Type	Default	Description
`namespace`	string	`optio`	Kubernetes namespace for all Optio resources.
`resourceQuota.enabled`	boolean	`false`	Apply a `ResourceQuota` to the namespace. Recommended for production to cap the resources that rogue or runaway agent pods can consume.
`resourceQuota.hard.requests.cpu`	string	`20`	Namespace-level CPU request limit.
`resourceQuota.hard.requests.memory`	string	`40Gi`	Namespace-level memory request limit.
`resourceQuota.hard.limits.cpu`	string	`40`	Namespace-level CPU usage limit.
`resourceQuota.hard.limits.memory`	string	`80Gi`	Namespace-level memory usage limit.
`resourceQuota.hard.pods`	string	`50`	Maximum number of pods allowed in the namespace.
`resourceQuota.hard.persistentvolumeclaims`	string	`30`	Maximum number of PVCs allowed in the namespace.
`serviceAccount.create`	boolean	`true`	Create a Kubernetes `ServiceAccount` for the API server. Required for pod management.
`serviceAccount.name`	string	`optio`	Name of the `ServiceAccount`.
`serviceAccount.annotations`	object	`{}`	Annotations on the `ServiceAccount`. Useful for IAM role binding (e.g. EKS IRSA).

Image pull secrets

imagePullSecrets

Value	Type	Default	Description
`imagePullSecrets`	list	`[]`	List of existing Kubernetes secrets of type `kubernetes.io/dockerconfigjson` to use when pulling images from private registries. Each entry must have a `name` key.

Example:

imagePullSecrets:
  - name: my-registry-secret

Create the secret with:

kubectl create secret docker-registry my-registry-secret \
  --docker-server=ghcr.io \
  --docker-username=your-username \
  --docker-password=your-token \
  -n optio

Example configurations

# Minimal production values file
# Pass with: helm install optio helm/optio -f production-values.yaml -n optio --create-namespace

encryption:
  key: "<output of: openssl rand -hex 32>"

postgresql:
  enabled: false

externalDatabase:
  url: "postgres://optio:password@your-db.example.com:5432/optio"

redis:
  enabled: false

externalRedis:
  url: "redis://your-redis.example.com:6379"

auth:
  github:
    clientId: "your-github-client-id"
    clientSecret: "your-github-client-secret"

agent:
  image:
    repository: ghcr.io/your-org/optio-agent-base
    tag: latest
  imagePullPolicy: IfNotPresent

ingress:
  enabled: true
  className: nginx
  certManager:
    enabled: true
    clusterIssuer: letsencrypt-prod
  hosts:
    - host: optio.example.com
      paths:
        - path: /
          pathType: Prefix
          service: web
        - path: /api
          pathType: Prefix
          service: api
        - path: /ws
          pathType: Prefix
          service: api

resourceQuota:
  enabled: true

Self-Hosting

Configuration

Helm Chart Reference

API server

Web UI

Agent containers

PostgreSQL

Redis

External database and Redis

Authentication

Encryption

GitHub webhook

Ingress

Namespace, resource quotas, and service account

Image pull secrets

Example configurations

Build docs developers (and LLMs) love

Self-Hosting

Configuration

Documentation Index

​API server

​Web UI

​Agent containers

​PostgreSQL

​Redis

​External database and Redis

​Authentication

​Encryption

​GitHub webhook

​Ingress

​Namespace, resource quotas, and service account

​Image pull secrets

​Example configurations

Build docs developers (and LLMs) love

API server

Web UI

Agent containers

PostgreSQL

Redis

External database and Redis

Authentication

Encryption

GitHub webhook

Ingress

Namespace, resource quotas, and service account

Image pull secrets

Example configurations