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.

Optio is entirely self-hosted. There is no SaaS option — you deploy it to a Kubernetes cluster you control. All components (API server, web UI, agent pods, PostgreSQL, Redis) run inside that cluster and are deployed via the included Helm chart.

​
Deployment modes

Local

Docker Desktop with Kubernetes enabled. One command to get running. Best for trying Optio out or for individual use on a single machine.

Production

Any Kubernetes cluster with managed PostgreSQL and Redis. Intended for teams sharing a deployment.

​
Architecture

Every component runs inside Kubernetes:
ComponentDefault portNotes
Web UI (Next.js):3000 (internal)Exposed via NodePort or Ingress
API server (Fastify):4000 (internal)Exposed via NodePort or Ingress
Agent podsdynamicProvisioned on-demand by the API server in the same namespace
PostgreSQL:5432 (internal)Can be replaced with a managed database
Redis:6379 (internal)Can be replaced with managed Redis
The API server manages the full agent lifecycle — it provisions Kubernetes pods per repository, execs tasks into those pods, streams logs back to the web UI over WebSocket, and watches pull requests for CI and review status. 
┌──────────────┐     ┌────────────────────┐     ┌───────────────────────────┐
│   Web UI     │────→│    API Server      │────→│      Kubernetes           │
│   Next.js    │     │    Fastify         │     │                           │
│   :3000      │←ws──│                   │     │  ┌── Repo Pod ──────────┐  │
│              │     │  Task queue        │     │  │ clone + sleep        │  │
│              │     │  PR watcher        │     │  │ ├─ worktree 1  ⚡    │  │
│              │     │  Health monitor    │     │  │ └─ worktree 2  ⚡    │  │
└──────────────┘     └─────────┬──────────┘     │  └──────────────────────┘  │
                               │                └───────────────────────────┘
                        ┌──────┴──────┐
                        │  Postgres   │
                        │  Redis      │
                        └─────────────┘
All three components — API server, web UI, and agent pods — are containerized and deployed via the same Helm chart. The API and web images are built from the repository root. Agent images are built from images/ and pushed to a registry (or loaded locally for development).

​
What runs where

API server — the control plane. Runs as a Kubernetes Deployment (optio-api). Manages task state, orchestrates pods, streams logs, watches PRs, and runs all BullMQ workers. Web UI — the dashboard. Runs as a Kubernetes Deployment (optio-web). A Next.js app that communicates with the API over HTTP and WebSocket. Agent pods — dynamically provisioned. The API server creates one long-lived pod per repository in the optio namespace. When a task runs, the API execs into the pod and runs the agent in an isolated git worktree. Pods are cleaned up after 10 minutes of idle time.

​
Prerequisites by mode

  • Docker Desktop with Kubernetes enabled (Settings → Kubernetes → Enable Kubernetes)
  • Node.js 22+ and pnpm 10+
  • Helm (brew install helm)
The ./scripts/setup-local.sh script checks for these automatically and prints a clear error if anything is missing.
  • A Kubernetes cluster (EKS, GKE, AKS, or any conformant cluster)
  • Helm 3+
  • A managed PostgreSQL instance (e.g. RDS, Cloud SQL, Supabase)
  • A managed Redis instance (e.g. ElastiCache, Upstash, Redis Cloud)
  • A container registry to host agent images
  • At least one OAuth provider configured (GitHub, Google, or GitLab)
  • metrics-server installed in the cluster

​
Next steps

Local deployment

Run Optio on Docker Desktop with one command.

Production deployment

Deploy to a Kubernetes cluster for your team.

Helm chart reference

Full reference for all Helm values.

Build docs developers (and LLMs) love

Get started for freeTalk to us