kelos-dev/kelos

Kelos – Running AI‑powered coding agents on Kubernetes

What it is – Kelos is an open‑source control plane that turns coding agents (LLM‑backed code generators such as Claude Code, OpenAI Codex, Google Gemini, etc.) into first‑class Kubernetes workloads. It defines a set of custom Kubernetes resources (Task, Session, Workspace, AgentConfig, …) that describe what the agent should do, where its code lives, and how it should be run. A controller watches those resources and creates the appropriate Pods, Jobs, or StatefulSets, handling credentials, repository checkout, tool installation, and lifecycle management.

Why it matters – Developers often run LLM‑based code assistants on their local machines, which limits scalability, isolation, and observability. Kelos moves the execution to a Kubernetes cluster, giving you:

• Isolation – each agent runs in its own pod with its own secrets and resource limits.
• Reusability – the same Workspace, AgentConfig, and skill set can be reused across many Tasks or Sessions.
• Automation – Tasks can be spawned automatically from GitHub, Jira, Linear, cron, or generic webhooks.
• Observability & control – because everything is a native K8s object you can inspect, version‑control, and apply standard policies (RBAC, quotas, etc.).

Core concepts

Resource	Role
Workspace	Links a Git repository (and optional ref) to the cluster, providing the code base the agent will work on.
AgentConfig	Stores the LLM provider credentials, prompts, plugins, and optional MCP (model‑control‑plane) servers.
Task	A one‑off job: run an agent with a single prompt, wait for completion, and capture results (commits, PRs, token usage).
Session	A long‑running, interactive conversation with an agent that can be re‑attached from a terminal or web UI.
TaskSpawner / SessionSpawner	Declarative objects that create Tasks or Sessions in response to events (webhooks, schedules).
WorkerPool	Keeps a pool of ready‑to‑run agent containers to reduce cold‑start latency.

How it works – The Kelos controller watches the custom resources and translates them into Kubernetes workloads:

1. Workspace → clones the repo into a shared PersistentVolume.
2. AgentConfig → injects credentials as Secrets and mounts the selected LLM provider image.
3. Task → creates a Job that runs the agent container with the supplied prompt.
4. Session → creates a StatefulSet plus a side‑car web‑socket server so you can chat with the agent over the Kelos Console or CLI.
5. Spawner objects watch external sources (GitHub webhooks, CronJobs) and automatically generate the above resources.

Getting started (from the README)

# 1. Have a K8s 1.28+ cluster with cert‑manager installed
# 2. Install the Kelos CLI
curl -fsSL https://raw.githubusercontent.com/kelos-dev/kelos/main/hack/install.sh | bash
# or via Homebrew / go install

# 3. Deploy the controller into the cluster
kelos install   # installs the Helm chart

# 4. Add a coding‑agent skill to your LLM (example for a Node‑based skill)
npx skills add kelos-dev/kelos

# 5. Create a Workspace pointing at a repo
kelos create workspace my-workspace \
  --repo https://github.com/your-org/your-repo.git \
  --ref main

# 6. Run a one‑off Task
kelos run \
  --workspace my-workspace \
  --prompt "Add a hello world program in Python" \
  --watch

# 7. (Optional) Open an interactive Session via the web console
kelos session connect interactive-review

The CLI also supports kelos logs, kelos init for config scaffolding, and kelos create … for the other resource types.

Typical use cases

• Developer‑guided work – start a Session, let the agent draft code, then reconnect later to review or continue.
• Event‑driven automation – automatically create a Task when a GitHub issue gets the label agent-ready; the agent reproduces the bug, writes a fix, and opens a PR.
• Agent pipelines – chain Tasks (implement → test → review) using TaskSpawner to build CI‑style workflows driven by LLMs.
• Repository fleets – fan‑out the same change across dozens of micro‑services by spawning parallel Tasks.
• Self‑development loops – let a specialized agent continuously triage, implement, and maintain a project (the Kelos repo itself demonstrates this).

Where to learn more – The repository ships extensive docs:

• docs/reference.md – API spec and CLI flags.
• examples/ – ready‑to‑apply YAML patterns for Tasks, Sessions, spawners, etc.
• docs/integration.md – wiring GitHub, Jira, Linear, and generic webhooks.
• docs/agent-image-interface.md – how to build custom container images that expose a standard LLM‑agent interface.
• Helm chart docs for installation and upgrades.

License – Apache License 2.0.