Kelos

Run and orchestrate coding agents on Kubernetes.

How It Works · Quick Start · Usage · Documentation · Contributing

Kelos turns coding agents into Kubernetes workloads. Give an agent a goal and Kelos provides the repository, credentials, tools, compute, and workflow needed to complete it.

Use Kelos for one-off tasks, persistent conversations, event-driven automation, pipelines, and parallel work across many repositories. It supports Claude Code, OpenAI Codex, Google Gemini, OpenCode, Cursor, and custom agent images.

Set up the Kelos Console

Why Kelos?

• Run agents in isolated Kubernetes workloads instead of on developer laptops.
• Reuse the same repositories, instructions, skills, and tools across agents.
• Keep interactive Sessions alive and reconnect from terminal or web clients.
• Trigger work from GitHub, Jira, Linear, cron schedules, or generic webhooks.
• Observe, limit, and operate agent workloads with familiar Kubernetes controls.

How It Works

The controller turns Kelos resources into Pods, Jobs, and StatefulSets.

Core Primitives

Task status records useful results such as branches, commits, pull requests, and token usage. The resources remain ordinary Kubernetes objects, so advanced users can review them, keep them in Git, or manage them with existing delivery tools.

See the API and CLI reference for the underlying fields and commands.

Quick Start

You need a Kubernetes 1.28+ cluster with cert-manager installed.

Install the CLI:

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

Homebrew and source installs are also available:

brew tap kelos-dev/tap
brew install kelos

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

Install Kelos:

kelos install

For Helm installations and upgrades, see the chart documentation.

Install the first-party Kelos skill in your coding agent:

npx skills add kelos-dev/kelos

The skill teaches your agent how to configure Kelos, create the right resources, operate workloads, and troubleshoot failures. You can now use Kelos without writing configuration files or assembling CLI commands by hand.

Usage

Use the Kelos skill

Ask your coding agent to use the /kelos skill. Describe the outcome you want, the agent provider, and the repository; the skill handles the Kelos resources and commands.

Set up a repository

Using the /kelos skill, configure Kelos on my current cluster for OpenAI Codex
and https://github.com/your-org/your-repo.

Name the Workspace my-workspace. Use my existing local Codex OAuth credentials.
Ask before creating or replacing any Kubernetes Secret, then verify the setup
with a small read-only Task.

Create your first Task

Using the /kelos skill, create a Codex Task in my-workspace with this
prompt: "Add a hello world program in Python."

Run the Task, watch it until it finishes, and show me the logs and result.

Start a persistent session

Using the /kelos skill, create a persistent Codex Session named my-session for
my-workspace, then connect me to it.

Automate issue fixes

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.

Build your own self-development setup

Using the /kelos skill, use this repository's self-development/ setup as a
reference and create a minimal self-development setup for
https://github.com/your-org/your-repo.

Start with issue pick-up and pull request review. Reuse shared configuration,
prefer GitHub webhooks, and show me the resources before applying them.

Troubleshoot a failed workload

Using the /kelos skill, investigate why Task my-task failed in the default
namespace. Do not print Secret values. Fix configuration problems if it is safe
to do so, then retry and watch the Task.

These prompts are starting points. Your agent will inspect the cluster and ask for missing choices or credentials when needed.

Use scoped credentials, protected branches, and workload limits for autonomous agents.

Use the CLI directly

Initialize ~/.kelos/config.yaml, then add your agent credentials using the comments in the generated file:

kelos init

Create a Workspace

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

Create a Task

Create and watch a Task in that Workspace:

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

The command prints the generated Task name. Use it to stream the agent logs:

kelos logs TASK_NAME -f

Start a Session

Replace the credential placeholder in the Session example, then apply and connect to it:

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

Use the Kelos Console

To inspect Kelos resources and create, organize, and chat with Sessions in a browser, enable the optional Console server. Follow the Kelos Console guide to configure its shared token and access the cluster-internal web application.

See the configuration reference for other agents and authentication options.

What You Can Build

• Developer-guided work: reconnect to a long-running Session from a terminal or browser.
• Event-driven workers: turn issues, pull requests, webhooks, and schedules into agent Tasks.
• Agent pipelines: sequence implementation, review, testing, and delivery.
• Repository fleets: fan out the same change across many services.
• Self-development loops: let specialized agents triage, implement, review, and maintain a project continuously.

Kelos uses Kelos to develop itself. The self-development setup shows the agents and workflows running the project.

Documentation

Development

Use the project Makefile:

make update
make verify
make test
make test-integration
make build

See the contributing guide for development setup and pull request requirements.

License

Apache License 2.0