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.

Optio runs each AI agent inside a Docker container in Kubernetes. When a task starts, Optio provisions a pod for the repository, clones the code, and runs the agent process inside that pod. The container image you choose for a repository determines which languages and tools are available to the agent.

​
Image presets

Optio ships six presets. All presets include Claude Code, the GitHub CLI (gh), git, curl, wget, jq, and common Unix utilities. All run as a non-root agent user on Ubuntu 24.04.
Image: optio-base:latestThe foundation for all other presets. Use this for repositories that don’t need a specific language runtime, or as a starting point for custom images.Includes:
  • Ubuntu 24.04
  • git, curl, wget, jq, unzip, openssh-client
  • GitHub CLI (gh)
  • Node.js 22 (required by Claude Code)
  • pnpm 10 (via corepack)
  • Python 3 (minimal, for internal tooling)
  • Claude Code (@anthropic-ai/claude-code)

​
Auto-detection

When you add a repository to Optio, it inspects the repository’s root-level files via the GitHub API and automatically selects the most appropriate preset:
Root fileSelected preset
package.jsonnode
go.modgo
Cargo.tomlrust
pyproject.toml, setup.py, or requirements.txtpython
Multiple language markersfull
None of the abovebase
You can override the auto-detected preset at any time from the repository settings page.

​
Building the images

For local development or self-hosted deployments, build all presets with the included script: 
./images/build.sh
This builds optio-base first (since the other images depend on it), then builds optio-node, optio-python, optio-go, and optio-rust in parallel, and finally builds optio-full. It also tags optio-base:latest as optio-agent:latest as the default fallback. For production deployments, push the built images to a container registry and set the pull policy accordingly:
values.yaml
agent:
  image:
    repository: ghcr.io/your-org/optio-agent-node
    tag: latest
    pullPolicy: IfNotPresent

​
Custom images

You can specify any Docker image per repository from the repository settings page. The image must include Claude Code (@anthropic-ai/claude-code) and a compatible entrypoint. For most cases, the recommended approach is to build from one of the official presets as a base: 
FROM optio-node:latest

USER root
# Install additional tools
RUN apt-get update && apt-get install -y <your-tools> && rm -rf /var/lib/apt/lists/*

USER agent

​
Repository setup script

For per-repository customization, create a .optio/setup.sh file in the root of the repository. Optio runs this script inside the pod after cloning the repository, before any tasks start. Use this for steps that are specific to the project — for example, installing dependencies or configuring environment-specific files:
.optio/setup.sh
#!/bin/bash
set -euo pipefail

# Install dependencies on pod startup so they are available for all tasks
npm ci
Because pods use a persistent volume, tools and packages installed by setup.sh survive pod restarts and are available to every subsequent task without re-installation.

​
Persistent volumes

Each repository pod is backed by a Kubernetes PersistentVolumeClaim (PVC). The default size is 10Gi. This means:
  • The repository clone persists between tasks — no re-cloning on each task.
  • Dependencies installed by setup.sh or by the agent persist across pod restarts.
  • Each pod instance gets its own PVC. If a repository is scaled to multiple pod instances, each instance has an independent volume.
To change the default PVC size:
values.yaml
agent:
  pvc:
    size: 20Gi
    storageClass: ""  # Leave empty to use the cluster default

Build docs developers (and LLMs) love

Get started for freeTalk to us