Getting Started

Optio is a self-hosted platform for running AI agents as work — on your Kubernetes cluster or on your own machines — and connecting them to schedules, events, and other agents. Each piece of work has 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

Your First Work

From the dashboard, connect a GitHub repository, then create work 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 Work → New work 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 work detail view, and it shows up under Active in the Work feed. Try the other presets next: Interactive chat, Scheduled run, and Persistent agent.

What Happens Next

Once the PR is opened, Optio follows its CI, review, and merge status. Enable automatic review, resuming, or merging when those behaviors fit your workflow:

  • CI fails — the agent is resumed with the failure context when automatic resuming is enabled
  • Review requests changes — the agent picks up the review comments when automatic resuming is enabled
  • CI passes + approved — the PR is eligible for automatic merging when configured; linked issues can be closed on completion

Next Steps