kelos

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+)

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 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. 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>

This installs the controller and, by default, the Kelos CRDs.

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

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 terminates. Always set up a workspace to get persistent results.

4. Run Your First Task

$ kelos run -p "Add a hello world program in Python"
task/task-r8x2q created

$ kelos logs task-r8x2q -f

The task name (e.g. task-r8x2q) is auto-generated. Use --name to set a custom name, or -w to watch task status after creation. To stream agent logs, run kelos logs <task-name> -f.

You can also read the prompt from a file with --prompt-file, or pipe it from stdin:

$ kelos run --prompt-file prompt.txt
$ echo "Fix the flaky test" | kelos run --prompt-file -

The agent clones your repo, makes changes, and can push a branch or open a PR.

Tip: If something goes wrong, check the controller logs with kubectl logs deployment/kelos-controller-manager -n kelos-system.

Create a Workspace resource to define a git repository:

apiVersion: kelos.dev/v1alpha1
kind: Workspace
metadata:
  name: my-workspace
spec:
  repo: https://github.com/your-org/your-repo.git
  ref: main

Then reference it from a Task:

apiVersion: kelos.dev/v1alpha1
kind: Task
metadata:
  name: hello-wor