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.

Local deployment uses Docker Desktop’s built-in Kubernetes cluster. It is designed for trying Optio out or running it for individual use on a single machine. The setup script handles everything from building Docker images to deploying via Helm.

​
Prerequisites

  • Docker Desktop with Kubernetes enabled Settings → Kubernetes → Enable Kubernetes
  • Node.js 22+ (node --version should print v22.x.x or higher)
  • pnpm 10+ (npm install -g pnpm)
  • Helm (brew install helm)
Kubernetes must be running in Docker Desktop before you run the setup script. The script checks for cluster connectivity and exits immediately if no cluster is found.

​
Setup

1

Clone the repository

git clone https://github.com/jonwiggins/optio.git
cd optio
2

Run the setup script

./scripts/setup-local.sh
The script runs six steps automatically:
  1. Installs pnpm dependencies
  2. Builds all agent images in parallel (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 the kube-system namespace (required for resource usage display)
  5. Deploys the full stack to the optio namespace via Helm
  6. Waits for the API and web deployments to become available
The script prints progress for each step and exits with a clear error message if a prerequisite is missing.
3

Open the setup wizard

When setup completes, both services are available:
ServiceURL
Web UIhttp://localhost:30310
APIhttp://localhost:30400
Open the web UI and the setup wizard will walk you through:
  • Configuring GitHub access (GITHUB_TOKEN)
  • Setting up agent credentials (Anthropic API key, Claude OAuth token, or OpenAI API key)
  • Adding your first repository

​
What the Helm deployment configures

The setup script deploys Helm with these local dev settings: 
helm install optio helm/optio -n optio --create-namespace \
  --set encryption.key=$(openssl rand -hex 32) \
  --set api.image.pullPolicy=Never \
  --set web.image.pullPolicy=Never \
  --set agent.image.repository=optio-base \
  --set agent.image.tag=latest \
  --set agent.imagePullPolicy=Never \
  --set auth.disabled=true \
  --set api.service.type=NodePort \
  --set api.service.nodePort=30400 \
  --set web.service.type=NodePort \
  --set web.service.nodePort=30310 \
  --set postgresql.auth.password=optio_dev
agent.imagePullPolicy=Never tells Kubernetes to only use images already present in the local containerd image store. Never change this to Always for local development — it will cause pods to fail because the images are not in any remote registry.
Authentication is disabled (auth.disabled=true) for convenience in local development. The web UI will log you in automatically as a synthetic “Local Dev” user.

​
Updating

To pull the latest code and redeploy: 
./scripts/update-local.sh
This script:
  1. Runs git pull --rebase
  2. Reinstalls pnpm dependencies
  3. Rebuilds optio-api and optio-web images (and any agent images that are missing)
  4. Runs helm upgrade with --reuse-values
  5. Triggers a rolling restart of the optio-api and optio-web deployments

​
Manual rebuild

If you change source files and want to redeploy without a full update: 
# Rebuild API and web images
docker build -t optio-api:latest -f Dockerfile.api .
docker build -t optio-web:latest -f Dockerfile.web .

# Trigger a rolling restart
kubectl rollout restart deployment/optio-api deployment/optio-web -n optio
To rebuild a specific agent image preset: 
# Example: rebuild the Node.js agent image
docker build -t optio-node:latest -f images/node.Dockerfile .

​
Teardown

To remove Optio from your cluster: 
helm uninstall optio -n optio
This removes all Kubernetes resources in the optio namespace including deployments, services, PersistentVolumeClaims, and the namespace itself. Your Docker images are not removed.

​
Troubleshooting

The script exits with ❌ No Kubernetes cluster found. if kubectl cannot reach a cluster.
  • Open Docker Desktop → Settings → Kubernetes and confirm “Enable Kubernetes” is checked
  • Wait for the status indicator to show “Kubernetes is running”
  • Verify with: kubectl cluster-info
This usually means the agent image is not in the local containerd store.
  • Verify images exist: docker images | grep optio
  • If any are missing, re-run ./scripts/setup-local.sh (it will upgrade the existing Helm release)
  • Check the pod events: kubectl describe pod <pod-name> -n optio
  • Check that both deployments are running: kubectl get pods -n optio
  • Confirm the NodePort services are in place: kubectl get svc -n optio
  • Expected: optio-api on NodePort 30400, optio-web on NodePort 30310
  • Check agent pod status: kubectl get pods -n optio
  • Look for ImagePullBackOff — this means imagePullPolicy is not Never or the image is missing locally
  • Check PVC availability: kubectl get pvc -n optio

Build docs developers (and LLMs) love

Get started for freeTalk to us