sbx create

sbx create

sbx create는 에이전트용 샌드박스를 만드는 명령이에요. 호스트 워크스페이스에 접근하는 샌드박스를 생성해 AI 에이전트를 실행하고 싶을 때 사용해요.

출처: 문서

본문

sbx create는 에이전트가 호스트 워크스페이스에 접근할 수 있는 샌드박스를 만들어요.

첫 번째 위치 인자는 내장 에이전트 이름이거나 샌드박스 kit 참조일 수 있어요. kit 참조는 로컬 디렉터리, ZIP 파일, git 저장소, OCI 참조일 수 있어요. 상대 로컬 참조는 ./my-kit나 ../my-kit.zip처럼 명시적 경로여야 해요.

경로를 생략하면 워크스페이스 바인드 마운트 없이 샌드박스를 만들어요. 그러면 에이전트는 파일 대신 컨테이너 자체 파일시스템에서 작업해요.

생성 후 에이전트에 연결하려면 sbx run --name SANDBOX를 사용해요.

사용 가능한 에이전트: claude, codex, copilot, cursor, devin, docker-agent, droid, gemini, kiro, opencode, shell

--cloud와 함께: 에이전트용 클라우드 샌드박스를 만들어요. 클라우드 샌드박스에는 호스트 워크스페이스가 없어서 에이전트 뒤에 경로가 오지 않아요. 크기는 --cpus와 --memory에서 오고 청구 가능한 형태여야 해요. 지정하지 않으면 2 CPU와 4 GiB를 받아요. -t/--template로 이름 붙인 템플릿은 클라우드 레지스트리에 이미 존재해야 해요. 클라우드 샌드박스는 클라우드 네트워크 정책을 사용하고, 호스트 네트워크·HTTP 정책은 적용되지 않아요. 생성 후 연결은 sbx --cloud run --name SANDBOX로 해요.

sbx create [flags] AGENT|SANDBOX_KIT [PATH...]

지원하는 하위 명령은 다음과 같아요.

명령 설명
sbx create claude claude용 샌드박스 생성
sbx create codex codex용 샌드박스 생성
sbx create copilot copilot용 샌드박스 생성
sbx create cursor cursor용 샌드박스 생성
sbx create devin devin용 샌드박스 생성
sbx create docker-agent docker-agent용 샌드박스 생성
sbx create droid droid용 샌드박스 생성
sbx create gemini gemini용 샌드박스 생성
sbx create kiro kiro용 샌드박스 생성
sbx create opencode opencode용 샌드박스 생성
sbx create shell shell용 샌드박스 생성

지원하는 옵션은 다음과 같아요.

옵션 기본값 설명
--allow-network 클라우드 샌드박스 이그레스로 허용할 네트워크 패턴이에요 (클라우드 전용, 여러 번 지정 가능).
--clone 워크스페이스를 바인드 마운트하는 대신 에이전트를 호스트 Git 저장소의 개인 인-컨테이너 클론에서 실행해요 (읽기 전용 마운트; 에이전트 커밋은 호스트의 sandbox- git 리모트로 접근 가능).
--cpus 0 샌드박스에 할당할 CPU 수예요 (0 = 자동: 호스트 전체 CPU).
--deny-network 생성 시 샌드박스별 네트워크 거부 규칙을 추가해요. 여러 번 지정 가능해요. 새 샌드박스에만 적용되고, sbx policy ls 또는 sbx policy rm network --sandbox --resource로 나중에 조회·제거할 수 있어요. 로컬 거부는 이그레스를 좁힐 뿐 넓히지 않아 중앙 거버넌스 아래에서 안전해요.
-e, --env 샌드박스에 환경 변수를 설정해요 (반복 가능): KEY=VALUE, 또는 현재 환경에서 값을 가져올 KEY.
--env-file 파일에서 환경 변수를 읽어요 (반복 가능). --env가 파일보다 우선하고, 이후 파일이 이전 파일보다 우선해요.
--image-ref 인라인 모드 클라우드 생성을 위한 OCI 이미지 참조예요 (--template와 상호 배타, --cpus·--memory 필요).
--kit 실험적 — 추가 kit 참조예요 (mixin이어야 함; 디렉터리, ZIP, git, OCI). 여러 번 지정 가능.
--kit-arg 실험적 — kit가 선언한 인자 값이에요. 모든 kit에는 name=value, 하나만이면 kit.name=value (반복 가능).
--kit-args-file 실험적 — 한 줄에 하나씩 name=value kit 인자를 담은 파일이에요 (반복 가능); --kit-arg가 우선.
-m, --memory 이진 단위 메모리 한도예요 (예: 512m, 8g). 최소 512 MiB. 기본값은 호스트 메모리의 50%(512 MiB~32 GiB로 고정). 최대 max(호스트 메모리의 75%, 512 MiB).
--name 샌드박스 이름이에요 (최소 두 글자, 문자나 숫자로 시작, 문자·숫자·하이픈·마침표만 허용; --cloud에서 마침표는 거부, default는 예약).
--on-timeout delete --ttl이 지나면 delete(기본)는 샌드박스를 tombstone 처리하고, stop은 제자리에 멈춰 나중에 다시 시작 가능하게 해요 (클라우드 전용; stop은 계정 자격 필요).
-p, --publish 샌드박스 포트를 호스트에 게시해요 (반복 가능): [[HOST_IP:]HOST_PORT:]SANDBOX_PORT[/PROTOCOL].
--pull always 이미지 풀 정책이에요 (always/missing/never).
-q, --quiet 자세한 출력을 숨겨요.
--skills readonly 공유 스킬 저장소 모드예요: off, readonly, readwrite (에이전트 스킬 디렉터리, 예: ~/.claude/skills에 마운트). 기본은 readonly 또는 설정된 skills.defaultMode.
-t, --template 샌드박스에 쓸 컨테이너 이미지예요 (기본: 에이전트별 이미지).
--ttl 클라우드 샌드박스 TTL이에요 (예: 30m, 2h, 1h30m; 단위 대소문자 무시; 클라우드 전용; 기본: 서버 측).
-v, --volume 실험적 — 기존 영구 볼륨을 연결해요, NAME:MOUNTPATH (클라우드 전용, 실험적, 반복 가능).

예시

# Create a sandbox for Claude in the current directory
sbx create claude .

# Create a sandbox with a custom name
sbx create --name my-project claude /path/to/project

# Create with additional read-only workspaces
sbx create claude . /path/to/docs:ro

# Create without a workspace bind mount
sbx create claude

# Create from a local sandbox kit
sbx create ../path/to/my-agent/

# Add a mixin to a built-in agent
sbx create claude --kit ./my-mixin/

# Run the agent on an in-container clone of the host repo, wired back via a git-daemon
sbx create --clone claude .

# Create a cloud sandbox for claude
sbx --cloud create claude

# Create a named cloud sandbox with a mixin baked in
sbx --cloud create --name my-project claude --kit ./my-mixin/

# Create from a template that already exists in the cloud registry
sbx --cloud create -t TEMPLATE

더 알아보기