OpenSandbox에 대해 알아보자

 

GitHub - alibaba/OpenSandbox: OpenSandbox is a general-purpose sandbox platform for AI applications, offering multi-language SDK

 

---

OpenSandbox가 해결하려는 문제

AI 에이전트(코딩 에이전트/GUI 에이전트/브라우저 자동화/평가 에이전트 등)는 **“외부에서 생성된(신뢰할 수 없는) 코드/명령/툴 호출”**을 실제로 실행해야 결과를 얻습니다. 이때 로컬 머신이나 운영 서버에서 그대로 실행하면:

• 파일 시스템/네트워크/프로세스에 대한 과도한 권한으로 사고 가능
• 실행 환경(패키지/OS/의존성)이 매번 달라 재현성 저하
• 여러 세션을 격리/수명관리(TTL)/리소스 제한/관찰성(로그·메트릭)을 운영레벨로 갖추기 어려움

OpenSandbox는 이를 위해 **“AI 앱용 범용 샌드박스 플랫폼”**으로, 다양한 언어 SDK + 표준 API(프로토콜) + Docker/Kubernetes 런타임을 한 세트로 제공합니다. (GitHub)

---

한 줄 정의

컨테이너 기반 격리 환경을 ‘에이전트가 쓰기 좋은 방식’으로 표준화한 플랫폼입니다.

• 클라이언트(에이전트/서비스) 입장: SDK로 샌드박스 생성 → 파일 업로드/명령 실행/코드 인터프리터 실행 → 결과 수집
• 운영 입장: 샌드박스 수명(TTL), 리소스 제한, 네트워크 정책, 관찰성 등을 “서버(컨트롤 플레인)”에서 통제 (GitHub)

---

아키텍처(구성 레이어) — OpenSandbox가 “플랫폼”인 이유

공식 아키텍처 문서 기준으로 4개 레이어로 정리됩니다. (GitHub)

1. SDKs Layer
   Python/Java(Kotlin)/JS/TS/C# 등에서 동일한 개념으로 샌드박스를 다루는 클라이언트 라이브러리.
   주요 컴포넌트로 Sandbox(수명관리), Filesystem(파일CRUD), Commands(명령 실행), CodeInterpreter(상태 유지형 코드 실행) 등을 제공합니다. (GitHub)
2. Specs Layer (프로토콜/표준)
   OpenAPI 스펙으로 “샌드박스 수명관리 API”와 “샌드박스 내부 실행 API”를 표준화합니다.
   즉, 런타임 구현을 Docker→K8s로 바꿔도, SDK/클라이언트는 같은 계약(Contract)으로 붙습니다. (GitHub)
3. Runtime Layer (서버/오케스트레이션)
   FastAPI 기반의 서버가 샌드박스 생성/중지/일시정지/재개/종료, TTL, 엔드포인트 발급, 인증 등을 담당합니다. Docker/Kubernetes 런타임을 플러그인처럼 선택할 수 있습니다. (GitHub)
4. Sandbox Instances Layer (실제 컨테이너 + execd 주입)
   각 샌드박스 컨테이너 내부에 execd라는 실행 데몬을 주입(inject)해, 파일/명령/코드 실행을 HTTP API로 제공하게 만듭니다. (GitHub)

---

핵심 구성요소 3개만 기억하면 됩니다

1) OpenSandbox Server (컨트롤 플레인)

• FastAPI 기반 “샌드박스 관리자”
• 기능: 생성/조회/삭제, pause/resume, TTL(자동 만료/갱신), API Key 인증, 네트워크 모드(host/bridge), 리소스 제한(CPU/메모리 등), 상태 전이 추적 등 (GitHub)

도커 모드 포인트

• host 모드: 컨테이너가 호스트 네트워크 공유(성능/단순)
• bridge 모드: 네트워크 격리 + 서버 프록시/라우팅으로 외부 접근 제공(운영에 유리) (GitHub)

2) execd (샌드박스 내부 실행 데몬)

샌드박스 컨테이너 안에서 돌아가며 아래를 HTTP로 제공합니다. (GitHub)

• 코드 실행: Jupyter 커널 세션을 “상태 유지(stateful)”로 관리하며 SSE로 출력 스트리밍
• 명령 실행: 포그라운드/백그라운드 실행, 중단, stdout/stderr 스트리밍
• 파일 시스템: 업로드/다운로드/검색(glob)/권한 변경 등
• 메트릭: CPU/메모리 등 모니터링(+ SSE로 watch)

특히 “코드 인터프리터”는 단발 실행이 아니라 컨텍스트(세션) 유지가 핵심이라, 에이전트가 여러 번 실행/수정/재실행하는 워크플로우에 맞습니다. (GitHub)

3) Specs (OpenAPI 계약)

• sandbox-lifecycle.yml: 샌드박스 생성/목록/상태/삭제/pause/resume/TTL 갱신/포트 엔드포인트 조회 (GitHub)
• execd-api.yaml: 코드/명령/파일/메트릭 API (보안 헤더 포함) (GitHub)

---

네트워크 정책: Ingress + Egress가 따로 있다

OpenSandbox가 “에이전트 실행 인프라” 느낌이 나는 부분이 네트워크 쪽입니다. (GitHub)

Ingress Gateway (외부 → 샌드박스 포트 라우팅)

• 샌드박스 인스턴스로 HTTP/WebSocket 리버스 프록시
• 라우팅 모드:
  • Header 모드: OpenSandbox-Ingress-To 또는 Host 헤더로 (sandboxId, port) 결정
  • URI 모드: /{sandboxId}/{port}/... 형태로 라우팅 (GitHub)

Egress Sidecar (샌드박스 → 외부 네트워크 제어)

• FQDN(도메인) 기반 allowlist/denylist로 outbound 트래픽 제어
• 기본 “deny-all”에서 시작해 정책으로 허용을 열어주는 방식
• 현재는 DNS Proxy 레이어가 먼저 구현되고, nftables 기반 네트워크 필터 레이어는 로드맵에 포함되어 있습니다. (GitHub)

즉, “AI가 만든 코드가 인터넷 마음대로 나가서 뭔가를 유출/오남용”하는 것을 도메인 단위로 통제할 수 있게 설계되어 있어요. (GitHub)

---

SDK/예제: 어떤 식으로 붙이나?

README 기준으로, OpenSandbox는 다음 시나리오들을 공식 예제로 제공합니다. (GitHub)

• 코딩 에이전트 실행: Claude Code / Gemini CLI / OpenAI Codex CLI 등을 샌드박스 안에서 구동 (GitHub)
• 코드 인터프리터: 샌드박스 생성 → 명령 실행 → 파일 read/write → 코드 실행(언어 선택, 출력 스트리밍) (GitHub)
• 브라우저 자동화: headless Chrome, Playwright + VNC/DevTools 접근 (GitHub)
• 원격 개발환경: VS Code Web(code-server), Desktop(VNC) (GitHub)
• RL training 같은 워크로드 (GitHub)

SDK 언어는 Python/Java(Kotlin)/JS/TS/C# 등이 언급되고, Go SDK는 로드맵으로 표시되어 있습니다. (GitHub)

---

“직접 도입” 관점에서의 최소 흐름(MVP)

1. 서버 설치/기동

• opensandbox-server 설치 후 설정 파일(TOML) 생성, Docker 또는 K8s 런타임 선택 (GitHub)

1. SDK로 샌드박스 생성

• 이미지(예: code-interpreter 이미지) + entrypoint + env + timeout(TTL) + 리소스 제한으로 생성 (GitHub)

1. 샌드박스 내부 작업

• 파일 업로드/다운로드, 명령 실행, 코드 실행(세션 유지) (GitHub)

1. (필요 시) 네트워크 통제

• 외부에서 샌드박스 포트 접근은 ingress로 라우팅
• 샌드박스의 outbound는 egress 정책으로 allowlist (GitHub)

---

OpenSandbox를 쓰면 좋은 경우 / 굳이 안 써도 되는 경우

좋은 경우

• 에이전트가 생성한 코드/툴을 “실제로 실행”해야 하는데, 보안/격리/재현성이 필요할 때
• 코드 인터프리터(상태 유지) + 파일/명령 + 스트리밍 출력이 필요한 제품(IDE형, 분석형, 에이전트형)
• Docker 로컬 테스트 → Kubernetes 운영까지 같은 API로 가져가고 싶을 때 (GitHub)

굳이 아닌 경우

• 단순히 함수 몇 개 실행하는 정도로 충분하고, 컨테이너 격리까지는 과한 경우(다만 제품이 커지면 다시 필요해지는 경우가 많음)

---