Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/jonwiggins/optio/llms.txt

Use this file to discover all available pages before exploring further.

​
Secrets management

Optio provides a built-in secrets store for values that agents need at runtime — such as API keys and tokens. Secrets are managed through the Secrets page in the UI. Encryption: All secret values are encrypted at rest using AES-256-GCM. The encryption key is set via encryption.key in Helm values (or the OPTIO_ENCRYPTION_KEY environment variable) and must be generated before the first install: 
openssl rand -hex 32
The encryption key cannot be changed without invalidating all stored secrets. If you rotate the key, every secret must be re-entered. Store the key securely and back it up — losing it means losing access to all encrypted secrets.
API behavior: Secret values are never returned by the API. The GET /api/secrets endpoint returns only secret names and scopes. This means secrets cannot be read back through the UI or API after they are stored. Scope: Secrets are workspace-scoped. Each workspace has its own isolated secrets store. Common secrets to store:
Secret namePurpose
ANTHROPIC_API_KEYAnthropic API key for Claude Code (API key auth mode)
CLAUDE_CODE_OAUTH_TOKENClaude Max/Pro OAuth token (OAuth token auth mode)
GITHUB_TOKENGitHub personal access token for PR watching and issue sync

​
Agent isolation

Each task runs in an isolated environment within a Kubernetes pod:
  • Pod-per-repo: A single long-lived pod is created per repository. Tasks run in separate git worktrees within that pod, keeping them isolated from each other’s working trees.
  • Worktree isolation: Each task gets its own git worktree at /workspace/tasks/{taskId}. Worktrees are created before the agent starts and removed after it finishes.
  • Non-root user: Agent processes run as the non-root agent user inside the container.
  • Namespace-scoped RBAC: The Optio service account has a namespace-scoped Kubernetes Role granting access only to pods, exec, secrets, PVCs, services, and events within the optio namespace. A ClusterRole is used only for read access to nodes, namespaces, and metrics.

​
Resource quotas

Resource quotas are disabled by default. Enabling them is recommended for production deployments to prevent runaway agents from consuming all cluster resources.
You can enable a Kubernetes ResourceQuota on the optio namespace to cap total resource consumption across all agent pods:
values.yaml
resourceQuota:
  enabled: true
  hard:
    requests.cpu: "20"
    requests.memory: 40Gi
    limits.cpu: "40"
    limits.memory: 80Gi
    pods: "50"
    persistentvolumeclaims: "30"
Adjust these limits based on the size of your cluster and the number of concurrent agents you expect to run.

​
Access control

Optio uses multi-tenant workspaces with role-based access control. Authentication: All users authenticate via OAuth (GitHub, Google, or GitLab). There are no local username/password accounts. Workspace roles:
RoleDescription
adminFull access to workspace settings, members, secrets, and all resources
memberCan create and manage tasks, repositories, and sessions
viewerRead-only access to tasks and logs
Workspace members and their roles are managed from the Workspace Settings page.

​
Production hardening checklist

1

Disable the auth bypass

Ensure OPTIO_AUTH_DISABLED is not set, or is explicitly set to false. In Helm values, confirm auth.disabled: false.
2

Enable TLS

Configure the Ingress with TLS. The Helm chart supports cert-manager for automatic certificate provisioning:
values.yaml
ingress:
  enabled: true
  certManager:
    enabled: true
    clusterIssuer: letsencrypt-prod
  hosts:
    - host: optio.example.com
      paths:
        - path: /
          pathType: Prefix
          service: web
        - path: /api
          pathType: Prefix
          service: api
3

Use managed PostgreSQL and Redis

Replace the bundled in-cluster deployments with managed services to ensure persistence and high availability:
values.yaml
postgresql:
  enabled: false
externalDatabase:
  url: "postgres://user:pass@your-managed-host:5432/optio"

redis:
  enabled: false
externalRedis:
  url: "redis://your-managed-host:6379"
4

Generate and securely store the encryption key

Generate the encryption key before first install and store it in a secrets manager:
openssl rand -hex 32
Set it via encryption.key in Helm values. Do not commit it to source control.
5

Enable resource quotas

Add a ResourceQuota on the optio namespace to limit cluster consumption by agent pods. See Resource quotas above.
6

Configure agent image pull policy

For production, images should be pushed to a registry and pulled with IfNotPresent or Always rather than using locally built images with Never:
values.yaml
agent:
  imagePullPolicy: IfNotPresent
7

Set API_PUBLIC_URL and WEB_PUBLIC_URL

These must match the actual public URLs of your deployment. OAuth callbacks will fail if they point to the wrong host.
8

Configure at least one OAuth provider

At least one of GitHub, Google, or GitLab OAuth must be configured so users can log in. See Authentication.

Build docs developers (and LLMs) love

Get started for freeTalk to us