jonwiggins/optio

Optio – Self‑hosted AI‑agent orchestration platform

What it is – Optio is an open‑source control‑plane that lets you run AI‑powered agents (Claude Code, OpenAI Codex, GitHub Copilot, Gemini, etc.) as sessions on your own Kubernetes cluster or on a developer’s laptop. A session is defined by five simple attributes (When, Where, Who, What, Then) and can be anything from a one‑shot “turn a ticket into a merged PR” workflow to a long‑living, message‑driven swarm of agents.

Why it matters – Most commercial “AI‑agent” services are SaaS‑only, lock you into a single model, and require you to ship source code and secrets to a third‑party cloud. Optio puts the orchestration layer inside your infrastructure, gives you a single UI/API to schedule, trigger, and monitor all agent work, and lets you mix‑and‑match any vendor model you trust.

Core concepts

Concept	Explanation
Session	A durable, observable unit of work that is created via a single form. The form captures When (trigger), Where (K8s pod or local machine), Who (which model/runtime), What (prompt or template), and Then (exit, wait, or persist).
Feed	All sessions appear in one chronological feed with a unified status scale (needs‑you → running → queued → … → done/failed).
Reconciliation control plane	A Kubernetes‑style loop that decides the next state for every session based on a frozen snapshot of the world, applying changes with compare‑and‑swap to guarantee no stuck runs.
Persistent agents & swarms	Named agents that keep state between turns, have an inbox, and can message each other over an internal HTTP API. Useful for dispatcher‑specialist patterns.
Connections (MCP)	Pre‑configured integrations (Notion, Slack, Linear, GitHub, PostgreSQL, Sentry, custom HTTP APIs, etc.) that are injected into a pod at start, giving agents safe, scoped access to external tools.

What you can do today

• Ticket → merged PR – Assign a GitHub/Linear/Jira issue; Optio provisions a repo pod, runs the chosen model, opens a PR, watches CI, runs a review agent, and auto‑merges when green.
• Scheduled / webhook jobs – Nightly dependency audits, PagerDuty triage, weekly Slack reports, DB‑to‑Notion queries, all driven by cron or incoming webhooks.
• Recurring blueprints – Save a session as a blueprint and have it fire automatically on each trigger payload.
• Local automations – Run agents on a developer’s workstation (using their own CLI login) for events like GitHub review requests or Slack mentions; secrets never leave the machine.
• Interactive terminals – Open a model‑backed terminal in the browser or iOS app, get real‑time logs, and receive “needs‑you” notifications when the model pauses for input.
• Agent swarms – Deploy a dispatcher agent that routes work to specialist agents, each running in its own pod lifecycle mode (always‑on, sticky, on‑demand).
• Cost & usage tracking – Per‑session token usage, model‑specific limits, and daily cost breakdowns are shown in the UI.

Architecture at a glance

• Control plane – Pure decision functions (deriveKind) that map the five attributes to a concrete runtime (repo pod, pooled pod, or local terminal). State changes flow through a K8s‑style reconciler with CAS updates and periodic resync.
• Pod‑per‑repo model – One long‑lived pod per repository holds a git worktree; multiple sessions share the same clone, reducing start‑up time and caching tools.
• Job pods – Shared pooled pods for sessions that don’t need a repo (e.g., audits, reports).
• Local daemon – optio local runs a lightweight daemon on a workstation, exposing a WebSocket to the server so triggers can launch terminal‑based agents.
• Persistence – PostgreSQL stores session metadata, cost ledger, and RBAC definitions; Redis is used for short‑lived queues and agent inboxes.
• Security – AES‑256‑GCM encrypted secrets at rest, OIDC/OAuth and GitHub‑App authentication, Kubernetes RBAC enforcement, and optional post‑quantum‑ready TLS.

Who should consider Optio?

• Organizations that cannot send code or data to external SaaS (finance, healthcare, government, defense).
• Platform teams that want a single internal “AI‑tooling” layer to expose prompts, policies, and connections to developers.
• Teams already running Kubernetes and looking for a drop‑in Helm chart.
• Companies evaluating multiple LLM vendors or building multi‑agent systems.
• Developers who want the same agent experience on a laptop, in the cluster, and on a mobile device.

Getting started

1. Install – Deploy via the provided Helm chart (requires a K8s cluster, Postgres, Redis). Optionally run optio local on a workstation.
2. Configure connections – Add your GitHub, Slack, Notion, etc., credentials once.
3. Create a session – Use the web UI or CLI to fill the single form (When/Where/Who/What/Then).
4. Watch – The feed shows live logs, cost, and status; interactive sessions can be taken over from any browser or the iOS app.

---

TL;DR – Optio is an open‑source, self‑hosted platform that lets you run, schedule, and monitor AI‑agent workloads (PR bots, scheduled jobs, interactive terminals, persistent swarms) on your own Kubernetes cluster or laptops, while keeping code, secrets, and model choice under your control.