kelos

Kelos is a Kubernetes-native framework for AI coding agents. It does two things:

1. Defines the agent and the environment it runs in as one unit — the prompt, model, instructions, plugins, MCP servers, git workspace, credentials, and Pod resources all live together as Kubernetes resources you can version-control.
2. Defines how agents integrate with your workflows — trigger runs from GitHub issues, PRs, webhooks, Linear, Jira, schedules, or any HTTP source, and chain agents into pipelines.

Supports Claude Code, OpenAI Codex, Google Gemini, OpenCode, Cursor, and custom agent images.

How It Works

You define what needs to be done, and Kelos handles the "how" — from cloning the right repo and injecting credentials to running the agent and capturing its outputs (branch names, commit SHAs, PR URLs, and token usage).

Core Primitives

Kelos is built on four resources, grouped by the two concerns above:

Defining the agent and its environment

• Tasks — A single agent run: prompt, model, effort, credentials, and Pod-level overrides.
• Workspaces — The git repository (URL, ref, auth) the agent operates in.
• AgentConfigs — Reusable bundles of agent instructions (AGENTS.md, CLAUDE.md), plugins (skills and agents), and MCP servers.

Integrating with workflows

• TaskSpawners — React to external triggers (GitHub Issues/PRs, webhooks, Linear, Jira, Cron, Generic Webhooks) and create Tasks automatically.

Why Kelos?

AI coding agents are evolving from interactive CLI tools into autonomous background workers — managed like infrastructure, not invoked like commands. Kelos provides the framework to manage this transition at scale.

• Workflow as YAML — Define your development workflow declaratively: what triggers agents, what they do, and how they hand off. Version-control it, review it in PRs, and GitOps it like any other infrastructure.
• Orchestration, not just execution — Don't just run an agent; manage its entire lifecycle. Chain tasks with dependsOn and pass results (branch names, PR URLs, token usage) between pipeline stages. Use TaskSpawner to build event-driven workers that react to GitHub issues, PRs, or schedules.
• Host-isolated autonomy — Each task runs in an isolated, ephemeral Pod with a freshly cloned git workspace. Agents have no access to your host machine — use scoped tokens and branch protection to control repository access.
• Standardized interface — Plug in any agent (Claude, Codex, Gemini, OpenCode, Cursor, or your own) using a simple container interface. Kelos handles credential injection, workspace management, and Kubernetes plumbing.
• Scalable parallelism — Fan out agents across multiple repositories. Kubernetes handles scheduling, resource management, and queueing — scale is limited by your cluster capacity and API provider quotas.
• Observable & CI-native — Every agent run is a first-class Kubernetes resource with deterministic outputs (branch names, PR URLs, commit SHAs, token usage) captured into status. Monitor via kubectl, manage via the kelos CLI or declarative YAML (GitOps-ready), and integrate with ArgoCD or GitHub Actions.

Quick Start

Get running in 5 minutes (most of the time is gathering credentials).

Prerequisites

• Kubernetes cluster (1.28+)
• cert-manager installed and ready

1. Install kind (requires Docker)
2. Create a cluster:

   kind create cluster
   

This creates a single-node cluster and configures your kubeconfig automatically.

1. Install the CLI

Install using the script:

curl -fsSL https://raw.githubusercontent.com/kelos-dev/kelos/main/hack/install.sh | bash

Or using Homebrew:

brew tap kelos-dev/tap
brew install kelos

go install github.com/kelos-dev/kelos/cmd/kelos@latest

2. Install Kelos

Kelos uses cert-manager to issue the CRD conversion webhook certificate. Install cert-manager first if your cluster does not already have it. Follow the cert-manager installation documentation for the current recommended installation method.

kelos install

This installs the Kelos controller and CRDs into the kelos-system namespace.

For chart-native customization, pass Helm values to kelos install:

kelos install -f values.yaml
kelos install --set webhookServer.sources.github.enabled=true

kelos install manages CRDs separately, so crds.install must be omitted or set to false. kelos install --dry-run prints controller manifests only; CRDs are staged separately during real installs after certificate and conversion webhook readiness. For the full values schema and advanced examples, see the Helm chart README.

Verify the installation:

kubectl get pods -n kelos-system
kubectl get crds | grep kelos.dev

Helm Install

Kelos also publishes a Helm chart as an OCI artifact in GHCR.

To install Kelos with Helm:

helm upgrade --install kelos oci://ghcr.io/kelos-dev/charts/kelos \
  -n kelos-system \
  --create-namespace \
  --version <version> \
  --set crds.install=true

This installs the controller resources and Kelos CRDs. The chart default leaves CRD rendering disabled for clusters where CRDs are managed by kelos install or another manifest workflow. Use kelos install for the staged controller-plus-CRD install, or see the Helm chart README for fresh-install, upgrade, and adoption flows.

For CRD migration, adopting existing CRDs into Helm ownership, and advanced chart usage, see the Helm chart README.

3. Initialize Your Config

kelos init

Edit ~/.kelos/config.yaml:

oauthToken: <your-oauth-token>
workspace:
  repo: https://github.com/your-org/your-repo.git
  ref: main
  token: <github-token>  # optional, for private repos and pushing changes

Claude OAuth token (recommended for Claude Code): Run claude setup-token locally and follow the prompts. This generates a long-lived token (valid for ~1 year). Copy the token from ~/.claude/credentials.json.

Anthropic API key (alternative for Claude Code): Create one at console.anthropic.com. Set apiKey instead of oauthToken in your config.

Codex OAuth credentials (for OpenAI Codex): Run codex auth login locally, then reference the auth file in your config:

oauthToken: "@~/.codex/auth.json"
type: codex

For production installs, you can keep Codex OAuth credentials fresh by labeling each credentials Secret with kelos.dev/codex-oauth-refresh=true. Kelos creates one CronJob per labeled Secret; each CronJob uses Codex's file-backed auth refresh and writes the updated auth.json back to that Secret. See the Helm chart README for values and setup. Or set apiKey with an OpenAI API key instead.

Gemini API key (for Google Gemini): Create one at aistudio.google.com/app/apikey. Set apiKey in your config and use type: gemini.

Cursor API key (for Cursor CLI): Obtain one from the Integrations tab at cursor.com/dashboard. Set apiKey in your config and use type: cursor.

GitHub token (for pushing branches and creating PRs): Create a Personal Access Token with repo scope (and workflow if your repo uses GitHub Actions).

GitHub App (recommended for production/org use): For organizations, GitHub Apps are preferred over PATs — they offer fine-grained permissions, higher rate limits, and don't depend on a specific user account. Use githubApp instead of token in your workspace config:

workspace:
  repo: https://github.com/your-org/repo.git
  ref: main
  githubApp:
    appID: "12345"
    installationID: "67890"
    privateKeyPath: ~/.config/my-app.private-key.pem

See the Workspace reference for details.

Warning: Without a workspace, the agent runs in an ephemeral pod — any files it creates are lost when the pod termina