TencentCloud/CubeSandbox 딥다이브
— AI 에이전트에게 "진짜 컴퓨터"를 60ms 만에 쥐어주는 마이크로VM

1프로젝트 한 줄 요약

2왜 주목받는가 — 컨테이너로는 안 되는 이유

배경: "AI가 짠 코드를 어디서 돌릴 것인가" 문제

2025~2026년 코딩 에이전트가 폭발하면서 모두가 같은 벽에 부딪혔다. 에이전트에게 셸을 주려면 그 셸이 격리돼 있어야 한다. 그런데 에이전트는 사람과 달리 초당 수십 개씩 세션을 만들고 버린다. 이 두 요구는 정면으로 충돌한다.

README의 비교표를 그대로 옮기면 이렇다. (모두 저장소가 주장하는 자체 측정치이며 제3자 검증은 아니다.)

실측 벤치마크 — 동시성이 올라가면 어떻게 되는가

저장소의 벤치마크 문서(docs/blog/posts/2026-06-01-cubesandbox-perf-benchmark.md)는 텐센트 클라우드 BMI5 베어메탈(96코어 / 375GiB)에서 잰 수치를 공개한다. 마케팅 숫자만 보지 말고 동시성이 올라갈 때의 꼬리 지연(P95/P99)을 보는 게 핵심이다.

메모리 오버헤드 <5MB의 진실

같은 문서를 끝까지 읽으면 더 정직한 숫자가 나온다. 2GiB 스펙 샌드박스를 100개 띄우면 VM당 실제 소비 메모리는 약 21.5MB, 1000개를 띄우면 약 25.7MB로 수렴한다. "5MB"는 VMM 프로세스 자체의 오버헤드이고, 실제로는 게스트 커널·에이전트가 쓰는 메모리가 더해진다.

경쟁 제품 대비 위치

흥미롭게도 저장소는 E2B를 경쟁자로 공격하지 않고 "완전 호환"을 내세운다. 문서에는 이렇게 쓰여 있다 — "E2B Cloud에서 Cube Sandbox로 옮기는 것은 API URL 같은 환경변수를 교체하는 것만큼 간단하다."

3기술 스택 전체 지도

이 프로젝트의 첫인상은 "언어를 왜 이렇게 섞었지?"다. 하지만 배치를 보면 규칙이 명확하다 — 커널·하드웨어에 가까울수록 Rust, 오케스트레이션·클러스터에 가까울수록 Go, 트래픽 라우팅은 Lua.

언어별 코드 규모 (실측)

백엔드 — Rust 진영

백엔드 — Go 진영

인프라 / 프론트엔드

• CubeProxy — OpenResty(nginx + Lua). 호스트/경로 기반 라우팅 + Redis 조회로 요청을 올바른 샌드박스로 전달
• CubeEgress — OpenResty + Lua. 아웃바운드 트래픽 L7 검사 프록시
• CubeNet — eBPF C 3개 파일 + Go 컨트롤플레인(cubevs)
• Redis — 상태·이벤트·분산 락
• MySQL / PostgreSQL — 영속 메타데이터 (최근 커밋에 PostgreSQL 경로 수정 이력 있음)
• web/ — WebUI 대시보드
• Buildkit — 템플릿 rootfs 빌드
• CoreDNS — 샌드박스 DNS

4아키텍처 심화 — 8개 컴포넌트와 4가지 설계 패턴

전체 시스템 구조도

설계 패턴 ① — 컨트롤 플레인과 데이터 플레인의 완전 분리

다이어그램에서 가장 중요한 건 화살표가 두 갈래로 갈라진다는 점이다.

• 컨트롤 플레인: 클라이언트 → CubeAPI → CubeMaster → Cubelet → CubeShim → 하이퍼바이저. "샌드박스를 만들어/멈춰/지워" 같은 명령이 흐른다.
• 데이터 플레인: 클라이언트 → CubeProxy → (Redis에서 샌드박스 위치 조회) → 샌드박스 안의 envd. "이 코드를 실행해" 같은 실제 작업이 흐른다.

설계 패턴 ② — 이중 격리 (VM 안에 또 컨테이너)

이 프로젝트에서 가장 오해하기 쉬운 부분이다. 격리가 두 겹이다.

왜 VM 안에 또 컨테이너를 넣을까? 두 경계가 막는 것이 다르기 때문이다.

실제 코드 위치는 이렇다:

• agent/src/namespace.rs — Namespace 구조체가 unshare(CloneFlags)로 IPC/UTS/PID 네임스페이스를 만들고 /var/run/sandbox-ns에 퍼시스턴트 마운트
• agent/rustjail/src/seccomp.rs — init_seccomp(scmp: &LinuxSeccomp)가 OCI 런타임 스펙의 seccomp 프로필을 적용. get_unknown_syscalls()로 커널이 모르는 syscall을 걸러낸다
• agent/rustjail/src/cgroups/ — fs·systemd 두 드라이버 + notifier

설계 패턴 ③ — CubeCoW: 파일 복사 없는 스냅샷

60ms 부팅의 진짜 비밀은 하이퍼바이저가 빨라서가 아니라 "부팅을 안 하기 때문"이다.

템플릿이 만들어지는 과정은 3단계다 (docs/guide/templates.md):

CubeCoW가 내세우는 두 가지 특징:

• flat snapshot model — 스냅샷들이 사슬(체인)로 엮이지 않는다. 그래서 중간 스냅샷 하나를 지워도 다른 스냅샷이 깨지지 않는다. (Docker 이미지 레이어나 qcow2 백킹 체인의 고질적 문제를 피한다)
• incremental dirty-page tracking — soft-dirty 커널 기능으로 변경된 익명 페이지만 저장한다

스냅샷 메타데이터 구조체(CubeShim/shim/src/hypervisor/snapshot.rs)도 살펴볼 가치가 있다:

struct SnapshotInfo {
    kernel_version,   // 게스트 커널 버전
    image_version,    // rootfs 이미지 버전
    ch_version,       // Cloud Hypervisor 버전
    vm_res,           // VmRes { cpu, cpu_max, memory, disks, pmems }
    memory_vol_url,
    ...
}

설계 패턴 ④ — CubeVS: iptables를 버리고 eBPF로

샌드박스가 수천 개면 네트워크 규칙도 수천 개다. 전통적인 iptables는 규칙을 선형 탐색하므로 규칙이 늘수록 패킷당 지연이 커진다(이른바 "rule explosion"). CubeVS는 이걸 eBPF로 우회한다.

eBPF 프로그램 3개가 각각 다른 지점에 붙는다:

Go 컨트롤플레인(CubeNet/cubevs/)이 BPF 맵을 관리한다 — egress_sessions, snat_iplist, allow_out_v2, dns_allow 등. iptables·리눅스 브리지·OVS를 전혀 쓰지 않는다.

보안 계층 총정리

docs/architecture/overview.md가 정리한 6개 방어층:

1. KVM 마이크로VM — 전용 커널, 하드웨어 격리
2. CubeVS — 기본 거부(사설 대역·링크로컬 차단) + 샌드박스별 정책
3. CubeEgress — L7 도메인 화이트리스트
4. Credential vault — 헤더 재작성으로 시크릿을 주입. 시크릿이 샌드박스 안에도, LLM 컨텍스트에도 노출되지 않는다
5. CubeHypervisor — VMM 프로세스 최소 seccomp
6. CubeAPI — 교체 가능한(pluggable) 인증 콜백

5디렉토리 구조 해부

읽는 순서 추천

1. docs/architecture/overview.md — 전체 그림. 여기부터 시작 안 하면 길을 잃는다
2. CubeAPI/src/routes.rs — 시스템이 "무엇을 할 수 있는가"의 전체 목록
3. CubeShim/shim/src/hypervisor/cube_hypervisor.rs — VM 라이프사이클의 실제 호출 흐름
4. cubecow/ — 크기가 작고 독립적이라 혼자 읽기 좋다. FICLONE 학습에 최적
5. CubeNet/*.bpf.c — eBPF 실전 코드. 3개 파일뿐이라 부담 없다

6학습 포인트 — 여기서 훔쳐올 설계

① 가상화 — "빠른 부팅"의 실체

이 저장소의 가장 큰 교훈은 성능 문제를 "더 빠르게 만들기"가 아니라 "안 하기"로 푼다는 것이다. 부팅이 느리면 부팅을 최적화하는 대신, 부팅 결과를 저장해두고 복원한다.

이 패턴은 도처에 있다 — JVM의 AppCDS, Android의 Zygote 프로세스, Python의 fork() 기반 프리로더, Node.js의 스냅샷. 공통 구조는 이렇다:

실습 아이디어: 무거운 초기화(대형 모델 로딩, DB 커넥션 풀)를 하는 파이썬 프로세스를 만들고, fork() 기반 프리포크 서버로 바꿔 요청당 지연이 얼마나 줄어드는지 측정해보라.

② 파일시스템 — CoW를 직접 만져보기

FICLONE은 Rust나 C가 아니어도 실험할 수 있다. 리눅스에서 XFS(reflink 활성) 또는 Btrfs 위에서 cp --reflink=always를 써보면 즉시 체감된다.

# 10GB 파일을 만들고 두 방식으로 복사해 시간 비교
dd if=/dev/zero of=big.img bs=1M count=10240
time cp big.img copy1.img                 # 수십 초
time cp --reflink=always big.img copy2.img # 밀리초
df -h .                                    # 디스크 사용량이 안 늘어난다

실습 아이디어: reflink 복사본을 만든 뒤 한쪽 파일 일부를 수정하고, filefrag -v로 extent가 어떻게 갈라지는지 관찰해보라. CoW가 "언제" 실제 복사를 하는지 눈으로 볼 수 있다.

③ eBPF — 커널 프로그래밍의 현대적 입구

CubeNet의 파일 3개는 eBPF 입문 교재로 훌륭하다. TC(Traffic Control) 훅에 붙는 eBPF는 XDP보다 다루기 쉽고 활용 범위가 넓다.

실습 아이디어: cilium/ebpf(Go) 또는 aya(Rust)로 "특정 포트로 나가는 패킷만 카운트하는" 최소 TC 프로그램을 작성해보라. 그다음 BPF 맵에서 그 카운터를 사용자공간으로 읽어오는 것까지 하면 CubeVS의 축소판이 된다.

④ 시스템 설계 — 컨트롤/데이터 플레인 분리

Kubernetes(API 서버 ↔ 워크로드 트래픽), Envoy(xDS ↔ 프록시), Kafka(주키퍼/KRaft ↔ 브로커) 모두 같은 구조다. 이 분리를 못 하면 시스템은 부하가 올라갈 때 항상 같은 방식으로 죽는다 — 제어 명령이 데이터 트래픽에 밀려 타임아웃되고, 그러면 재시도가 몰려 더 죽는다.

실습 아이디어: 자기가 만든 API 서버에서 "관리용 엔드포인트"와 "고빈도 엔드포인트"를 다른 포트/다른 프로세스로 분리해보라. 부하 테스트로 격리 효과를 측정하면 체감이 온다.

⑤ 오픈소스 전략 — 포크와 호환 계층

이 저장소는 "어디까지 빌리고 어디부터 만들 것인가"의 판단 사례집이다.

규칙이 보인다 — "성숙하고 표준적인 것은 빌린다. 자기 제품의 차별점이 되는 부분만 만든다." README도 이를 명시한다: "made tailored modifications... original in-file copyright notices are preserved."

7하드웨어 / 시스템 요구사항

공식 스펙 (docs/guide/quickstart.md)

커널

• 게스트 커널: 6.6.119-49.6 (OpenCloudOS-Kernel 소스, 저장소가 직접 빌드)
• PVM 호스트 커널: 6.6.69-1.2.cubesandbox
• 권장 호스트 OS: OpenCloudOS 9 (RPM 제공). Ubuntu/Debian/CentOS도 지원

KVM이 없는 클라우드 VM이라면 — PVM

배포 경로 3종

추가 배포 자산: deploy/one-click/에 systemd 서비스 + docker-compose(webui, cubeproxy, coredns, cube-lifecycle-manager), deploy/terraform/tencentcloud/에 TKE+CVM 자동 배포(v0.5.0 신규), deploy/kubernetes/chart에 Helm 차트.

ARM64 참고사항

bare-metal-deploy.md에 따르면, 일부 구형 aarch64 호스트는 KVM이 게스트에 PMUv3(성능 카운터)를 노출하지 않는다. 마이크로VM은 정상 부팅하되 하드웨어 성능 카운터 없이 동작한다. 기능상 문제는 아니지만 프로파일링이 제한된다.

8직접 해볼 수 있는 실습 과제

from e2b_code_interpreter import Sandbox

with Sandbox.create(template=template_id) as sandbox:
    print(sandbox.run_code("print('hello cube')",
                           on_stdout=lambda data: print(data)))

9관련 기술 심화 학습 로드맵

10핵심 키워드 사전

11참고 링크

이 프로젝트

• GitHub — TencentCloud/CubeSandbox (★10.4k · fork 911 · Apache-2.0)
• 공식 사이트 — cubesandbox.com
• 저장소 내 문서: docs/architecture/overview.md(전체 구조), docs/guide/quickstart.md(설치), docs/guide/templates.md(템플릿 3단계), docs/blog/posts/2026-06-01-cubesandbox-perf-benchmark.md(벤치마크 원본)
• openapi.yml — REST API 전체 스펙
• examples/ — 17개 예제 (code-sandbox, browser-sandbox, RL training, pi-agent-integration, e2b-dev-sidecar 등)

포크 원본 프로젝트 (원리 학습에 필수)

• Cloud Hypervisor — hypervisor/의 원본
• Kata Containers — agent/·rustjail의 원본
• Firecracker — 마이크로VM 개념의 원조. 문서가 훌륭해 학습용으로 더 좋다
• e2b-dev/infra — envd의 출처
• containerd-shim-rs — CubeShim이 쓰는 shim 프레임워크

배경 기술

• ebpf.io — eBPF 공식 학습 포털
• cilium/ebpf (Go) / aya (Rust) — eBPF 개발 라이브러리
• OCI Runtime Spec — rustjail이 구현하는 표준
• KVM API 문서 — 커널 공식
• XFS 문서 — reflink 동작 원리