xiaods/k8e

K8E란 무엇인가요?

K8E(k-eight-e로 발음)는 AI 에이전트를 위한 오픈 소스 샌드박스 플랫폼입니다. 자율형 에이전트(Claude Code, Codex, Pi 등)가 생성한 신뢰할 수 없는 코드를 격리된 컨테이너나 마이크로 VM 내에서 실행하는 데 필요한 모든 것을 패키징합니다. 전체 시스템은 100MB 미만의 단일 바이너리로 제공되며, 모든 Linux 호스트를 안전한 멀티 테넌트 실행 매트릭스로 변환할 수 있습니다.

핵심 아이디어

에이전트 격리 – AI 기반의 각 워크로드는 엄격한 CPU/메모리 제한이 적용된 자체 샌드박스(gVisor, Kata Containers 또는 Firecracker) 내에서 실행됩니다.
에이전트 간 제로 트러스트 – 네트워크 정책, eBPF 기반 이그레스 규칙, 세션별 작업 공간을 통해 한 에이전트가 다른 에이전트에 영향을 미치지 못하도록 합니다.
빠른 시작 – 미리 부팅된 Pod의 *웜 풀(warm-pool)*을 통해 새로운 세션을 500ms 이내에 확보할 수 있습니다.
E2B 호환 API – 게이트웨이는 Elastic Engine for Bots (E2B) API와 일치하는 gRPC/mTLS 엔드포인트를 노출하므로, 기존 LLM 에이전트 툴킷을 변경 없이 그대로 사용할 수 있습니다.
원클릭 설치 – 간단한 설치 스크립트(curl … | sh -)를 통해 바이너리, 최소한의 Kubernetes 스타일 컨트롤 플레인, 샌드박스 런타임을 약 60초 만에 설정할 수 있습니다.

아키텍처 개요

AI Agent (Claude Code / Codex / Pi) ──► k8e-sandbox-cli (gRPC over mTLS)
                                            │
                                            ▼
                                   Sandbox Gateway (E2B-compatible)
                                            │
               ┌────────────────────────────┼─────────────────────────────┐
               │                            │                             │
        Session manager                Metrics & Events               Warm-pool
               │                            │                             │
               ▼                            ▼                            ▼
   ┌─────────────────────┐   ┌─────────────────────┐   ┌─────────────────────┐
   │ Sandbox pod (gVisor│   │ Sandbox pod (Kata   │   │ Pre-booted pod ready│
   │ / Kata / Firecracker)│   │ / Firecracker)      │   │ to be claimed        │
   └─────────────────────┘   └─────────────────────┘   └─────────────────────┘

Sandbox Gateway – 세션 수명 주기, 파일 I/O, PTY 터미널, 명령 실행, 스냅샷 및 서비스 노출을 처리하는 단일 gRPC 서버입니다.
격리 런타임 – 플러그인 가능한 RuntimeClass: gVisor(사용자 공간 커널, 약 10ms 부팅), Kata Containers(VM 기반, 약 500ms), Firecracker(마이크로 VM, 약 125ms).
Cilium – 기본 CNI가 eBPF 기반 NetworkPolicy 적용 및 세션별 이그레스 화이트리스트를 제공합니다.
웜 풀 컨트롤러 – 구성 가능한 수의 사전 시작된 샌드박스 Pod를 유지하여 새 세션이 500ms 미만으로 시작되도록 합니다.

주요 구성 요소

구성 요소	역할
Sandbox Gateway	gRPC + mTLS 진입점; 세션, 실행, 파일, PTY, 스냅샷 및 메트릭을 위한 E2B 호환 API 구현.
격리 런타임	gVisor, Kata Containers, Firecracker – Pod 생성 시 `RuntimeClass`를 통해 선택.
Cilium (eBPF)	Kubernetes `NetworkPolicy` 및 세션별 이그레스(`allowed_hosts`) 적용.
웜 풀 컨트롤러	준비된 샌드박스 Pod 풀 유지; 수요에 따라 자동 확장.
k8e-sandbox-cli	에이전트가 세션 생성, 코드 실행, 파일 읽기/쓰기, 스냅샷 관리에 사용하는 독립형 클라이언트(~44 MB).
API-key 서비스	에이전트용 단기 키 생성; 키는 mTLS 인증에 사용.

시작하기 (퀵스타트)

# 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 설치 (단일 바이너리, <100 MB)
curl -sfL https://k8e.sh/install.sh | sh -

# 3. 서비스 확인
k8e-sandbox-cli status
k8e-sandbox-cli run 'echo hello from the sandbox'

설치 스크립트는 최소한의 컨트롤 플레인을 설정하고, 게이트웨이를 시작하며, 샌드박스 Pod의 웜 풀을 생성합니다.

AI 에이전트에서 샌드박스 사용하기

서버에서 API 키 생성:

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

OS용 클라이언트 다운로드 (≈44 MB) 및 실행 권한 부여.

연결 (에이전트에 /k8e-sandbox 스킬 설치):

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

코드 실행 – 에이전트는 이제 다음과 같은 명령을 내릴 수 있습니다:
```
k8e-sandbox-cli run "print('hello')" --lang python
```
CLI는 자동으로 세션을 생성하고, 명령을 격리된 Pod로 스트리밍하며, 결과를 반환합니다.

README에 나열된 지원 에이전트는 Claude Code, Codex, Pi입니다.

AI 에이전트 워크로드를 위한 주요 기능

안전한 격리 – 경량(gVisor) 및 강력한 VM 기반 런타임 중 선택 가능.
리소스 할당량 – 비용 폭주를 방지하기 위한 세션별 CPU/메모리 제한.
임시 작업 공간 – 각 세션은 자동으로 정리되는 새로운 파일 시스템을 제공받음.
콘텐츠 주소 지정 스냅샷 – SHA-256 CAS 레이어 저장소를 통한 빠른 증분 복원.
실행 기록 및 로그 – 디버깅을 위한 재개 가능한 명령 로그.
관측 가능성 – Prometheus 메트릭 및 NDJSON 이벤트 스트림.
하위 에이전트 재사용 – 하위 에이전트는 격리 상태를 유지하면서 부모 Pod의 작업 공간을 공유할 수 있음.
CLI 카탈로그 – SDK 생성을 위한 기계 판독 가능한 명령 설명.

K8E 사용 시기

즉석에서 코드를 생성하고 실행하는 자율형 AI 에이전트를 구축 중일 때.
강력한 격리가 필요할 때(악의적이거나 버그가 있는 에이전트 코드가 호스트나 다른 에이전트에 영향을 미치지 않도록 방지).
매번 전체 VM을 프로비저닝하지 않고 빠른 온디맨드 실행을 원할 때.
대규모 클라우드 관리 서비스보다 자체 호스팅되는 단일 바이너리 솔루션을 선호할 때.

라이선스 및 커뮤니티

라이선스: Apache 2.0
별점 / 릴리스: 버전별 릴리스로 활발히 유지 관리됨; x86_64, ARM64, RISC-V용 바이너리 제공.
일반적인 GitHub 풀 리퀘스트 워크플로우를 통한 기여를 환영합니다.

요약

K8E는 신뢰할 수 없는 AI 에이전트 코드를 안전하고 대규모로 실행할 수 있는 소형 자체 호스팅 샌드박스 매트릭스입니다. 런타임을 설치하고(gVisor가 가장 쉬움), 한 줄 설치 프로그램을 실행하고, API 키를 생성한 뒤 k8e-sandbox-cli 바이너리를 사용하면 LLM 에이전트가 1초 미만의 시작 시간, 엄격한 리소스 제한, 내장된 관측 가능성을 갖춘 격리된 Pod 내에서 코드를 실행할 수 있습니다.