optio

Optio is an open-source AI engineering platform that orchestrates AI coding agent swarms entirely within your own Kubernetes cluster. Unlike hosted alternatives such as Devin or Cursor background agents, Optio keeps your source code, secrets, and agent logs inside your own network while giving you full control over which AI model powers each task.

The platform organizes agent work into three tiers. Tasks represent the full ticket-to-PR lifecycle — Optio provisions an isolated pod, runs an AI agent, monitors CI, automatically resumes the agent on failures or review requests, and squash-merges the PR when everything passes. Jobs are reusable, parameterized agent runs with no repository checkout, ideal for operational work like generating reports, triaging alerts, or querying databases. Persistent Agents are long-lived, message-driven processes that wake on user messages, inter-agent messages, webhooks, cron ticks, or ticket events — enabling multi-agent team setups.

At its core, Optio is built around a Kubernetes-style reconciliation control plane: a pure-decision-plus-CAS-executor loop that reads a WorldSnapshot, derives a single Action, and applies it with a compare-and-swap guard on the database timestamp. This architecture keeps task runs from getting stuck on lost events and makes every state transition auditable. All agent execution happens in ephemeral Kubernetes pods with configurable security contexts, RBAC, and encrypted secrets at rest using AES-256-GCM.

Optio supports multiple AI agent backends — Claude Code, OpenAI Codex, GitHub Copilot, Google Gemini, and OpenCode — behind a single unified interface, letting engineering teams switch models per repository or A/B test agents on the same task. The Connections system lets you inject external services (Notion, Linear, Jira, Slack, PostgreSQL, Sentry, or any MCP-compatible server) into agent pods at runtime with fine-grained access control.

What You Get

• Full ticket-to-PR automation with autonomous CI retry and review-feedback loops that run entirely inside your Kubernetes cluster
• Three-tier execution model: Tasks (PR lifecycle), Jobs (ops/automation without git checkout), and Persistent Agents (long-lived message-driven services)
• Multi-vendor AI agent support with Claude Code, OpenAI Codex, GitHub Copilot, Google Gemini, and OpenCode switchable per repository or per task
• Kubernetes-style reconciliation control plane using a pure-decision-plus-CAS-executor loop to prevent stale-state overwrite and ensure runs never get stuck
• Connections system to inject Notion, Linear, Jira, Slack, PostgreSQL, Sentry, or any MCP-compatible server into agent pods at runtime
• AES-256-GCM encrypted secrets at rest, OIDC/OAuth, Kubernetes RBAC, and full audit-friendly task history built in from day one
• Inter-agent messaging API enabling multi-agent team setups where Persistent Agents address and coordinate with each other
• Real-time log streaming and cost tracking dashboard with per-task token usage, PR status, and pipeline stage visibility

Common Use Cases

• Engineering teams in regulated industries (finance, healthcare, defense) that cannot send source code or secrets to a third-party SaaS AI platform
• Platform engineering teams building internal AI tooling on top of an existing Kubernetes cluster, Postgres, and Redis stack
• Multi-agent workflows where a Triage Agent routes incoming issues, a Forge Agent implements fixes, and a Review Agent validates PRs — all communicating via Optio’s inter-agent messaging
• On-call automation where webhook events from Sentry or PagerDuty trigger Jobs that query logs, draft incident summaries, and post to Slack without any manual intervention
• A/B testing different AI coding agents (Claude vs Codex vs Copilot) on the same repositories to measure PR merge rate, CI pass rate, and cost
• Scheduled dependency audits or security scans run as parameterized Jobs on a cron schedule, with results pushed to a Notion database via the Connections system

Under The Hood

Architecture Optio is a modular monorepo (Turborepo + pnpm workspaces) with four apps — api, web, cli, and site — and four shared packages: agent-adapters, container-runtime, shared (types, reconcile logic, prompt templates), and ticket-providers. The API (Fastify 5, TypeScript ESM) is the central control plane; it owns the reconciliation loop, BullMQ workers, WebSocket log streaming, and the OpenAPI surface. The core architectural primitive is a pure-decision-plus-CAS-executor pattern: reconcile-repo.ts, reconcile-standalone.ts, and reconcile-persistent-agent.ts in the shared package are pure functions that take a WorldSnapshot and return a single Action with no I/O. The reconcile-executor.ts in the API then applies that action to the database using a compare-and-swap guard on updated_at, preventing stale-snapshot overwrites in concurrent worker scenarios. State fans out through task-service.transitionTask, which fires webhooks, Slack notifications, and dependency cascades in a single coordinated call.

Tech Stack The API is built on Fastify 5 with fastify-type-provider-zod for end-to-end typed request/response validation, Drizzle ORM over PostgreSQL for schema and migrations, BullMQ over Redis for the task and worker queues, and the official @kubernetes/client-node SDK for pod lifecycle management. Agent adapters for Claude Code, OpenAI Codex, GitHub Copilot, Google Gemini, and OpenCode are implemented as adapter classes in the agent-adapters package, each compiling the right container environment and command for the target agent binary. Observability is comprehensive: OpenTelemetry auto-instrumentation with OTLP exporters for traces, metrics (Prometheus endpoint), and structured logs (Pino), plus a dedicated tls-observability service for certificate monitoring. The frontend is Next.js/React with Tailwind CSS. Helm charts target Kubernetes ≥1.33.

Code Quality The codebase has extensive test coverage — 185 test files across *.test.ts and *.test.tsx throughout the monorepo, with nearly every route, service, worker, and adapter paired with a corresponding test file using Vitest. Error handling is typed and explicit: StateRaceError, InvalidTransitionError, and typed ExecuteOutcome variants (applied | stale | skipped | error) ensure that callers handle every outcome. The reconciler’s pure-function design makes state logic independently testable without any database or Kubernetes dependency. Naming is highly consistent — every service, route, and worker follows a {noun}-{role}.ts pattern. ESLint, TypeScript strict mode, commitlint, Prettier, husky pre-commit hooks, and a CI workflow enforce style and type safety at every commit.

What Makes It Unique Optio’s most distinctive design choice is applying Kubernetes-style level-triggered reconciliation — normally used for infrastructure operators — to software development workflows. Rather than an event-driven pipeline where a missed webhook leaves a task stuck, Optio’s reconciler continuously re-derives the correct action from observed world state, making it naturally resilient to network failures, worker restarts, and lost events. The three-tier execution model (Tasks / Jobs / Persistent Agents) on a shared reconciler and trigger engine is also uncommon: most agent platforms are PR-centric, while Optio treats operational automation (Jobs) and long-lived agent services (Persistent Agents) as first-class primitives. The multi-vendor adapter architecture with per-repo model switching, combined with the Connections MCP injection system, gives teams genuine model independence without sacrificing the unified control plane.

Self-Hosting

Licensing Model MIT licensed — all features available in self-hosted deployments with no restrictions or license keys required.

Self-Hosting Optio is designed specifically for self-hosting on Kubernetes (GKE, EKS, AKS, or any conformant cluster). A Helm chart is provided targeting Kubernetes ≥1.33. You supply your own PostgreSQL and Redis instances. No cloud account, license key, or phone-home is required.