Getting Started

Optio is a self-hosted platform for running AI agents as sessions — on your Kubernetes cluster or on your own machines — and wiring them into workflows and swarms. A session is one noun with five attributes: When it starts, Where it runs, Who does the work, What it is asked to do, and Then what happens after. The classic shape — a ticket becomes a merged PR, with Optio provisioning an isolated environment, running the agent, watching CI, handling review, and merging — is one point in that space. Scheduled jobs, webhook responders, laptop automations, interactive terminals, and persistent multi-agent systems are the others.

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 Session

From the dashboard, connect a GitHub repository, then create a session that opens a PR:

  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 Sessions → New session and pick the Open a PR preset
  4. Answer When (now), Where (an Optio pod with your repo), Who (Claude Code), What (your prompt), Then (exits when done) — the form reads it back as a sentence — 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 session detail view, and it shows up under Active in the Sessions feed. Try the other presets next: Interactive chat, Scheduled run, and Persistent agent.

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

Work

The five attributes and the kinds they derive

Architecture

How the system works under the hood

Configuration

Environment variables and Helm values

Task Lifecycle

States, transitions, and the feedback loop