kubeopencode

Kubernetes-native Agent Platform for Teams and Enterprise

Note: KubeOpenCode builds on the excellent OpenCode AI agent. OpenCode is great for individual developers — KubeOpenCode makes it work for teams and enterprises by adding governance, shared agent configurations, scale, and enterprise infrastructure integration. This is an independent project, not affiliated with the OpenCode team.

Demo

Overview

KubeOpenCode is a Kubernetes-native agent platform that enables teams to deploy, manage, and govern AI agents at scale. Built on OpenCode, it turns individual AI capabilities into a shared, enterprise-ready platform.

Why KubeOpenCode?

• Live Agents on Kubernetes: Every Agent runs as a persistent service — interactive terminal access, shared context across tasks, zero cold start. Perfect for team-shared coding assistants, Slack bots, and always-on development agents.
• For Teams: Shared agent configurations, batch operations across repositories, concurrency control, and centralized credential management — so your entire team can leverage AI agents with consistent standards.
• For Enterprise: RBAC, private registry support, corporate proxy integration, custom CA certificates, pod security policies, and audit-ready infrastructure — meeting the governance and compliance requirements of enterprise environments.
• Kubernetes-Native: Declarative CRDs, GitOps-friendly, works with Helm/Kustomize/ArgoCD — no new tools to learn, just kubectl apply.

Community

Get Help & Connect:

• Slack: Join KubeOpenCode Slack - Ask questions and get auto-answers from the KubeOpenCode bot
• Discussions: GitHub Discussions - Community Q&A with KubeOpenCode bot assistance
• Issues: GitHub Issues - Bug reports and feature requests

Architecture

┌─────────────────────────────────────────────┐
│         Kubernetes API Server               │
│  - Custom Resource Definitions (CRDs)       │
│  - RBAC & Authentication                    │
└─────────────────┬───────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────┐
│      KubeOpenCode Controller (Operator)     │
│  - Watch Task CRs                           │
│  - Create Kubernetes Pods for tasks         │
│  - Update CR status                         │
└─────────────────┬───────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────┐
│            Kubernetes Pods                  │
│  - Execute tasks using AI agents            │
│  - Context files mounted as volumes         │
└─────────────────────────────────────────────┘

Core Concepts

• Task: Single task execution (the primary API). References either an Agent (agentRef) or a template (templateRef).
• CronTask: Scheduled/recurring task execution — creates Tasks on a cron schedule with concurrency policies.
• Agent: Running AI agent instance — always creates a Deployment + Service. Interactive access via CLI, web terminal, or programmatic Tasks.
• AgentTemplate: Reusable blueprint for Agents (configuration inheritance) and for ephemeral Tasks (one-off Pods without a persistent Agent).
• KubeOpenCodeConfig: System-level configuration (optional)

Note: Workflow orchestration and webhook triggers have been delegated to Argo Workflows and Argo Events respectively. KubeOpenCode focuses on the core Task/Agent abstraction.

Quick Start

Prerequisites

• Kubernetes 1.25+
• Helm 3.8+

Installation

# Create namespace
kubectl create namespace kubeopencode-system

# Install from OCI registry (with UI enabled)
helm install kubeopencode oci://quay.io/kubeopencode/helm-charts/kubeopencode \
  --namespace kubeopencode-system \
  --set server.enabled=true

Minimal Example

# Create an Agent
apiVersion: kubeopencode.io/v1alpha1
kind: Agent
metadata:
  name: default
  namespace: kubeopencode-system
spec:
  profile: "General-purpose development agent"
  workspaceDir: /workspace
  serviceAccountName: kubeopencode-agent
  credentials:
    - name: api-key
      secretRef:
        name: ai-credentials
        key: api-key
      env: OPENCODE_API_KEY
---
# Create a Task
apiVersion: kubeopencode.io/v1alpha1
kind: Task
metadata:
  name: my-task
  namespace: kubeopencode-system
spec:
  agentRef:
    name: default
  description: |
    Update dependencies to latest versions.
    Run tests and create PR.

# Monitor progress
kubectl get tasks -n kubeopencode-system -w
kubectl logs $(kubectl get task my-task -o jsonpath='{.status.podName}') -n kubeopencode-system

Live Agent

Deploy a persistent AI agent that your team can interact with anytime:

apiVersion: kubeopencode.io/v1alpha1
kind: Agent
metadata:
  name: team-agent
  namespace: kubeopencode-system
spec:
  profile: "Always-on development agent for the team"
  workspaceDir: /workspace
  serviceAccountName: kubeopencode-agent
  port: 4096
  persistence:
    sessions:
      size: "2Gi"
  credentials:
    - name: api-key
      secretRef:
        name: ai-credentials
        key: api-key
      env: OPENCODE_API_KEY

# The controller automatically creates a Deployment + Service
kubectl get agents -n kubeopencode-system
# NAME         PROFILE                                  STATUS
# team-agent   Always-on development agent for the team Ready

# Attach to the live agent from your terminal
kubeoc agent attach team-agent -n kubeopencode-system

See the Getting Started Guide for detailed examples including Agent setup, ephemeral template-based tasks, and interactive access.

CLI

The KubeOpenCode CLI lets you list agents and interactively attach to them from your terminal — no kubectl port-forward needed.

Install:

go install github.com/kubeopencode/kubeopencode/cmd/kubeoc@latest

Configure (optional — defaults to KUBECONFIG / ~/.kube/config):

# Point to the cluster where KubeOpenCode agents run
export KUBEOPENCODE_KUBECONFIG=/path/to/agent-cluster.kubeconfig

Usage:

# List available agents
kubeoc get agents

# NAMESPACE    NAME           PROFILE                          STATUS
# test         my-agent       General-purpose dev agent         Ready
# prod         review-bot     Automated code review agent       Ready

# Attach to an agent (connects via kube-apiserver service proxy)
kubeoc agent attach my-agent -n test

The CLI authenticates using your kubeconfig credentials and connects through the kube-apiserver's built-in service proxy — no Ingress or port-forward required.

Documentation

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines on:

• Commit standards (signed commits required)
• Pull request process
• Code standards and testing requirements
• Development workflow

License

Copyright Contributors to the KubeOpenCode project.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at:

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Acknowledgments

KubeOpenCode is inspired by:

• Tekton Pipelines
• Argo Workflows
• Kubernetes Batch API

Built with:

• controller-runtime
• kubebuilder

Made with love by the KubeOpenCode community