Getting Started

Optio is a workflow orchestration system for AI coding agents. Think of it as "CI/CD where the build step is an AI agent." You submit tasks — from GitHub Issues, Linear tickets, or manually — and Optio handles the full lifecycle: provisioning an isolated environment, running the agent, opening a PR, monitoring CI, handling code review, and merging when everything passes.

Quick Start

The fastest way to try Optio is with Docker Desktop's built-in Kubernetes. The setup script handles everything: building images, installing dependencies, and deploying via Helm.

Prerequisites

  • Docker Desktop with Kubernetes enabled
  • Node.js 22+
  • pnpm 10+
  • Helm 3+
  • kubectl

Setup

terminal
git clone https://github.com/jonwiggins/optio.git
cd optio
./scripts/setup-local.sh

The script builds all container images (API, web, agent presets), installs the Helm chart, and starts the services. This takes a few minutes on first run.

Info

Auth is disabled by default in local development. You'll be logged in as a synthetic "Local Dev" user automatically.

Access the Dashboard

Once setup completes, open:

  • Dashboard: http://localhost:30310
  • API: http://localhost:30400

First Task

From the dashboard, connect a GitHub repository, then create a task:

  1. Go to Repos and add a repository
  2. Configure your API keys in Secrets (Anthropic API key or Claude OAuth token)
  3. Go to Tasks → New Task
  4. Select your repo, write a prompt, and submit

Optio will provision a pod, create a worktree, run the agent, and open a PR. You can watch the live logs in the task detail view.

What Happens Next

Once the PR is opened, the feedback loop kicks in. Optio polls the PR every 30 seconds:

  • CI fails — the agent is resumed with the failure context
  • Review requests changes — the agent picks up the review comments
  • CI passes + approved — the PR is squash-merged and the issue is closed

Next Steps

Installation

Full installation guide for local and production

Architecture

How the system works under the hood

Configuration

Environment variables and Helm values

Task Lifecycle

States, transitions, and the feedback loop