sandboxd는 Lovable, Bolt, v0, Replit처럼 “앱을 만들어 달라”는 요청을 받아 격리된 개발 환경에서 코딩 에이전트를 실행하고, 결과물을 즉시 미리보기 URL로 노출하는 백엔드 엔진이다.
무엇을 해결하는가
AI 앱 빌더나 코딩 에이전트 플랫폼을 만들 때 어려운 부분은 모델 호출 자체보다 실행 인프라다. 사용자마다 독립 파일시스템을 만들고, 에이전트가 코드를 쓰게 하며, 개발 서버를 외부 URL로 라우팅하고, 사용하지 않는 환경은 비용 절감을 위해 재워야 한다.
sandboxd는 이 흐름을 단일 Docker 호스트에서 처리한다.
POST /sandbox # 격리 컨테이너 생성
POST /tasks # OpenCode 또는 Claude Code 실행
http://<id>.preview... # 결과 앱 미리보기아키텍처
| 구성 요소 | 역할 |
|---|---|
| Go 제어 평면 | 샌드박스 생성, 실행, 중지, 작업 관리 API |
| Docker | 사용자별 격리 컨테이너 실행 |
| Traefik | 샌드박스별 preview URL 라우팅과 TLS |
| SQLite | 샌드박스 상태의 단일 소스 |
| 작업 디렉터리 | 컨테이너가 잠들어도 파일을 보존하는 영속 워크스페이스 |
Kubernetes, 별도 데이터베이스, 메시지 큐 없이 시작할 수 있다는 점이 핵심이다. 단일 서버에서 여러 샌드박스를 운영하고, 유휴 상태가 되면 컨테이너를 멈춰 메모리를 회수한다.
에이전트 실행
기본 이미지에는 OpenCode와 Claude Code CLI가 포함된다. API로 샌드박스를 만들고 작업 프롬프트를 보내면 에이전트가 ~/workspace/app 안에서 코드를 작성한다.
API=http://127.0.0.1:9090
ID=$(curl -s -XPOST $API/sandbox \
-H 'content-type: application/json' \
-d '{"ports":[3000]}' | sed -E 's/.*"id":"([^"]+)".*/\1/')
curl -s -XPOST $API/v1/sandboxes/$ID/tasks \
-H 'content-type: application/json' \
-d '{"prompt":"create a Vite todo app and run it on port 3000","agent":"opencode"}'작업 이벤트는 Server-Sent Events로 스트리밍된다. 앱이 3000번 포트에서 뜨면 http://s-<id>-3000.preview.localhost 같은 주소로 접근할 수 있다.
어디에 적합한가
- AI 앱 빌더: 사용자별 “프롬프트 → 앱 → preview URL” 경험 제공
- 코딩 에이전트 플랫폼: 여러 사용자의 에이전트 실행 환경을 격리
- 팀용 코딩 플레이그라운드: 브랜치·작업별 임시 개발 환경 제공
- SaaS 팩토리: 다수의 작은 앱을 한 서버에서 생성·호스팅
단순히 개인이 한두 개 컨테이너를 띄우는 용도라면 docker run, Docker Compose, LXD가 더 단순하다. sandboxd의 가치는 다중 사용자, 자동 sleep/wake, preview URL, API 기반 작업 수명주기가 필요할 때 나온다.
Docker Sandbox와의 차이
docker-sandbox가 MicroVM 기반의 강한 보안 격리에 초점을 둔다면, sandboxd는 AI 앱 빌더 제품에 필요한 운영 흐름에 초점을 둔다.
| 항목 | sandboxd | Docker Sandbox |
|---|---|---|
| 핵심 목적 | 다중 샌드박스 운영과 preview URL | 에이전트 실행의 강한 격리 |
| 기반 | Docker 컨테이너 + Traefik | MicroVM |
| 제품 기능 | API, sleep/wake, 작업 스트리밍, 라우팅 | VM 수준 격리, 안전한 Docker-in-Docker |
| 적합한 사용자 | 앱 빌더·에이전트 플랫폼 개발자 | 신뢰할 수 없는 코드 실행 환경 운영자 |
한계와 주의점
현재 README 기준으로 단일 Docker 호스트를 목표로 한다. 대규모 멀티노드 스케줄링, 조직별 네트워크 정책, 엔터프라이즈급 감사 로그가 필요하다면 별도 보강이 필요하다. 또한 에이전트가 사용자 코드를 실행하는 구조이므로 API 인증, 비밀값 주입 범위, 네트워크 egress 정책을 운영 환경에서 반드시 설계해야 한다.
관련 문서
- docker-sandbox — MicroVM 기반 AI 에이전트 격리 실행 환경
- opencode — 터미널 기반 오픈소스 코딩 에이전트
- claude-code — Claude Code CLI 기반 코딩 에이전트
참고 자료
- tastyeffectco/sandboxd — GitHub 공식 저장소