by kelos-dev
Kelos - The Kubernetes-native framework for orchestrating autonomous AI coding agents.
# Add to your Claude Code skills
git clone https://github.com/kelos-dev/kelosKelos is a Kubernetes-native framework for AI coding agents. It does two things:
Supports Claude Code, OpenAI Codex, Google Gemini, OpenCode, Cursor, and custom agent images.
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).
Kelos is built on four resources, grouped by the two concerns above:
Defining the agent and its environment
AGENTS.md, CLAUDE.md), plugins (skills and agents), and MCP servers.Integrating with workflows
No comments yet. Be the first to share your thoughts!
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.
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.kubectl, manage via the kelos CLI or declarative YAML (GitOps-ready), and integrate with ArgoCD or GitHub Actions.Get running in 5 minutes (most of the time is gathering credentials).
kind create cluster
This creates a single-node cluster and configures your kubeconfig automatically.
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
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
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.
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.
$ 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