xiaods/k8e

K8E는 무엇인가요?

K8E(k8e.sh에 호스팅)는 오픈소스의 AI 에이전트용 사전 격리 환경 플랫폼입니다. 단일 바이너리(< 100MB) 로 제공되어, 어떤 Linux 머신도 자율 에이전트(Claude Code, Codex, Pi 등)가 신뢰할 수 없는 코드를 안전하게 실행할 수 있는 클러스터로 전환합니다. 사전 격리 환경은 플러그인 가능한 격리 런타임(gVisor, Kata Containers, Firecracker microVM)을 사용하며, 에이전트가 직접 호출할 수 있는 가벼운 API(gRPC + E2B 호환 HTTP)를 제공합니다.

핵심 기능

기능	설명
하드웨어 격리	세션별로 gVisor(사용자 공간 커널), Kata(VM 기반), Firecracker(microVM) 중 선택 가능.
네트워크 정책	Cilium(`toFQDNs`)을 통한 세션별 eBPF 규칙. 외부 프록시 필요 없음.
자원 제한	에이전트별 CPU/메모리 제한으로 비용 폭주 방지.
워밍풀 포드	미리 부팅된 사전 격리 포드로 새 세션의 요청 지연을 500ms 미만으로 유지.
일시적 워크스페이스	세션 종료 후 자동 정리. 하위 에이전트는 부모 포드를 공유하지만 재사용 시 리셋됨.
콘텐츠 주소 기반 스냅샷	SHA-256 기반 계층 저장소와 zstd 압축. `--base`로 증분 복원 가능.
실행 트랜스크립트 및 로그	파일 기반, 재시작 가능한 명령 로그. `k8e-sandbox-cli log`로 접근 가능.
관측성	Prometheus 메트릭과 NDJSON 이벤트 스트림(`events`, `ps` 명령).
E2B SDK 호환성	공개 E2B SDK와 동일한 API로 기존 SDK 코드 그대로 사용 가능.
CLI 카탈로그	SDK 바인딩 자동 생성에 유용한 기계가 읽을 수 있는 명령 설명(`catalog`).

아키텍처 개요

AI 에이전트 ──► k8e-sandbox-cli (gRPC/mTLS) ──► 사전 격리 게이트웨이
                                            │
                                            ├─► 워밍풀 컨트롤러 (준비된 포드 유지)
                                            └─► 격리된 사전 격리 포드 (gVisor/Kata/Firecracker)

게이트웨이는 유일한 공개 진입점으로, 세션 라이프사이클, 파일 I/O, PTY 터미널, 스냅샷, 서비스 노출을 처리합니다.

빠른 시작 (30초 설치)

# 1️⃣ 격리 런타임 설치 – gVisor가 기본이며 KVM 필요 없음
ARCH=$(uname -m)
URL=https://storage.googleapis.com/gvisor/releases/release/latest/${ARCH}
wget ${URL}/runsc ${URL}/runsc.sha512 \
     ${URL}/containerd-shim-runsc-v1 ${URL}/containerd-shim-runsc-v1.sha512
sha512sum -c runsc.sha512 -c containerd-shim-runsc-v1.sha512
chmod +x runsc containerd-shim-runsc-v1
sudo mv runsc containerd-shim-runsc-v1 /usr/local/bin/

# 2️⃣ K8E 설치 (단일 바이너리 설치기)
curl -sfL https://k8e.sh/install.sh | sh -

# 3️⃣ 서비스 확인
k8e-sandbox-cli status          # → {"available":true,…}

# 4️⃣ 사전 격리 환경에서 명령 실행
k8e-sandbox-cli run 'echo hello from the sandbox'

위 모든 작업은 최신 x86_64, ARM64, RISC-V Linux 호스트에서 동작합니다.

AI 에이전트에서 사전 격리 환경 사용 방법

서버에서 API 키 생성 (TTL은 기본 30일):

k8e sandbox-apikey create my-agent
# → {"name":"my-agent","key":"k8e-abc123..."}

플랫폼용 클라이언트 바이너리(약 44MB) 다운로드 후 k8e-sandbox-cli에 심볼릭 링크 생성.

연결 – mTLS 인증 수행 및 에이전트 허브에 /k8e-sandbox 스킬 설치:

./k8e-sandbox-cli --endpoint <server-ip>:50051 \
    --apikey k8e-abc123... connect

에이전트는 "이 Python 스크립트를 사전 격리 환경에서 실행해줘"와 같은 자연어 명령을 내릴 수 있으며, 스킬이 내부적으로 k8e-sandbox-cli run ...로 변환합니다.

주요 CLI 명령어 (에이전트 대상)

명령어	목적
`run <code>`	한 번성 명령 또는 스크립트 실행 (세션 자동 생성).
`create`	명시적으로 세션 시작 – 런타임, 허용 호스트, Git 리포지토리 등 설정 가능.
`destroy <sid>`	세션 종료 및 리소스 해제.
`write / read / list`	사전 격리 환경 내 파일 조작.
`subagent <parent-sid>`	부모 포드를 재사용하는 자식 사전 격리 환경 생성 (최대 깊이 1).
`catalog`	CLI의 기계가 읽을 수 있는 설명을 덤프 – SDK 생성에 유용.
`sandbox-apikey ...`	서버 측 API 키 관리 (생성, 목록, 삭제).

K8E를 사용할 때

임의의 코드 실행이 필요한 에이전트 기반 AI 서비스 (예: 코드 생성 에이전트, 데이터 분석 봇).
각 테넌트의 에이전트가 서로 격리되어야 하는 다중 테넌트 플랫폼.
비용 민감한 배포 – 워밍풀 포드로 시작 지연을 낮추면서도 바이너리 크기는 극히 작음.
E2B, Daytona, Kubernetes SIG agent-sandbox 프로젝트와 같은 상용 제품의 셀프호스팅 대안.

다른 사전 격리 환경과의 차이점

	K8E	E2B	Daytona	agent-sandbox (SIG)
셀프호스팅, 단일 바이너리	✅ (< 100MB)	❌ 무거운 VM 이미지	✅	❌ 전체 K8s 클러스터 필요
플러그인 가능한 런타임	gVisor / Kata / Firecracker	Firecracker 전용	microVM/컨테이너	RuntimeClass (K8s 필요)
500ms 미만의 시작을 위한 워밍풀	✅	❌	✅	❌
E2B SDK 호환성	✅ 네이티브	✅	❌	❌
내장된 eBPF 네트워크 정책	✅ (Cilium)	❌	❌	❌

TL;DR

K8E는 작고 자가 완전한 사전 격리 환경 매트릭스로, AI가 생성한 코드를 확장성 있게 안전하게 실행할 수 있습니다. 런타임(gVisor가 가장 쉬움)을 설치하고, 1줄 설치 스크립트를 실행하며, API 키를 생성하면 에이전트는 밀리초 단위 지연으로 격리된 포드에서 코드를 실행할 수 있습니다. 완전한 Kubernetes 클러스터나 무거운 VM이 필요 없습니다.