Kelos

Orchestrate autonomous AI coding agents on Kubernetes.

Quick Start · Kelos Skill · Kelos Developing Kelos · Examples · Integration · Reference · YAML Manifests

Kelos lets you define your development workflow as Kubernetes resources and run it continuously. Declare what triggers agents, what they do, and how they hand off — Kelos handles the rest.

Kelos develops Kelos through TaskSpawners running 24/7: triaging issues, planning implementations, fixing bugs, responding to PR feedback, reviewing code, squashing commits, updating agent images, testing DX, brainstorming improvements, and tuning their own prompts and configs. See the full pipeline below.

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

Kelos orchestrates the flow from external events to autonomous execution:

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:

1. Tasks — Ephemeral units of work that wrap an AI agent run.
2. Workspaces — Persistent or ephemeral environments (git repos) where agents operate.
3. AgentConfigs — Reusable bundles of agent instructions (AGENTS.md, CLAUDE.md), plugins (skills and agents), and MCP servers.
4. TaskSpawners — Orchestration engines that react to external triggers (GitHub, Cron) to automatically manage agent lifecycles.

Kelos develops itself. TaskSpawners run 24/7, each handling a different part of the development lifecycle — fully autonomous.

See the self-development/ README for the full pipeline: manifests, triggers, models, and setup instructions.

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.

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

• Kubernetes cluster (1.28+)

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

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

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

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.

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

apiVersion: kelos.dev/v1alpha1
kind: Task
metadata:
  name: hello-world
spec:
  type: claude-code
  prompt: "Create a hello world program in Python"
  credentials:
    type: oauth
    secretRef:
      name: claude-oauth-token
  workspaceRef:
    name: my-workspace

kubectl apply -f workspace.yaml
kubectl apply -f task.yaml
kubectl get tasks -w

apiKey: <your-api-key>

The Kelos skill teaches AI coding agents how to author and operate Kelos resources. Install it via skills.sh:

npx skills add kelos-dev/kelos

Then ask your agent:

Using the /kelos skill, set up a TaskSpawner that watches GitHub issues
labeled "bug" and auto-creates Tasks to fix them.

The agent will generate the correct manifests, apply them, and troubleshoot any issues on your behalf.

Create a TaskSpawner to automatically turn GitHub issues into agent tasks:

apiVersion: kelos.dev/v1alpha1
kind: TaskSpawner
metadata:
  name: fix-bugs
spec:
  when:
    githubIssues:
      labels: [bug]
      state: open
      pollInterval: 5m
  taskTemplate:
    type: claude-code
    workspaceRef:
      name: my-workspace
    credentials:
      type: oauth
      secretRef:
        name: claude-oauth-token
    promptTemplate: "Fix: {{.Title}}\n{{.Body}}"

kubectl apply -f taskspawner.yaml

TaskSpawner polls for new issues matching your filters and creates a Task for each one.

Use dependsOn to chain tasks into pipelines. A task in Waiting phase stays paused until all its dependencies succeed:

kelos run -p "Scaffold a new user service" --name scaffold --branch feature/user-service
kelos run -p "Write tests for the user service" --depends-on scaffold --branch feature/user-service

Tasks sharing the same branch are serialized automatically — only one runs at a time.

apiVersion: kelos.dev/v1alpha1
kind: Task
metadata:
  name: scaffold
spec:
  type: claude-code
  prompt: "Scaffold a new user service with CRUD endpoints"
  credentials:
    type: oauth
    secretRef:
      name: claude-oauth-token
  workspaceRef:
    name: my-workspace
  branch: feature/user-service
---
apiVersion: kelos.dev/v1alpha1
kind: Task
metadata:
  name: write-tests
spec:
  type: claude-code
  prompt: "Write comprehensive tests for the user service"
  credentials:
    type: oauth
    secretRef:
      name: claude-oauth-token
  workspaceRef:
    name: my-workspace
  branch: feature/user-service
  dependsOn: [scaffold]

Downstream tasks can reference upstream results in their prompt using {{.Deps}}:

apiVersion: kelos.dev/v1alpha1
kind: Task
metadata:
  name: open-pr
spec:
  type: claude-code
  prompt: |
    Open a PR for branch {{index .Deps "write-tests" "Results" "branch"}}.
  credentials:
    type: oauth
    secretRef:
      name: claude-oauth-token
  workspaceRef:
    name: my-workspace
  branch: feature/user-service
  dependsOn: [write-tests]

The .Deps map is keyed by dependency Task name. Each entry has Results (key-value map with branch, commit, pr, etc.) and Outputs (raw output lines). See examples/07-task-pipeline for a full three-stage pipeline.

Add a token to your workspace config:

workspace:
  repo: https://github.com/your-org/repo.git
  ref: main
  token: <your-github-token>

kelos run -p "Fix the bug described in issue #42 and open a PR with the fix"

The gh CLI and GITHUB_TOKEN are available inside the agent container, so the agent can push branches and create PRs autonomously.

Use AgentConfig to bundle project-wide instructions, plugins, and MCP servers:

apiVersion: kelos.dev/v1alpha1
kind: AgentConfig
metadata:
  name: my-config
spec:
  agentsMD: |
    # Project Rules
    Follow TDD. Always write tests first.
  mcpServers:
    - name: github
      type: http
      url: https://api.githubcopilot.com/mcp/
      headers:
        Authorization: "Bearer <token>"

kelos run -p "Fix the bug" --agent-config my-config

• agentsMD is written to ~/.claude/CLAUDE.md (user-level, additive with the repo's own instructions).
• plugins are mounted as plugin directories and passed via --plugin-dir.
• mcpServers are written to the agent's native MCP configuration. Supports stdio, http, and sse transport types.

See the full AgentConfig spec for plugins, skills, and agents configuration.

Browse all ready-to-apply YAML manifests in the examples/ directory.

Kelos integrates with external systems in two ways:

TaskSpawner — Kelos natively watches external sources and automatically creates Tasks. Supports GitHub Issues, GitHub Pull Requests, GitHub Webhooks, Jira, and Cron schedules. No glue code needed.

spec:
  when:
    githubIssues:
      labels: [bug]
      state: open

Direct Task creation — Create Task resources from your own workflows for full control. Any system that can run kubectl apply or call the Kubernetes API can trigger agent runs — GitHub Actions, CI/CD pipelines, scripts, Slack bots, or custom automation.

kelos run -p "Fix the flaky test in ci_test.go" --workspace my-workspace

See the Integration guide for examples of both approaches, including GitHub Actions workflows, Jira setup, and programmatic Task creation.

• Autonomous Self-Development — Build a feedback loop where agents pick up issues, write code, self-review, and fix CI flakes until the task is complete. See the self-development pipeline.
• Event-Driven Bug Fixing — Automatically spawn agents to investigate and fix bugs as soon as they are labeled in GitHub. See Auto-fix GitHub issues.
• Fleet-Wide Refactoring — Orchestrate a "fan-out" where dozens of agents apply the same refactoring pattern across a fleet of microservices in parallel.
• Hands-Free CI/CD — Embed agents as first-class steps in your deployment pipelines to generate documentation or perform automated migrations.
• AI Worker Pools — Maintain a pool of specialized agents (e.g., "The Security Fixer") that developers can trigger via simple Kubernetes resources.

Kelos runs agents in isolated, ephemeral Pods with no access to your host machine, SSH keys, or other processes. The risk surface is limited to what the injected credentials allow.

What agents CAN do: Push branches, create PRs, and call the GitHub API using the injected GITHUB_TOKEN.

What agents CANNOT do: Access your host, read other pods, reach other repositories, or access any credentials beyond what you explicitly inject.

Best practices:

• Scope your GitHub tokens. Use fine-grained Personal Access Tokens restricted to specific repositories instead of broad repo-scoped classic tokens.
• Enable branch protection. Require PR reviews before merging to main. Agents can push branches and open PRs, but protected branches prevent direct pushes to your default branch.
• Use maxConcurrency and maxTotalTasks. Limit how many tasks a TaskSpawner can create to prevent runaway agent activity.
• Use podOverrides.activeDeadlineSeconds. Set a timeout to prevent tasks from running indefinitely.
• Audit via Kubernetes. Every agent run is a first-class Kubernetes resource — use kubectl get tasks and cluster audit logs to track what was created and by whom.

About --dangerously-skip-permissions: Claude Code uses this flag for non-interactive operation. Despite the name, the actual risk is minimal — agents run inside ephemeral containers with no host access. The flag simply disables interactive approval prompts, which is necessary for autonomous execution.

Kelos uses standard Kubernetes RBAC — use namespace isolation to separate teams. Each TaskSpawner automatically creates a scoped ServiceAccount and RoleBinding.

Running AI agents costs real money. Here's how to stay in control:

Model costs vary significantly. Opus is the most capable but most expensive model. Use spec.model (or model in config) to choose cheaper models like Sonnet for routine tasks and reserve Opus for complex work. Check the API pricing page for current rates.

Use maxConcurrency to cap spend. Without it, a TaskSpawner can create unlimited concurrent tasks. If 100 issues match your filter on first poll, that's 100 simultaneous agent runs. Always set a limit:

spec:
  maxConcurrency: 3      # max 3 tasks running at once
  maxTotalTasks: 50       # stop after 50 total tasks

Use podOverrides.activeDeadlineSeconds to limit runtime. Set a timeout per task to prevent agents from running indefinitely:

spec:
  podOverrides:
    activeDeadlineSeconds: 3600  # kill after 1 hour

Or via the CLI:

kelos run -p "Fix the bug" --timeout 30m

Use suspend for emergencies. If costs are spiraling, pause a spawner immediately:

kelos suspend taskspawner my-spawner
# ... investigate ...
kelos resume taskspawner my-spawner

Rate limits. API providers enforce concurrency and token limits. If a task hits a rate limit mid-execution, it will likely fail. Use maxConcurrency to stay within your provider's limits.

kelos uninstall

Build, test, and iterate with make:

make update             # generate code, CRDs, fmt, tidy
make verify             # generate + vet + tidy-diff check
make test               # unit tests
make test-integration   # integration tests (envtest)
make test-e2e           # e2e tests (requires cluster)
make build              # build binary
make image              # build docker image

1. Fork the repo and create a feature branch.
2. Make your changes and run make verify to ensure everything passes.
3. Open a pull request with a clear description of the change.

For significant changes, please open an issue first to discuss the approach.

We welcome contributions of all kinds — see good first issues for places to start.

Apache License 2.0