{"id":46128056,"url":"https://github.com/kelos-dev/kelos","last_synced_at":"2026-04-06T01:19:49.984Z","repository":{"id":336619133,"uuid":"1147022845","full_name":"kelos-dev/kelos","owner":"kelos-dev","description":"The Kubernetes-native framework for orchestrating autonomous AI coding agents.","archived":false,"fork":false,"pushed_at":"2026-02-27T17:24:45.000Z","size":991,"stargazers_count":48,"open_issues_count":65,"forks_count":8,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-27T18:44:01.138Z","etag":null,"topics":["agentic-ai","agentic-coding","ai","ai-agents","ci-cd","claude","claude-code","codex","gemini","kubernetes","kubernetes-operator","opencode"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kelos-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-01T04:03:17.000Z","updated_at":"2026-02-27T17:24:48.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/kelos-dev/kelos","commit_stats":null,"previous_names":["gjkim42/axon","axon-core/axon","kelos-dev/kelos"],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/kelos-dev/kelos","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kelos-dev%2Fkelos","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kelos-dev%2Fkelos/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kelos-dev%2Fkelos/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kelos-dev%2Fkelos/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kelos-dev","download_url":"https://codeload.github.com/kelos-dev/kelos/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kelos-dev%2Fkelos/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29991309,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-02T01:47:34.672Z","status":"online","status_checked_at":"2026-03-02T02:00:07.342Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-ai","agentic-coding","ai","ai-agents","ci-cd","claude","claude-code","codex","gemini","kubernetes","kubernetes-operator","opencode"],"created_at":"2026-03-02T03:07:54.057Z","updated_at":"2026-04-02T20:46:17.083Z","avatar_url":"https://github.com/kelos-dev.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003eKelos\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\u003cstrong\u003eOrchestrate autonomous AI coding agents on Kubernetes.\u003c/strong\u003e\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/kelos-dev/kelos/actions/workflows/ci.yaml\"\u003e\u003cimg src=\"https://github.com/kelos-dev/kelos/actions/workflows/ci.yaml/badge.svg\" alt=\"CI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/kelos-dev/kelos/releases/latest\"\u003e\u003cimg src=\"https://img.shields.io/github/v/release/kelos-dev/kelos\" alt=\"Release\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/kelos-dev/kelos\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/kelos-dev/kelos?style=flat\" alt=\"GitHub Stars\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/kelos-dev/kelos\"\u003e\u003cimg src=\"https://img.shields.io/github/go-mod/go-version/kelos-dev/kelos\" alt=\"Go Version\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-Apache%202.0-blue.svg\" alt=\"License\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#quick-start\"\u003eQuick Start\u003c/a\u003e \u0026middot;\n  \u003ca href=\"#kelos-skill\"\u003eKelos Skill\u003c/a\u003e \u0026middot;\n  \u003ca href=\"#kelos-developing-kelos\"\u003eKelos Developing Kelos\u003c/a\u003e \u0026middot;\n  \u003ca href=\"#examples\"\u003eExamples\u003c/a\u003e \u0026middot;\n  \u003ca href=\"docs/integration.md\"\u003eIntegration\u003c/a\u003e \u0026middot;\n  \u003ca href=\"docs/reference.md\"\u003eReference\u003c/a\u003e \u0026middot;\n  \u003ca href=\"examples/\"\u003eYAML Manifests\u003c/a\u003e\n\u003c/p\u003e\n\nKelos lets you **define your development workflow as Kubernetes resources** and run it continuously. Declare what triggers agents, what they do, and how they hand off — Kelos handles the rest.\n\nKelos develops Kelos through seven TaskSpawners run 24/7: triaging issues, planning implementations, fixing bugs, responding to PR feedback, testing DX, brainstorming improvements, and tuning their own prompts. [See the full pipeline below.](#kelos-developing-kelos)\n\nSupports **Claude Code**, **OpenAI Codex**, **Google Gemini**, **OpenCode**, **Cursor**, and [custom agent images](docs/agent-image-interface.md).\n\n## How It Works\n\nKelos orchestrates the flow from external events to autonomous execution:\n\n\u003cimg width=\"2310\" height=\"1582\" alt=\"kelos-resources\" src=\"https://github.com/user-attachments/assets/a03c388e-cc28-4a25-972f-e0e506b4d583\" /\u003e\n\nYou define what needs to be done, and Kelos handles the \"how\" — from cloning the right repo and injecting credentials to running the agent and capturing its outputs (branch names, commit SHAs, PR URLs, and token usage).\n\n### Core Primitives\n\nKelos is built on four resources:\n\n1. **Tasks** — Ephemeral units of work that wrap an AI agent run.\n2. **Workspaces** — Persistent or ephemeral environments (git repos) where agents operate.\n3. **AgentConfigs** — Reusable bundles of agent instructions (`AGENTS.md`, `CLAUDE.md`), plugins (skills and agents), and MCP servers.\n4. **TaskSpawners** — Orchestration engines that react to external triggers (GitHub, Cron) to automatically manage agent lifecycles.\n\n\u003cdetails\u003e\n\u003csummary\u003eTaskSpawner — Automatic Task Creation from External Sources\u003c/summary\u003e\n\nTaskSpawner watches external sources (e.g., GitHub Issues) and automatically creates Tasks for each discovered item.\n\n```\n                    polls         new issues\n TaskSpawner ─────────────▶ GitHub Issues\n      │        ◀─────────────\n      │\n      ├──creates──▶ Task: fix-bugs-1\n      └──creates──▶ Task: fix-bugs-2\n```\n\n\u003c/details\u003e\n\n## Kelos Developing Kelos\n\nKelos develops itself. Seven TaskSpawners run 24/7, each handling a different part of the development lifecycle — fully autonomous.\n\n\u003cimg width=\"2694\" height=\"1966\" alt=\"kelos-self-development\" src=\"https://github.com/user-attachments/assets/a205f0c6-9eb4-4001-8ee6-5c8ab187fbea\" /\u003e\n\n| TaskSpawner | Trigger | Model | Description |\n|---|---|---|---|\n| **kelos-workers** | GitHub Issues (`actor/kelos`) | Opus | Picks up issues, creates or updates PRs, self-reviews, and ensures CI passes |\n| **kelos-pr-responder** | GitHub Pull Requests (`generated-by-kelos`, `changes_requested`) | Opus | Re-engages on PR review feedback and updates the existing branch incrementally |\n| **kelos-planner** | GitHub Issues (`/kelos plan` comment) | Opus | Investigates an issue and posts a structured implementation plan — advisory only, no code changes |\n| **kelos-triage** | GitHub Issues (`needs-actor`) | Opus | Classifies issues by kind/priority, detects duplicates, and recommends an actor |\n| **kelos-fake-user** | Cron (daily 09:00 UTC) | Sonnet | Tests DX as a new user — follows docs, tries CLI workflows, files issues for problems found |\n| **kelos-fake-strategist** | Cron (every 12 hours) | Opus | Explores new use cases, workflow improvements, and integration opportunities |\n| **kelos-self-update** | Cron (daily 06:00 UTC) | Opus | Reviews and tunes prompts, configs, and workflow files — the pipeline improves itself |\n\nHere's a trimmed snippet of `kelos-workers.yaml` — enough to show the pattern:\n\n```yaml\napiVersion: kelos.dev/v1alpha1\nkind: TaskSpawner\nmetadata:\n  name: kelos-workers\nspec:\n  when:\n    githubIssues:\n      labels: [actor/kelos]\n      excludeLabels: [kelos/needs-input]\n      priorityLabels:\n        - priority/critical-urgent\n        - priority/important-soon\n      pollInterval: 1m\n  maxConcurrency: 3\n  taskTemplate:\n    model: opus\n    type: claude-code\n    branch: \"kelos-task-{{.Number}}\"\n    promptTemplate: |\n      You are a coding agent. You either\n      - create a PR to fix the issue\n      - update an existing PR to fix the issue\n      - comment on the issue or the PR if you cannot fix it\n      ...\n```\n\nThe key pattern is `excludeLabels: [kelos/needs-input]` — this creates a feedback loop where the agent works autonomously until it needs human input, then pauses. Removing the label re-queues the issue on the next poll.\n\nSee the full manifest at [`self-development/kelos-workers.yaml`](self-development/kelos-workers.yaml) and the [`self-development/` README](self-development/README.md) for setup instructions.\n\n## Why Kelos?\n\nAI coding agents are evolving from interactive CLI tools into autonomous background workers — managed like infrastructure, not invoked like commands. Kelos provides the framework to manage this transition at scale.\n\n- **Workflow as YAML** — Define your development workflow declaratively: what triggers agents, what they do, and how they hand off. Version-control it, review it in PRs, and GitOps it like any other infrastructure.\n- **Orchestration, not just execution** — Don't just run an agent; manage its entire lifecycle. Chain tasks with `dependsOn` and pass results (branch names, PR URLs, token usage) between pipeline stages. Use `TaskSpawner` to build event-driven workers that react to GitHub issues, PRs, or schedules.\n- **Host-isolated autonomy** — Each task runs in an isolated, ephemeral Pod with a freshly cloned git workspace. Agents have no access to your host machine — use [scoped tokens and branch protection](#security-considerations) to control repository access.\n- **Standardized interface** — Plug in any agent (Claude, Codex, Gemini, OpenCode, Cursor, or your own) using a simple [container interface](docs/agent-image-interface.md). Kelos handles credential injection, workspace management, and Kubernetes plumbing.\n- **Scalable parallelism** — Fan out agents across multiple repositories. Kubernetes handles scheduling, resource management, and queueing — scale is limited by your cluster capacity and API provider quotas.\n- **Observable \u0026 CI-native** — Every agent run is a first-class Kubernetes resource with deterministic outputs (branch names, PR URLs, commit SHAs, token usage) captured into status. Monitor via `kubectl`, manage via the `kelos` CLI or declarative YAML (GitOps-ready), and integrate with ArgoCD or GitHub Actions.\n\n## Quick Start\n\nGet running in 5 minutes (most of the time is gathering credentials).\n\n### Prerequisites\n\n- Kubernetes cluster (1.28+)\n\n\u003cdetails\u003e\n\u003csummary\u003eDon't have a cluster? Create one locally with kind\u003c/summary\u003e\n\n1. [Install kind](https://kind.sigs.k8s.io/docs/user/quick-start/#installation) (requires Docker)\n2. Create a cluster:\n   ```bash\n   kind create cluster\n   ```\n\nThis creates a single-node cluster and configures your kubeconfig automatically.\n\n\u003c/details\u003e\n\n### 1. Install the CLI\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/kelos-dev/kelos/main/hack/install.sh | bash\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eAlternative: install from source\u003c/summary\u003e\n\n```bash\ngo install github.com/kelos-dev/kelos/cmd/kelos@latest\n```\n\n\u003c/details\u003e\n\n### 2. Install Kelos\n\n```bash\nkelos install\n```\n\nThis installs the Kelos controller and CRDs into the `kelos-system` namespace.\n\nVerify the installation:\n\n```bash\nkubectl get pods -n kelos-system\nkubectl get crds | grep kelos.dev\n```\n\n### Helm Install\n\nKelos also publishes a Helm chart as an OCI artifact in GHCR.\n\nTo install Kelos with Helm:\n\n```bash\nhelm upgrade --install kelos oci://ghcr.io/kelos-dev/charts/kelos \\\n  -n kelos-system \\\n  --create-namespace \\\n  --version \u003cversion\u003e\n```\n\nThis installs the controller and, by default, the Kelos CRDs.\n\nFor CRD migration, adopting existing CRDs into Helm ownership, and advanced chart usage, see [the Helm chart README](internal/manifests/charts/kelos/README.md).\n\n### 3. Initialize Your Config\n\n```bash\nkelos init\n```\n\nEdit `~/.kelos/config.yaml`:\n\n```yaml\noauthToken: \u003cyour-oauth-token\u003e\nworkspace:\n  repo: https://github.com/your-org/your-repo.git\n  ref: main\n  token: \u003cgithub-token\u003e  # optional, for private repos and pushing changes\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eHow to get your credentials\u003c/summary\u003e\n\n**Claude OAuth token** (recommended for Claude Code):\nRun `claude setup-token` locally and follow the prompts. This generates a long-lived token (valid for ~1 year). Copy the token from `~/.claude/credentials.json`.\n\n**Anthropic API key** (alternative for Claude Code):\nCreate one at [console.anthropic.com](https://console.anthropic.com). Set `apiKey` instead of `oauthToken` in your config.\n\n**Codex OAuth credentials** (for OpenAI Codex):\nRun `codex auth login` locally, then reference the auth file in your config:\n```yaml\noauthToken: \"@~/.codex/auth.json\"\ntype: codex\n```\nOr set `apiKey` with an OpenAI API key instead.\n\n**GitHub token** (for pushing branches and creating PRs):\nCreate a [Personal Access Token](https://github.com/settings/tokens) with `repo` scope (and `workflow` if your repo uses GitHub Actions).\n\n**GitHub App** (recommended for production/org use):\nFor organizations, [GitHub Apps](https://docs.github.com/en/apps) are preferred over PATs — they offer fine-grained permissions, higher rate limits, and don't depend on a specific user account. Use `githubApp` instead of `token` in your workspace config:\n```yaml\nworkspace:\n  repo: https://github.com/your-org/repo.git\n  ref: main\n  githubApp:\n    appID: \"12345\"\n    installationID: \"67890\"\n    privateKeyPath: ~/.config/my-app.private-key.pem\n```\nSee the [Workspace reference](docs/reference.md#workspace) for details.\n\n\u003c/details\u003e\n\n\u003e **Warning:** Without a workspace, the agent runs in an ephemeral pod — any files it creates are lost when the pod terminates. Always set up a workspace to get persistent results.\n\n### 4. Run Your First Task\n\n```bash\n$ kelos run -p \"Add a hello world program in Python\"\ntask/task-r8x2q created\n\n$ kelos logs task-r8x2q -f\n```\n\nThe task name (e.g. `task-r8x2q`) is auto-generated. Use `--name` to set a custom name, or `-w` to watch task status after creation. To stream agent logs, run `kelos logs \u003ctask-name\u003e -f`.\n\nThe agent clones your repo, makes changes, and can push a branch or open a PR.\n\n\u003e **Tip:** If something goes wrong, check the controller logs with\n\u003e `kubectl logs deployment/kelos-controller-manager -n kelos-system`.\n\n\u003cdetails\u003e\n\u003csummary\u003eUsing kubectl and YAML instead of the CLI\u003c/summary\u003e\n\nCreate a `Workspace` resource to define a git repository:\n\n```yaml\napiVersion: kelos.dev/v1alpha1\nkind: Workspace\nmetadata:\n  name: my-workspace\nspec:\n  repo: https://github.com/your-org/your-repo.git\n  ref: main\n```\n\nThen reference it from a `Task`:\n\n```yaml\napiVersion: kelos.dev/v1alpha1\nkind: Task\nmetadata:\n  name: hello-world\nspec:\n  type: claude-code\n  prompt: \"Create a hello world program in Python\"\n  credentials:\n    type: oauth\n    secretRef:\n      name: claude-oauth-token\n  workspaceRef:\n    name: my-workspace\n```\n\n```bash\nkubectl apply -f workspace.yaml\nkubectl apply -f task.yaml\nkubectl get tasks -w\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eUsing an API key instead of OAuth\u003c/summary\u003e\n\nSet `apiKey` instead of `oauthToken` in `~/.kelos/config.yaml`:\n\n```yaml\napiKey: \u003cyour-api-key\u003e\n```\n\nOr pass `--secret` to `kelos run` with a pre-created secret (api-key is the default credential type), or set `spec.credentials.type: api-key` in YAML.\n\n\u003c/details\u003e\n\n## Kelos Skill\n\nThe [Kelos skill](skills/kelos/) teaches AI coding agents how to author and operate Kelos resources. Install it via [skills.sh](https://skills.sh):\n\n```bash\nnpx skills add kelos-dev/kelos\n```\n\nThen ask your agent:\n\n```\nUsing the /kelos skill, set up a TaskSpawner that watches GitHub issues\nlabeled \"bug\" and auto-creates Tasks to fix them.\n```\n\nThe agent will generate the correct manifests, apply them, and troubleshoot any issues on your behalf.\n\n## Examples\n\n### Auto-fix GitHub issues with TaskSpawner\n\nCreate a TaskSpawner to automatically turn GitHub issues into agent tasks:\n\n```yaml\napiVersion: kelos.dev/v1alpha1\nkind: TaskSpawner\nmetadata:\n  name: fix-bugs\nspec:\n  when:\n    githubIssues:\n      labels: [bug]\n      state: open\n      pollInterval: 5m\n  taskTemplate:\n    type: claude-code\n    workspaceRef:\n      name: my-workspace\n    credentials:\n      type: oauth\n      secretRef:\n        name: claude-oauth-token\n    promptTemplate: \"Fix: {{.Title}}\\n{{.Body}}\"\n```\n\n```bash\nkubectl apply -f taskspawner.yaml\n```\n\nTaskSpawner polls for new issues matching your filters and creates a Task for each one.\n\n### Chain tasks into pipelines\n\nUse `dependsOn` to chain tasks into pipelines. A task in `Waiting` phase stays paused until all its dependencies succeed:\n\n```bash\nkelos run -p \"Scaffold a new user service\" --name scaffold --branch feature/user-service\nkelos run -p \"Write tests for the user service\" --depends-on scaffold --branch feature/user-service\n```\n\nTasks sharing the same `branch` are serialized automatically — only one runs at a time.\n\n\u003cdetails\u003e\n\u003csummary\u003eYAML equivalent\u003c/summary\u003e\n\n```yaml\napiVersion: kelos.dev/v1alpha1\nkind: Task\nmetadata:\n  name: scaffold\nspec:\n  type: claude-code\n  prompt: \"Scaffold a new user service with CRUD endpoints\"\n  credentials:\n    type: oauth\n    secretRef:\n      name: claude-oauth-token\n  workspaceRef:\n    name: my-workspace\n  branch: feature/user-service\n---\napiVersion: kelos.dev/v1alpha1\nkind: Task\nmetadata:\n  name: write-tests\nspec:\n  type: claude-code\n  prompt: \"Write comprehensive tests for the user service\"\n  credentials:\n    type: oauth\n    secretRef:\n      name: claude-oauth-token\n  workspaceRef:\n    name: my-workspace\n  branch: feature/user-service\n  dependsOn: [scaffold]\n```\n\n\u003c/details\u003e\n\nDownstream tasks can reference upstream results in their prompt using `{{.Deps}}`:\n\n```yaml\napiVersion: kelos.dev/v1alpha1\nkind: Task\nmetadata:\n  name: open-pr\nspec:\n  type: claude-code\n  prompt: |\n    Open a PR for branch {{index .Deps \"write-tests\" \"Results\" \"branch\"}}.\n  credentials:\n    type: oauth\n    secretRef:\n      name: claude-oauth-token\n  workspaceRef:\n    name: my-workspace\n  branch: feature/user-service\n  dependsOn: [write-tests]\n```\n\nThe `.Deps` map is keyed by dependency Task name. Each entry has `Results` (key-value map with branch, commit, pr, etc.) and `Outputs` (raw output lines). See [examples/07-task-pipeline](examples/07-task-pipeline/) for a full three-stage pipeline.\n\n### Create PRs automatically\n\nAdd a `token` to your workspace config:\n\n```yaml\nworkspace:\n  repo: https://github.com/your-org/repo.git\n  ref: main\n  token: \u003cyour-github-token\u003e\n```\n\n```bash\nkelos run -p \"Fix the bug described in issue #42 and open a PR with the fix\"\n```\n\nThe `gh` CLI and `GITHUB_TOKEN` are available inside the agent container, so the agent can push branches and create PRs autonomously.\n\n### Inject agent instructions and MCP servers\n\nUse `AgentConfig` to bundle project-wide instructions, plugins, and MCP servers:\n\n```yaml\napiVersion: kelos.dev/v1alpha1\nkind: AgentConfig\nmetadata:\n  name: my-config\nspec:\n  agentsMD: |\n    # Project Rules\n    Follow TDD. Always write tests first.\n  mcpServers:\n    - name: github\n      type: http\n      url: https://api.githubcopilot.com/mcp/\n      headers:\n        Authorization: \"Bearer \u003ctoken\u003e\"\n```\n\n```bash\nkelos run -p \"Fix the bug\" --agent-config my-config\n```\n\n- `agentsMD` is written to `~/.claude/CLAUDE.md` (user-level, additive with the repo's own instructions).\n- `plugins` are mounted as plugin directories and passed via `--plugin-dir`.\n- `mcpServers` are written to the agent's native MCP configuration. Supports `stdio`, `http`, and `sse` transport types.\n\nSee the [full AgentConfig spec](docs/reference.md#agentconfig) for plugins, skills, and agents configuration.\n\n\u003e Browse all ready-to-apply YAML manifests in the [`examples/`](examples/) directory.\n\n## Integration\n\nKelos integrates with external systems in two ways:\n\n**TaskSpawner** — Kelos natively watches external sources and automatically creates Tasks. Supports GitHub Issues, GitHub Pull Requests, Jira, and Cron schedules. No glue code needed.\n\n```yaml\nspec:\n  when:\n    githubIssues:\n      labels: [bug]\n      state: open\n```\n\n**Direct Task creation** — Create Task resources from your own workflows for full control. Any system that can run `kubectl apply` or call the Kubernetes API can trigger agent runs — GitHub Actions, CI/CD pipelines, scripts, Slack bots, or custom automation.\n\n```bash\nkelos run -p \"Fix the flaky test in ci_test.go\" --workspace my-workspace\n```\n\nSee the [Integration guide](docs/integration.md) for examples of both approaches, including GitHub Actions workflows, Jira setup, and programmatic Task creation.\n\n## Orchestration Patterns\n\n- **Autonomous Self-Development** — Build a feedback loop where agents pick up issues, write code, self-review, and fix CI flakes until the task is complete. See the [self-development pipeline](#kelos-developing-kelos).\n- **Event-Driven Bug Fixing** — Automatically spawn agents to investigate and fix bugs as soon as they are labeled in GitHub. See [Auto-fix GitHub issues](#auto-fix-github-issues-with-taskspawner).\n- **Fleet-Wide Refactoring** — Orchestrate a \"fan-out\" where dozens of agents apply the same refactoring pattern across a fleet of microservices in parallel.\n- **Hands-Free CI/CD** — Embed agents as first-class steps in your deployment pipelines to generate documentation or perform automated migrations.\n- **AI Worker Pools** — Maintain a pool of specialized agents (e.g., \"The Security Fixer\") that developers can trigger via simple Kubernetes resources.\n\n## Reference\n\n| Resource | Key Fields | Full Spec |\n|----------|-----------|-----------|\n| **Task** | `type`, `prompt`, `credentials`, `workspaceRef`, `dependsOn`, `branch` | [Reference](docs/reference.md#task) |\n| **Workspace** | `repo`, `ref`, `secretRef` (PAT or GitHub App), `files` | [Reference](docs/reference.md#workspace) |\n| **AgentConfig** | `agentsMD`, `plugins`, `mcpServers` | [Reference](docs/reference.md#agentconfig) |\n| **TaskSpawner** | `when`, `taskTemplate`, `pollInterval`, `maxConcurrency` | [Reference](docs/reference.md#taskspawner) |\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eCLI Reference\u003c/strong\u003e\u003c/summary\u003e\n\n| Command | Description |\n|---------|-------------|\n| `kelos install` | Install Kelos CRDs and controller into the cluster |\n| `kelos uninstall` | Uninstall Kelos from the cluster |\n| `kelos init` | Initialize `~/.kelos/config.yaml` |\n| `kelos run` | Create and run a new Task |\n| `kelos get \u003cresource\u003e [name]` | List resources or view a specific resource (`tasks`, `taskspawners`, `workspaces`) |\n| `kelos delete \u003cresource\u003e \u003cname\u003e` | Delete a resource |\n| `kelos logs \u003ctask-name\u003e [-f]` | View or stream logs from a task |\n| `kelos suspend taskspawner \u003cname\u003e` | Pause a TaskSpawner |\n| `kelos resume taskspawner \u003cname\u003e` | Resume a paused TaskSpawner |\n\nSee [full CLI reference](docs/reference.md#cli-reference) for all flags and options.\n\n\u003c/details\u003e\n\n## Security Considerations\n\nKelos runs agents in isolated, ephemeral Pods with no access to your host machine, SSH keys, or other processes. The risk surface is limited to what the injected credentials allow.\n\n**What agents CAN do:** Push branches, create PRs, and call the GitHub API using the injected `GITHUB_TOKEN`.\n\n**What agents CANNOT do:** Access your host, read other pods, reach other repositories, or access any credentials beyond what you explicitly inject.\n\nBest practices:\n\n- **Scope your GitHub tokens.** Use [fine-grained Personal Access Tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#fine-grained-personal-access-tokens) restricted to specific repositories instead of broad `repo`-scoped classic tokens.\n- **Enable branch protection.** Require PR reviews before merging to `main`. Agents can push branches and open PRs, but protected branches prevent direct pushes to your default branch.\n- **Use `maxConcurrency` and `maxTotalTasks`.** Limit how many tasks a TaskSpawner can create to prevent runaway agent activity.\n- **Use `podOverrides.activeDeadlineSeconds`.** Set a timeout to prevent tasks from running indefinitely.\n- **Audit via Kubernetes.** Every agent run is a first-class Kubernetes resource — use `kubectl get tasks` and cluster audit logs to track what was created and by whom.\n\n\u003e **About `--dangerously-skip-permissions`:** Claude Code uses this flag for non-interactive operation. Despite the name, the actual risk is minimal — agents run inside ephemeral containers with no host access. The flag simply disables interactive approval prompts, which is necessary for autonomous execution.\n\nKelos uses standard Kubernetes RBAC — use namespace isolation to separate teams. Each TaskSpawner automatically creates a scoped ServiceAccount and RoleBinding.\n\n## Cost and Limits\n\nRunning AI agents costs real money. Here's how to stay in control:\n\n**Model costs vary significantly.** Opus is the most capable but most expensive model. Use `spec.model` (or `model` in config) to choose cheaper models like Sonnet for routine tasks and reserve Opus for complex work. Check the [API pricing](https://docs.anthropic.com/en/docs/about-claude/pricing) page for current rates.\n\n**Use `maxConcurrency` to cap spend.** Without it, a TaskSpawner can create unlimited concurrent tasks. If 100 issues match your filter on first poll, that's 100 simultaneous agent runs. Always set a limit:\n\n```yaml\nspec:\n  maxConcurrency: 3      # max 3 tasks running at once\n  maxTotalTasks: 50       # stop after 50 total tasks\n```\n\n**Use `podOverrides.activeDeadlineSeconds` to limit runtime.** Set a timeout per task to prevent agents from running indefinitely:\n\n```yaml\nspec:\n  podOverrides:\n    activeDeadlineSeconds: 3600  # kill after 1 hour\n```\n\nOr via the CLI:\n\n```bash\nkelos run -p \"Fix the bug\" --timeout 30m\n```\n\n**Use `suspend` for emergencies.** If costs are spiraling, pause a spawner immediately:\n\n```bash\nkelos suspend taskspawner my-spawner\n# ... investigate ...\nkelos resume taskspawner my-spawner\n```\n\n**Rate limits.** API providers enforce concurrency and token limits. If a task hits a rate limit mid-execution, it will likely fail. Use `maxConcurrency` to stay within your provider's limits.\n\n## FAQ\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eWhat agents does Kelos support?\u003c/strong\u003e\u003c/summary\u003e\n\nKelos supports **Claude Code**, **OpenAI Codex**, **Google Gemini**, **OpenCode**, and **Cursor** out of the box. You can also bring your own agent image using the [container interface](docs/agent-image-interface.md).\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eCan I use Kelos without Kubernetes?\u003c/strong\u003e\u003c/summary\u003e\n\nNo. Kelos is built on Kubernetes Custom Resources and requires a Kubernetes cluster. For local development, use [kind](https://kind.sigs.k8s.io/) (`kind create cluster`) to create a single-node cluster on your machine.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eIs it safe to give agents repo access?\u003c/strong\u003e\u003c/summary\u003e\n\nAgents run in isolated, ephemeral Pods with no host access. Their capabilities are limited to what you inject — typically a scoped GitHub token. Use fine-grained PATs, branch protection, and `maxConcurrency` to control the blast radius. See [Security Considerations](#security-considerations).\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eHow much does it cost to run?\u003c/strong\u003e\u003c/summary\u003e\n\nCosts depend on the model and task complexity. Check the [API pricing](https://docs.anthropic.com/en/docs/about-claude/pricing) page for current rates. Use `maxConcurrency`, timeouts, and model selection to stay in budget. See [Cost and Limits](#cost-and-limits).\n\n\u003c/details\u003e\n\n## Uninstall\n\n```bash\nkelos uninstall\n```\n\n## Development\n\nBuild, test, and iterate with `make`:\n\n```bash\nmake update             # generate code, CRDs, fmt, tidy\nmake verify             # generate + vet + tidy-diff check\nmake test               # unit tests\nmake test-integration   # integration tests (envtest)\nmake test-e2e           # e2e tests (requires cluster)\nmake build              # build binary\nmake image              # build docker image\n```\n\n## Contributing\n\n1. Fork the repo and create a feature branch.\n2. Make your changes and run `make verify` to ensure everything passes.\n3. Open a pull request with a clear description of the change.\n\nFor significant changes, please open an issue first to discuss the approach.\n\nWe welcome contributions of all kinds — see [good first issues](https://github.com/kelos-dev/kelos/labels/good%20first%20issue) for places to start.\n\n## License\n\n[Apache License 2.0](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkelos-dev%2Fkelos","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkelos-dev%2Fkelos","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkelos-dev%2Fkelos/lists"}