Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/jonwiggins/optio/llms.txt

Use this file to discover all available pages before exploring further.

This guide gets you from zero to a running Optio instance with your first task completed. Optio runs entirely on your local Kubernetes cluster — no external services required to get started.

​
Prerequisites

Before you begin, make sure you have the following installed:
  • Docker Desktop with Kubernetes enabled — go to Settings → Kubernetes → Enable Kubernetes
  • Node.js 22+ and pnpm 10+
  • Helm — install with brew install helm on macOS
Kubernetes must be running before you start. Verify with kubectl cluster-info. If you see a connection error, open Docker Desktop and confirm Kubernetes is enabled and the status indicator is green.

​
Setup

1

Clone the repository and run the setup script

Clone Optio and run the one-command setup script:
git clone https://github.com/jonwiggins/optio.git && cd optio
./scripts/setup-local.sh
The setup script handles everything in sequence:
  1. Installs Node.js dependencies with pnpm install
  2. Builds all agent Docker images (optio-base, optio-node, optio-python, optio-go, optio-rust, optio-full)
  3. Builds the API and web Docker images
  4. Installs metrics-server into your cluster for resource usage display
  5. Deploys the full stack to the optio namespace via Helm
This takes a few minutes on first run — mostly image build time. When it completes, you’ll see:
=== Setup Complete ===

Services:
  Web UI ...... http://localhost:30310
  API ......... http://localhost:30400
2

Open the web UI

Open http://localhost:30310 in your browser.
The local setup disables authentication by default, so you’ll be signed in automatically as a local dev user. No login is required.
If the page doesn’t load immediately, wait 10–15 seconds for the pods to finish starting. You can check pod status with:
kubectl get pods -n optio
All pods should show Running before proceeding.
3

Complete the setup wizard

The first time you open the UI, Optio redirects you to the setup wizard at /setup. The wizard walks you through three configuration steps:1. GitHub access — paste a GitHub personal access token with repo scope. This is used to clone repositories, open PRs, poll CI status, and close issues.2. Agent credentials — choose how to authenticate with your AI agent:
  • API key — paste your ANTHROPIC_API_KEY or OpenAI API key. Simple pay-per-use.
  • OAuth token — for Claude Max or Pro subscribers. Run the one-liner shown in the wizard to extract your token from the macOS Keychain, then paste it. This gives Optio access to your subscription.
3. Add your first repository — paste the GitHub URL of a repository you want Optio to work on. Optio detects the language and selects the appropriate agent image automatically (Node, Python, Go, Rust, or full).
Start with a low-stakes repository — a personal project or a repo with a good test suite. This makes it easy to verify that the agent’s output is correct before enabling auto-merge.
4

Create your first task and watch it run

Once setup is complete, go to Tasks → New Task.Fill in:
  • Title — a short description of what to do (e.g., “Add input validation to the signup form”)
  • Repository — select the repo you just added
  • Description — a clear explanation of the change you want. The more context you provide, the better the agent’s output.
Click Create Task. Optio queues the task immediately.You’ll be taken to the task detail page where you can watch:
  • The pipeline progress bar moving through Queued → Provisioning → Running → PR Opened
  • Live agent logs streaming in real time
  • The PR URL appearing as soon as the agent opens one
Once a PR is open, Optio’s PR watcher takes over — polling GitHub every 30 seconds for CI status and review state.

​
Updating

To pull the latest code and redeploy: 
./scripts/update-local.sh
This pulls the latest commits, rebuilds the API and web images, applies any Helm chart changes, and rolling-restarts the deployments.

​
Teardown

To remove Optio from your cluster entirely: 
helm uninstall optio -n optio

​
Next steps

How It Works

Understand the full task lifecycle and feedback loop in detail.

Managing Tasks

Learn how to prioritize tasks, retry failures, and use bulk operations.

Repository configuration

Configure per-repo model, prompt template, concurrency, and container image.

GitHub & Linear

Assign GitHub Issues and Linear tickets directly to Optio.

Build docs developers (and LLMs) love

Get started for freeTalk to us