kelos-dev/kelos: Running Coding Agents as Kubernetes Workloads

The problem Kelos solves is where the agent runs, not what it writes

Coding agents are usually run from a developer laptop. That works until the work is long, parallel, or triggered by something other than a person. Kelos moves the agent into Kubernetes: the README states that the project 'turns coding agents into Kubernetes workloads' and that it provides 'the repository, credentials, tools, compute, and workflow needed to complete it'. The audience is therefore platform and CI engineers who already have a cluster and want agent runs to be scheduled, limited and observed like any other workload.

The README lists the supported providers explicitly: Claude Code, OpenAI Codex, Google Gemini, OpenCode, Cursor, and custom agent images via docs/agent-image-interface.md. The repository layout confirms this with top-level directories named claude-code/, codex/, gemini/, opencode/ and cursor/, plus a cmd/ tree containing controllers, a spawner, a worker runner, a session runtime, a console server, a GitHub proxy and a webhook server. If you only ever run one agent interactively on your own machine, none of this earns its keep.

How the controller turns Task, Session and Workspace into Pods and Jobs

The mechanism is a Kubernetes controller. The README says plainly that 'the controller turns Kelos resources into Pods, Jobs, and StatefulSets'. Everything else is an API object with a purpose: Task runs one agent job, TaskPipeline runs ordered Task stages with matrix fan-out, Session keeps an interactive conversation running, Workspace gives agents a Git repository, AgentConfig shares instructions, skills, plugins and MCP servers, TaskSpawner creates Tasks from events or schedules, SessionSpawner creates Sessions from GitHub webhooks, and WorkerPool maintains reusable agent workers.

The data flow implied by those primitives is: a source (webhook, cron, or a manual command) produces a Task or Session; the Task references a Workspace for its repository and an AgentConfig for shared instructions; the controller materialises that into a workload; status is written back onto the Kelos object. The README states that 'Task status records useful results such as branches, commits, pull requests, and token usage', which is the part that makes this more than a job runner. Because the objects are ordinary Kubernetes resources, the README notes that advanced users can 'review them, keep them in Git, or manage them with existing delivery tools'. That is the strongest argument for the design and also the source of its operational weight: you are adding CRDs to a cluster you must then maintain.

Installing Kelos and running a first Task against a real repository

The README states the prerequisites directly: a Kubernetes 1.28+ cluster with cert-manager installed. Install the CLI with the install script, Homebrew, or go install. The script form is:

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

The Homebrew and Go paths are given as alternatives in the README:

brew tap kelos-dev/tap
brew install kelos

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

With the binary on your PATH, install the cluster components. The README shows a single command for this and points to the Helm chart for upgrades:

kelos install

Next, initialise the local config file and add credentials following the comments in the generated file. The README names the path as ~/.kelos/config.yaml:

kelos init

Now create a Workspace, which is the object that gives an agent a Git repository and a ref:

kelos create workspace my-workspace \
  --repo https://github.com/your-org/your-repo.git \
  --ref main

Finally, create and watch a Task. The README gives this exact command, and notes that it prints the generated Task name:

kelos run \
  --workspace my-workspace \
  --prompt "Add a hello world program in Python" \
  --watch

To stream logs afterwards, use the printed Task name:

kelos logs TASK_NAME -f

The README also offers a second path that avoids writing configuration by hand: install the first-party skill with npx skills add kelos-dev/kelos, then ask your coding agent to use the /kelos skill. The examples directory is the better reference for anything beyond this, with 18 numbered examples covering cron and GitHub issue spawners, pipelines, budgets, worker pools and sessions.

Where Kelos is the wrong tool: credentials, cluster coupling and thin docs

The first constraint is that Kelos is not standalone. Without a Kubernetes 1.28+ cluster and cert-manager, kelos install has nothing to install onto. Anyone looking for a local agent runner is in the wrong project.

The second is credentials. The README's own guidance is to 'use scoped credentials, protected branches, and workload limits for autonomous agents'. That sentence is doing a lot of work. Kelos stores agent credentials as Kubernetes Secrets, and the README's own example prompt asks the agent to 'ask before creating or replacing any Kubernetes Secret'. A framework that runs autonomous agents with repository write access inside your cluster expands the blast radius of a leaked Secret or an over-permissioned agent. Kelos gives you Kubernetes controls to limit that, but it does not remove the need to configure them.

The third is documentation depth. The README is long on prompts and short on operational detail. It does not document rollback for a failed install, it does not describe what kelos install does to the cluster beyond the fact that it installs Kelos, and the upgrade path is delegated to internal/manifests/charts/kelos/README.md rather than covered in the main file. For a controller that creates Jobs and StatefulSets on your cluster, that is a real gap. Read the chart documentation and docs/reference.md before you run this against a cluster you care about.

Kelos compared with running agents in CI or on a laptop

The obvious alternative is a CI system. A GitHub Actions workflow can check out a repository, run an agent binary, and open a pull request, and it needs no controller, no CRDs and no cert-manager. The difference in approach is where state lives. CI is built around a run that starts and ends; Kelos is built around Kubernetes objects that persist. That is why Session exists as a primitive: the README describes keeping 'interactive Sessions alive and reconnect from terminal or web clients', and the repository includes a console server and a browser-based chat screenshot in docs/images/. A CI job cannot hold a conversation open and let you reconnect to it later.

The second alternative is simply running the agent on a developer laptop. That is faster to start and needs no infrastructure. Kelos trades that away for isolation, scheduling, concurrency limits and shared configuration through AgentConfig. The README's framing of running agents 'in isolated Kubernetes workloads instead of on developer laptops' is the whole comparison in one line. If your agents are short, interactive and single-user, the laptop wins. If they are triggered by webhooks, run in parallel across many repositories, or need to be limited and observed, the controller starts to pay for itself.

Maintenance, release cadence and the Apache-2.0 licence

The repository is not archived, and the last push was on 2026-09-14. Releases are frequent: v0.56.0 on 2026-09-13, v0.55.0 on 2026-09-06 and v0.54.0 on 2026-08-30, roughly a weekly cadence across three consecutive weeks. This is a project that is moving, and that cuts both ways. You get fixes quickly. You also get a moving target, and the version numbers are still in the 0.x range, which conventionally signals that the API has not been declared stable.

Upgrade cost is a real line item. The README points Helm users to internal/manifests/charts/kelos/README.md for installations and upgrades, so the chart is the supported path once you are past the first install. Because Kelos adds custom resources to your cluster, an upgrade can involve CRD changes, and the README does not describe a rollback procedure. The Makefile shows the image set that has to be built and published (cmd/kelos-controller, cmd/kelos-spawner, cmd/kelos-worker-runner, cmd/kelos-session-runtime, cmd/kelos-console-server, cmd/ghproxy, cmd/kelos-webhook-server, cmd/kelos-slack-server, plus the per-provider images), which gives a sense of how many moving parts a version bump touches.

The licence is Apache-2.0, a permissive licence that permits commercial use and modification. That is a fact about the repository, not legal advice; if you are redistributing Kelos or bundling it into a product, have your own counsel review the LICENSE file and any third-party dependency obligations in go.mod.

Editorial conclusion

Adopt Kelos if you already operate Kubernetes and want agent runs isolated in Pods, Jobs and StatefulSets with credentials, repositories and limits declared as ordinary resources. Do not adopt it if you have no cluster, no cert-manager, or no appetite for operating a controller and its CRDs; the README's own warning about scoped credentials and protected branches is the boundary to respect. Verify first that your cluster is 1.28+ with cert-manager installed, that the agent provider you intend to use has a credential path you are willing to store as a Kubernetes Secret, and that the Workspace ref and repository URL you plan to use are reachable from inside the cluster before you create your first Task.

Frequently asked questions

Official sources

1. Issues
2. kelos-dev/kelos on GitHub
3. License: Apache-2.0
4. README
5. Releases