# Kelos: eight Kubernetes objects replace the laptop where a coding agent runs

> Kelos is a Go controller that turns coding agents into ordinary Kubernetes workloads, so a Task, Session, or TaskSpawner is reviewable YAML in Git rather than a terminal someone left open. The tradeoff is a 1.28+ cluster with cert-manager, plus a webhook surface you are expected to scope yourself.

**kelos-dev/kelos** — Kelos - The Kubernetes-native framework for orchestrating autonomous AI coding agents.

- Repository: https://github.com/kelos-dev/kelos
- Stars: 335 · Forks: 44
- Language: Go
- License: Apache-2.0
- Published: 2026-09-15 · Updated: 2026-09-15 · Language: en
- Canonical page: https://hysenlabs.com/projects/kelos-dev-kelos

## Eight resource kinds cover one-off jobs through persistent conversations

The unit of work is a custom resource, and the set is small enough to read in one sitting. A `Task` runs one agent job. A `TaskPipeline` runs ordered Task stages with matrix fan-out. A `Session` keeps an interactive agent conversation alive so you can reconnect. A `Workspace` hands agents a Git repository. An `AgentConfig` shares instructions, skills, plugins, and MCP servers across agents so the same setup is not retyped per workload.

The remaining three are spawners and a pool. `TaskSpawner` creates Tasks from events or schedules, `SessionSpawner` creates Sessions from GitHub webhooks, and `WorkerPool` maintains reusable agent workers instead of a fresh pod per request.

Because these stay ordinary Kubernetes objects, `kubectl get` works on them, they can be committed to Git, and existing delivery tooling can manage them. That is the argument for the whole design: nothing here is a private control plane you cannot inspect.

## The controller compiles resources into Pods, Jobs, and StatefulSets

Kelos ships as a controller written in Go, and the mapping is direct: Kelos resources become Pods, Jobs, and StatefulSets. A StatefulSet is what makes a persistent Session plausible, since a conversational session has to survive the pod it started in.

Task status is where the useful output lands. A finished Task records branches, commits, pull requests, and token usage, so the result of an agent run is queryable rather than buried in a log stream.

The module targets Go 1.25 and leans on controller-runtime 0.23 with Kubernetes libraries at 0.35. It also pulls in Helm 3.20, cobra for the CLI, bubbletea and lipgloss for terminal UI, gorilla/websocket for the connection pieces, robfig/cron for schedules, and go-github v66 for the GitHub side. The dependency list is a fair map of what the framework actually does.

## Install needs a 1.28+ cluster with cert-manager already in place

The floor is stated before anything else: a Kubernetes 1.28 or newer cluster with cert-manager installed. That is a prerequisite, not a nice-to-have, and it rules out a quick local trial on a default cluster.

Three install routes exist for the CLI, and they differ in how much they trust your toolchain.

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

```bash
brew tap kelos-dev/tap
brew install kelos

# Or:
go install github.com/kelos-dev/kelos/cmd/kelos@latest
```

The curl form pipes a remote script straight into a shell; the Homebrew tap and `go install` routes are pinned by a tap and a module path respectively. Helm installations and upgrades are handled separately through the chart documentation. Once the CLI exists, `kelos install` puts the controller in the cluster.

## The skill route replaces hand-written YAML with a conversation

The recommended path is to stop writing configuration by hand. Installing the first-party skill into your coding agent is one command:

```bash
npx skills add kelos-dev/kelos
```

The skill teaches the agent how to configure Kelos, pick the right resources, operate workloads, and troubleshoot failures. After that you ask for the outcome rather than the manifest, and the agent inspects the cluster, asks for missing choices or credentials, and builds the objects.

The worked prompts in the documentation are worth reading as templates, because they show the shape of a good request: name the Workspace, state the provider, and set expectations about what to confirm before applying.

```text
Using the /kelos skill, create a webhook-based TaskSpawner for GitHub issues
labeled "agent-ready" in your-org/your-repo.

Each task should reproduce the issue, add a tested fix, and open a pull request
without merging it. Limit concurrency to 3 and runtime to 1 hour. Show me the
resources before applying them.
```

That last sentence is the pattern: show the resources, then apply. Two other prompts in the same set tell the agent to ask before creating or replacing any Kubernetes Secret, and to not print Secret values while investigating a failed Task.

## kelos run creates the Task and hands you the name to stream from

The direct CLI path is short enough to be worth knowing even if you use the skill. `kelos init` writes `~/.kelos/config.yaml` with commented placeholders for agent credentials, which you fill in from the generated file rather than guessing field names.

A Workspace needs a repository URL and a ref:

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

Then the Task, with `--watch` to follow it:

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

The command prints the generated Task name, and that name is the handle for everything after it, including `kelos logs TASK_NAME -f` to stream agent logs. Note that the name is generated, not chosen by you, so scripts have to parse it out of the output rather than predict it.

## Sessions apply as example YAML and connect from the terminal

A persistent Session follows the same apply-then-connect shape, except the manifests come from the examples directory. You replace the credential placeholder in the Session example, apply it, and connect:

```bash
kubectl apply -f examples/16-session/
kelos session connect interactive-review
```

The name `interactive-review` is the Session's own name in that example, which is why the second command can name it directly instead of parsing generated output as with a Task.

The optional Console server adds a browser path for inspecting resources and for creating, organizing, and chatting with Sessions. It is configured through a shared token, and the application is cluster-internal rather than exposed publicly. The trade is explicit: a single shared token in front of agent conversations, on a server you have to switch on.

## A TaskSpawner turns any webhook into compute, so concurrency is the real control

Event-driven work is where the operational risk concentrates. `TaskSpawner` creates Tasks from events or schedules, and the sources named include GitHub, Jira, Linear, cron schedules, and generic webhooks. The examples directory backs that up with separate directories for GitHub issues, cron, GitHub webhooks, Linear webhooks, file patterns, generic webhooks, CI remediation, and a webhook gateway.

Because the entry point is an inbound request, the limits are what keep it safe. The webhook prompt pattern sets concurrency to 3 and runtime to 1 hour, and the documentation pairs that with scoped credentials, protected branches, and workload limits for autonomous agents. Task-level budgets have their own example directory as well.

`WorkerPool` is the alternative shape when request volume is steady: reusable workers instead of a new pod per event. `TaskPipeline` covers the ordered case, where stages run in sequence with matrix fan-out across them.

## Six agent providers are supported, plus your own image

The provider list is explicit: Claude Code, OpenAI Codex, Google Gemini, OpenCode, Cursor, and custom agent images described in a separate interface document. The repository layout mirrors that list, with a top-level directory for each of `claude-code/`, `codex/`, `gemini/`, `opencode/`, and `cursor/` alongside `api/`, `cmd/`, `pkg/`, and `internal/`.

The controller images are built from the same layout. The Makefile enumerates `cmd/kelos-controller`, `cmd/kelos-spawner`, `cmd/kelos-worker-runner`, `cmd/kelos-session-runtime`, `cmd/kelos-console-server`, `cmd/ghproxy`, `cmd/kelos-webhook-server`, and `cmd/kelos-slack-server`, published under `ghcr.io/kelos-dev`. So the spawner, the session runtime, and the webhook server are separate binaries, and the gateway proxy exists as its own component.

Release v0.58.0 shipped on 2026-09-28, after v0.57.0 on 2026-09-20 and v0.56.0 on 2026-09-13. The last push on the repository is 2026-10-01, and the project is Apache-2.0 licensed and not archived.

## Conclusion

Kelos fits a team that already runs Kubernetes and wants agent work to inherit the same limits, RBAC, and audit trail as everything else in the cluster, rather than on a developer laptop. Verify three things before adopting it: that you can meet the Kubernetes 1.28+ plus cert-manager floor, that the Console server's shared token is acceptable for how you expose Sessions in a browser, and that your webhook sources carry authentication you trust, since a TaskSpawner turns any inbound request into compute. For a single task on one machine, the CLI is heavier than the agent itself.

## FAQ

### What cluster requirements does Kelos have before I install it?

A Kubernetes 1.28 or newer cluster with cert-manager installed. Both are stated as prerequisites in the quick start, ahead of the CLI install. After the CLI is in place, kelos install puts the controller into the cluster.

### What are the main Kelos resource kinds and what does each one do?

A Task runs one agent job, a TaskPipeline runs ordered Task stages with matrix fan-out, a Session keeps an interactive conversation running, a Workspace gives agents a Git repository, and an AgentConfig shares instructions, skills, plugins and MCP servers. TaskSpawner and SessionSpawner create work from events or schedules, and WorkerPool maintains reusable agents.

### Which coding agents can Kelos run?

Claude Code, OpenAI Codex, Google Gemini, OpenCode, Cursor, and custom agent images built to a documented interface. Finished Task status records branches, commits, pull requests, and token usage.

### How do I keep webhook-triggered Kelos Tasks from running away?

Set concurrency and runtime limits on the TaskSpawner, as in the documented pattern that caps concurrency at 3 and runtime at 1 hour. The guidance pairs those limits with scoped credentials, protected branches, and workload limits for autonomous agents.

### Does Kelos need me to write Kubernetes manifests by hand?

Not if you install the first-party skill with npx skills add kelos-dev/kelos. The skill teaches your coding agent to configure Kelos, create the right resources, operate workloads, and troubleshoot failures, so you describe the outcome instead of assembling YAML and CLI commands.

## Sources

- [Issues](https://github.com/kelos-dev/kelos/issues)
- [kelos-dev/kelos on GitHub](https://github.com/kelos-dev/kelos)
- [License: Apache-2.0](https://github.com/kelos-dev/kelos/blob/main/LICENSE)
- [README](https://github.com/kelos-dev/kelos/blob/main/README.md)
- [Releases](https://github.com/kelos-dev/kelos/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/kelos-dev-kelos