kelos-dev/kelos

Kelos – Kubernetes에서 AI 기반 코드 에이전트 실행하기

무엇인가요 – Kelos는 코드 에이전트(Claude Code, OpenAI Codex, Google Gemini 등 LLM 기반 코드 생성기)를 Kubernetes의 1등급 워크로드로 전환하는 오픈소스 컨트롤 플레인입니다. Kelos는 에이전트가 무엇을 해야 하는지, 코드가 어디에 있는지, 어떻게 실행되어야 하는지를 설명하는 커스텀 Kubernetes 리소스들(Task, Session, Workspace, AgentConfig, …)을 정의합니다. 컨트롤러는 이러한 리소스를 감시하고 적절한 Pods, Jobs, 또는 StatefulSets를 생성하며, 자격 증명 처리, 리포지토리 체크아웃, 도구 설치, 라이프사이클 관리 등을 수행합니다.

왜 중요한가요 – 개발자들은 종종 로컬 머신에서 LLM 기반 코드 보조 도구를 실행하지만, 이는 확장성, 격리성, 관찰 가능성에 제한이 있습니다. Kelos는 실행을 Kubernetes 클러스터로 옮겨 다음과 같은 이점을 제공합니다:

• 격리성 – 각 에이전트는 자신의 시크릿과 리소스 제한을 가진 별도의 Pod에서 실행됩니다.
• 재사용성 – 동일한 Workspace, AgentConfig, 그리고 기술 세트는 여러 Task나 Session에서 재사용할 수 있습니다.
• 자동화 – GitHub, Jira, Linear, cron, 또는 일반 웹훅에서 자동으로 Task를 생성할 수 있습니다.
• 관찰 가능성 및 제어 – 모든 것이 네이티브 K8s 객체이므로, 검사, 버전 관리, 표준 정책(RBAC, 할당량 등)을 적용할 수 있습니다.

핵심 개념

리소스	역할
Workspace	Git 리포지토리(옵션으로 ref)를 클러스터에 연결하여 에이전트가 작업할 코드베이스를 제공합니다.
AgentConfig	LLM 제공자 자격 증명, 프롬프트, 플러그인, 그리고 선택적 MCP(모델-컨트롤 플레인) 서버를 저장합니다.
Task	단일 작업: 단일 프롬프트로 에이전트를 실행하고 완료를 기다린 후 결과(커밋, PR, 토큰 사용량)를 캡처합니다.
Session	장시간 실행되는 인터랙티브 대화로, 터미널이나 웹 UI에서 다시 연결할 수 있습니다.
TaskSpawner / SessionSpawner	이벤트(웹훅, 스케줄)에 반응하여 Task 또는 Session을 선언적으로 생성하는 객체입니다.
WorkerPool	냉시작 지연을 줄이기 위해 실행 가능한 에이전트 컨테이너 풀을 유지합니다.

작동 방식 – Kelos 컨트롤러는 커스텀 리소스를 감시하고 이를 Kubernetes 워크로드로 변환합니다:

1. Workspace → 공유된 PersistentVolume에 리포지토리를 클론합니다.
2. AgentConfig → 자격 증명을 Secrets로 주입하고 선택한 LLM 제공자 이미지를 마운트합니다.
3. Task → 제공된 프롬프트로 에이전트 컨테이너를 실행하는 Job을 생성합니다.
4. Session → StatefulSet과 함께 웹소켓 서버 사이드카를 생성하여 Kelos 콘솔이나 CLI를 통해 에이전트와 대화할 수 있습니다.
5. Spawner 객체는 외부 소스(GitHub 웹훅, CronJobs)를 감시하고 위 리소스들을 자동으로 생성합니다.

시작하기 (README에서)

# 1. cert-manager가 설치된 K8s 1.28+ 클러스터가 필요합니다
# 2. Kelos CLI 설치
curl -fsSL https://raw.githubusercontent.com/kelos-dev/kelos/main/hack/install.sh | bash
# 또는 Homebrew / go install을 통해

# 3. 컨트롤러를 클러스터에 배포
kelos install   # Helm 차트 설치

# 4. LLM에 코드 에이전트 기술 추가 (예: Node 기반 기술)
npx skills add kelos-dev/kelos

# 5. 리포지토리에 연결된 Workspace 생성
kelos create workspace my-workspace \
  --repo https://github.com/your-org/your-repo.git \
  --ref main

# 6. 단일 실행 Task 실행
kelos run \
  --workspace my-workspace \
  --prompt "Python으로 안녕 세계 프로그램 추가" \
  --watch

# 7. (옵션) 웹 콘솔을 통해 인터랙티브 세션 연결
kelos session connect interactive-review

CLI는 kelos logs, kelos init(구성 템플릿 생성), kelos create …(다른 리소스 유형 생성)도 지원합니다.

일반적인 사용 사례

• 개발자 주도 작업 – Session을 시작하고 에이전트가 코드 초안을 작성한 후, 나중에 다시 연결하여 검토하거나 계속 작업합니다.
• 이벤트 기반 자동화 – GitHub 이슈에 agent-ready 라벨이 붙으면 자동으로 Task를 생성합니다. 에이전트는 버그를 재현하고 수정 코드를 작성한 후 PR을 엽니다.
• 에이전트 파이프라인 – TaskSpawner를 사용해 Task를 연결(구현 → 테스트 → 검토)하여 LLM 기반의 CI 스타일 워크플로우를 구축합니다.
• 리포지토리 펌플릿 – 병렬 Task를 생성하여 수십 개의 마이크로서비스에 동일한 변경 사항을 적용합니다.
• 자기 개발 루프 – 전용 에이전트가 지속적으로 프로젝트를 트리지, 구현, 유지보수합니다 (Kelos 리포지토리 자체가 이를 보여줍니다).

더 알아보기 – 리포지토리는 풍부한 문서를 제공합니다:

• docs/reference.md – API 사양 및 CLI 플래그 설명.
• examples/ – Task, Session, Spawner 등에 대한 바로 사용 가능한 YAML 패턴.
• docs/integration.md – GitHub, Jira, Linear, 일반 웹훅 통합 방법.
• docs/agent-image-interface.md – 표준 LLM 에이전트 인터페이스를 노출하는 커스텀 컨테이너 이미지 제작 방법.
• 설치 및 업그레이드를 위한 Helm 차트 문서.

라이선스 – Apache License 2.0.