Development
Plugin
kelos
Kelos - The Kubernetes-native framework for orchestrating autonomous AI coding agents.
Plugin Signal67/100Solid
maintained100
capable14
documented100
adopted52
Install
$ npx -y skills add kelos-dev/kelos --agent claude-code
Run the curl in your terminal, the rest in Claude Code.
Stats
292
Stars
33
Forks
Active
Maintenance
Go
Language
Apache-2.0
License
1h ago
Last commit
6mo ago
Created
Repo: kelos-dev/kelos
What's inside
README
1Kelos 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.
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
| Resource | Purpose |
|---|---|
Task | Run one agent job |
Session | Keep an interactive agent conversation running |
Workspace | Give agents a Git repository |
AgentConfig | Share instructions, skills, plugins, and MCP servers |
TaskSpawner | Create Tasks from events or schedules |
SessionSpawner | Create Sessions from GitHub webhooks |
WorkerPool | Maintain reusable agent workers |
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 Session web chat
To create, organize, and chat with Sessions in a browser, enable the optional Session server. Follow the Session web chat 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
| Need | Documentation |
|---|---|
| Resource fields and CLI commands | Reference |
| Ready-to-apply patterns | Examples |
| GitHub, Jira, CI, and webhook connections | Integration guide |
| Interactive Sessions | Session example and web chat guide |
| Custom agent containers | Agent image interface |
| Helm installation and upgrades | Chart documentation |
| Contributing | Contributing guide |
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
File tree
624kelos-dev/kelosView on GitHub
.github/
PULL_REQUEST_TEMPLATE.md
workflows/
ci.yaml
deploy-dev.yaml
e2e-anchor.yaml
fork-e2e.yaml
label.yaml
refresh-codex-auth.yaml
release.yaml
reusable-e2e.yaml
run-fake-strategist.yaml
update-homebrew-formula.yaml
.gitignore
.yamlfmt
AGENTS.md
api/
v1alpha1/
agentconfig_types.go
groupversion_info.go
task_types.go
taskspawner_types.go
workspace_types.go
zz_generated.deepcopy.go
v1alpha2/
agentconfig_types.go
groupversion_info.go
session_types.go
sessionspawner_types.go
spawner_types.go
task_types.go
taskbudget_types.go
taskrecord_types.go
taskspawner_types.go
workerpool_types.go
workspace_types.go
zz_generated.deepcopy.go
claude-code/
Dockerfile
kelos_entrypoint.sh
CLAUDE.md
cmd/
ghproxy/
Dockerfile
main_test.go
main.go
metrics_test.go
metrics.go
kelos/
kelos-capture/
main.go
kelos-codex-auth-refresh/
main.go
kelos-controller/
Dockerfile
main_test.go
main.go
kelos-session-runtime/
Dockerfile
main.go
kelos-session-server/
Dockerfile
main_test.go
main.go
kelos-slack-server/
Dockerfile
main.go
kelos-spawner/
Dockerfile
main_test.go
main.go
metrics_test.go
metrics.go
reconciler.go
kelos-webhook-server/
Dockerfile
main.go
reporting_test.go
reporting.go
kelos-worker-runner/
Dockerfile
main.go
main_test.go
main.go
codex/
Dockerfile
kelos_entrypoint.sh
CONTRIBUTING.md
cursor/
Dockerfile
kelos_entrypoint.sh
docs/
agent-image-interface.md
images/
kelos-resources.png
kelos-session-web-chat.png
integration.md
reference.md
examples/
01-simple-task/
README.md
secret.yaml
task.yaml
02-task-with-workspace/
credentials-secret.yaml
github-token-secret.yaml
README.md
task.yaml
workspace.yaml
03-taskspawner-github-issues/
credentials-secret.yaml
github-token-secret.yaml
README.md
taskspawner.yaml
workspace.yaml
04-taskspawner-cron/
credentials-secret.yaml
github-token-secret.yaml
README.md
taskspawner.yaml
workspace.yaml
05-task-with-agentconfig/
agentconfig.yaml
credentials-secret.yaml
github-token-secret.yaml
README.md
task.yaml
workspace.yaml
06-fork-workflow/
README.md
taskspawner.yaml
workspace.yaml
07-task-pipeline/
credentials-secret.yaml
github-token-secret.yaml
pipeline.yaml
README.md
workspace.yaml
08-task-with-kelos-skill/
agentconfig.yaml
README.md
task.yaml
09-bedrock-credentials/
README.md
secret.yaml
task-irsa.yaml
task.yaml
10-taskspawner-github-webhook/
README.md
taskspawner.yaml
11-taskspawner-linear-webhook/
README.md
taskspawner.yaml
12-taskspawner-file-patterns/
README.md
taskspawner-pr-review.yaml
taskspawner-webhook.yaml
13-taskspawner-generic-webhook/
README.md
taskspawner.yaml
14-task-budget/
README.md
taskbudget.yaml
15-workerpool/
credentials-secret.yaml
github-token-secret.yaml
README.md
task-with-pool.yaml
taskspawner-with-pool.yaml
workerpool.yaml
workspace.yaml
16-session/
credentials-secret.yaml
README.md
session.yaml
workspace.yaml
17-taskspawner-ci-remediation/
README.md
taskspawner.yaml
gateway-api-webhook.md
helm-values-webhook.yaml
README.md
webhook-concurrency.md
webhook-gateway-values.yaml
Formula/
kelos.rb
gemini/
Dockerfile
kelos_entrypoint.sh
go.mod
go.sum
hack/
agent-gh-wrapper.sh
boilerplate.go.txt
install.sh
release-notes/
main_test.go
main.go
retry-ghcr_test.sh
retry-ghcr.sh
update-codegen.sh
update-homebrew-formula.sh
update-install-manifest.sh
verify.sh
internal/
admission/
taskbudget.go
capture/
capture_test.go
capture.go
usage_test.go
usage.go
claudecode/
result_test.go
result.go
cli/
agentconfig_compat_test.go
agentconfig_compat.go
client.go
completion_test.go
completion.go
config_test.go
config.go
confirm_test.go
confirm.go
create_agentconfig.go
create.go
delete_agentconfig.go
delete_session_test.go
delete_session.go
delete_workerpool_test.go
delete_workerpool.go
delete.go
dryrun_test.go
get_agentconfig.go
get_session_test.go
get_session.go
get_test.go
get_workerpool.go
get.go
helpers_test.go
helpers.go
init_test.go
init.go
install_compat_test.go
install_test.go
install.go
logparser_codex_test.go
logparser_codex.go
logparser_gemini_test.go
logparser_gemini.go
logparser_opencode_test.go
logparser_opencode.go
logparser_test.go
logparser.go
logs_test.go
logs.go
mcp_test.go
printer_test.go
printer.go
root.go
run_from_taskspawner_test.go
run_from_taskspawner.go
run_test.go
run.go
session_reconnect_test.go
session_reset_test.go
session_reset.go
session_terminal_background_other.go
session_terminal_background_unix_test.go
session_terminal_background_unix.go
session_terminal_background.go
session_terminal_test.go
session_terminal_tui_test.go
session_terminal_tui.go
session_terminal.go
session_test.go
session.go
suspend_test.go
suspend.go
version.go
webhook_test.go
codexauth/
refresher_test.go
refresher.go
contextfetch/
fetcher_test.go
fetcher.go
controller/
agent_command_test.go
agent_command.go
agentconfig_merge_test.go
agentconfig_merge.go
agentconfig_test.go
agentconfig.go
branch_locker_test.go
branch_locker.go
budget_reconcilers_test.go
codex_auth_refresher_builder.go
codex_auth_refresher_controller_test.go
codex_auth_refresher_controller.go
entrypoint_test.go
github_token_secret.go
job_builder_test.go
job_builder.go
metrics_test.go
metrics.go
output_parser_test.go
output_parser.go
session_controller_test.go
session_controller.go
session_runtime_access_test.go
session_runtime_access.go
sessionspawner_controller_test.go
sessionspawner_controller.go
task_budget_admission_test.go
task_budget_admission.go
task_controller_test.go
task_controller.go
taskbudget_controller.go
taskrecord_controller.go
taskspawner_controller_test.go
taskspawner_controller.go
taskspawner_deployment_builder_test.go
taskspawner_deployment_builder.go
workerpool_controller_test.go
workerpool_controller.go
workspace_controller_test.go
workspace_controller.go
workspace_ghproxy_builder.go
conversion/
agentconfig_test.go
agentconfig.go
converters_test.go
converters.go
json.go
task_test.go
task.go
taskspawner_test.go
taskspawner.go
workspace.go
examples/
self_development_test.go
githubapp/
token_test.go
token.go
helmchart/
render_test.go
render.go
logging/
verbosity_test.go
verbosity.go
manifests/
charts/
kelos/
Chart.yaml
charts/
kelos-crds/
Chart.yaml
templates/
agentconfig-crd.yaml
session-crd.yaml
sessionspawner-crd.yaml
task-crd.yaml
taskbudget-crd.yaml
taskrecord-crd.yaml
taskspawner-crd.yaml
workerpool-crd.yaml
workspace-crd.yaml
values.yaml
README.md
templates/
cronjob.yaml
deployment.yaml
namespace.yaml
podmonitor.yaml
rbac.yaml
serviceaccount.yaml
session-server.yaml
slack-server-configmap.yaml
slack-server.yaml
validating-webhook.yaml
webhook-gateway.yaml
webhook-ingress.yaml
webhook-server.yaml
webhook.yaml
values.yaml
install-crd.yaml
manifests.go
reporting/
activity_test.go
activity.go
checks_test.go
checks.go
github_test.go
github.go
progress_test.go
progress.go
slack_blocks_test.go
slack_blocks.go
... 343 moreFAQ
kelos is a Claude Code plugin with 1 hand-picked skill for development work, indexed on Flowy. Install it with the command on its page. It includes kelos. Its skills do not fire on their own yet. Request auto-invocation to have Flowy route them as you prompt. Free and open source.
- What is kelos?
- Kelos - The Kubernetes-native framework for orchestrating autonomous AI coding agents.
- How do I install kelos?
- Run these in Claude Code: npx -y skills add kelos-dev/kelos --agent claude-code. Then prompt normally.
- Does kelos auto-invoke its skills?
- Not yet. It is indexed on Flowy as a plain plugin. Request auto-invocation on its page and Flowy will route its skills for you as you prompt.
- Is kelos free?
- Yes. Flowy is free and open source, with nothing gated. You can read every skill in full before you install.