Connecting Repos

Before you can create tasks, you need to connect at least one repository. Optio supports any Git repository accessible via HTTPS. Each repository gets its own configuration for agent behavior, concurrency limits, and review settings.

Adding a Repository

Navigate to Repos in the sidebar
Click Add Repository
Enter the repository URL (e.g., https://github.com/acme/webapp)
Optio auto-detects the language, default branch, and suggests an image preset
Confirm the settings and connect

Info

A GITHUB_TOKEN secret is required for private repositories and for auto-detection features. Add it in Secrets before connecting private repos.

Via the API

POST /api/repos

{
  "repoUrl": "https://github.com/acme/webapp",
  "imagePreset": "node",
  "defaultBranch": "main"
}

Auto-Detection

When you add a repo, Optio queries the GitHub API for root-level files and automatically detects the language and tooling:

Detected File	Image Preset	Test Command
package.json	node	npm test
Cargo.toml	rust	cargo test
go.mod	go	go test ./...
pyproject.toml / setup.py / requirements.txt	python	pytest
Multiple languages	full	(varies)

You can always override the auto-detected preset and test command in the repo settings.

Image Presets

Image presets determine the Docker image used for the repo pod. Each preset comes with the appropriate language runtime and tooling pre-installed.

Preset	Includes
base	Git, common CLI tools, Claude Code
node	Base + Node.js, npm, pnpm, yarn
python	Base + Python, pip, poetry, uv
go	Base + Go toolchain
rust	Base + Rust, cargo, rustup
full	All language runtimes combined

Tip

Use the most specific preset for your repo. The full preset works for polyglot repos but produces a larger image and slower pod startup.

Custom Setup Scripts

If your repo needs custom setup beyond the image preset (e.g., installing system packages, configuring environment variables, or running a build step), add an .optio/setup.sh file to your repository root. This script runs automatically when the repo pod is first created, after the clone completes.

.optio/setup.sh

#!/bin/bash
# Install project dependencies
npm install

# Build shared packages
npm run build:packages

# Install additional system tools
apt-get update && apt-get install -y jq

Per-Repo Settings

Each repository has a comprehensive settings page accessible from Repos → (select repo) → Settings.

Concurrency

Setting	Default	Description
maxConcurrentTasks	2	Maximum concurrent tasks for this repo
maxPodInstances	1	Maximum pod replicas (1-20). Each gets its own PVC
maxAgentsPerPod	2	Maximum concurrent agents per pod instance (1-50)

Total capacity = maxPodInstances × maxAgentsPerPod. When all pods are at capacity and under the instance limit, Optio dynamically creates a new pod. Higher-index pods are removed first when idle (LIFO scaling).

Agent Behavior

Setting	Description
claudeModel	Model for coding tasks (sonnet, opus, haiku)
claudeContextWindow	Context window override (null = model default)
claudeThinking	Enable extended thinking mode for more complex reasoning
claudeEffort	Agent effort level override
maxTurnsCoding	Limit agent turns for coding tasks (controls cost)
maxTurnsReview	Limit agent turns for review tasks
autoMerge	Auto-merge PRs when CI passes and review is approved
autoResume	Auto-resume agent when reviewer requests changes

Prompt Template Override

Each repo can override the global prompt template. This is useful for repos with specific conventions, testing requirements, or architectural constraints.

example repo prompt override

Read the task description from {{TASK_FILE}}.

This is a Next.js 15 project using the App Router. Follow these conventions:
- Server Components by default, "use client" only when needed
- All data fetching in Server Components
- Use the existing design system in src/components/ui/
- Run "pnpm turbo typecheck" before opening the PR
- Include tests in __tests__/ directories

Create a branch named "{{BRANCH_NAME}}" and open a PR when done.

Repository URL Normalization

Optio normalizes all repository URLs to a canonical HTTPS form for consistent matching. The following formats all resolve to the same repo:

https://github.com/acme/webapp
https://github.com/acme/webapp.git
git@github.com:acme/webapp.git
ssh://git@github.com/acme/webapp

Pod Lifecycle

Understanding how repo pods work helps with troubleshooting:

Creation — When the first task arrives for a repo, a pod is created, the repo is cloned, and .optio/setup.sh runs if present
Reuse — Subsequent tasks reuse the existing pod. The repo is already cloned and dependencies installed
Persistence — Pods use persistent volumes, so installed tools and caches survive pod restarts
Idle cleanup — Pods idle for 10 minutes (configurable) before being removed
Health monitoring — The cleanup worker detects crashed or OOM-killed pods, fails associated tasks, and deletes the dead pod record so the next task recreates it

Next Steps

Creating Tasks

Create tasks from UI, issues, or API

Review Agents

Set up automated code review

Configuration

All environment variables and settings

Architecture

Pod-per-repo design and scaling