Getting Started

Alpha Project

KubeOpenCode is in early alpha (v0.1.x). It is not recommended for production use. The API (v1alpha1) may introduce breaking changes between releases — backward compatibility is not guaranteed at this stage. We welcome contributions and feedback!

This guide covers installing KubeOpenCode on a Kubernetes cluster and running your first AI task. The default setup uses the free opencode/big-pickle model — no API key required.

Looking for local development setup? If you want to build from source and run on a local Kind cluster, see the Contributing Guide.

Prerequisites

• A Kubernetes cluster (1.28+)
• kubectl
• Helm 3.8+

Installation

Install from OCI Registry

kubectl create namespace kubeopencode-system

helm install kubeopencode oci://ghcr.io/kubeopencode/helm-charts/kubeopencode \
  --namespace kubeopencode-system \
  --set server.enabled=true

Verify Deployment

# Controller and UI server
kubectl get pods -n kubeopencode-system

Expected output:

NAME                                       READY   STATUS    RESTARTS   AGE
kubeopencode-controller-xxxxxxxxx-xxxxx    1/1     Running   0          30s
kubeopencode-server-xxxxxxxxx-xxxxx        1/1     Running   0          30s

Check CRDs are installed:

kubectl get crds | grep kubeopencode

Access the Web UI

kubectl port-forward -n kubeopencode-system svc/kubeopencode-server 2746:2746

Open http://localhost:2746. The UI provides:

• Task List — View and filter Tasks across namespaces
• Task Detail — Monitor execution with real-time log streaming
• Task Create — Submit new Tasks to Agents
• Agent Browser — View Agents and AgentTemplates

Try It Out

Create an Agent

Create a namespace and a simple Agent. By default, Agents use the free opencode/big-pickle model — no API key required. You can change the model via the Agent's config field (see Setting Up an Agent).

kubectl create namespace test

kubectl apply -n test -f - <<EOF
apiVersion: kubeopencode.io/v1alpha1
kind: Agent
metadata:
  name: dev-agent
spec:
  profile: "A lightweight development agent"
  workspaceDir: /workspace
EOF

Submit a Task

kubectl apply -n test -f - <<EOF
apiVersion: kubeopencode.io/v1alpha1
kind: Task
metadata:
  name: hello-world
spec:
  agentRef:
    name: dev-agent
  description: "Say hello and tell me what tools you have available"
EOF

# Watch the task
kubectl get task -n test -w

Using a Paid Model

The default setup uses the free opencode/big-pickle model. To switch to a paid model (Anthropic, Google, etc.), create a Secret with your API key and reference it in the Agent's credentials field. See Security for details.

Upgrade

helm upgrade kubeopencode oci://ghcr.io/kubeopencode/helm-charts/kubeopencode \
  --namespace kubeopencode-system \
  --set server.enabled=true

See Operations for upgrade and maintenance guides.

Next Steps

• Setting Up an Agent — Configure your own Agent: model selection, images, persistence, and more
• Features — Learn about Live Agents (human-in-the-loop) and automated workflows
• Security — RBAC, credential management, and best practices
• Architecture — System design and API reference