sbx run — 샌드박스에서 에이전트 실행

sandbox의 하위 명령인 sbx run은 샌드박스에서 에이전트를 실행하고, 없으면 샌드박스를 만들어요. 내장 에이전트, 로컬/OCI 키트, 클라우드 실행 등 다양한 실행 방식을 지원해요.

출처: 문서

본문

설명 (Description)

샌드박스에서 에이전트를 실행하고, 샌드박스가 없으면 만들어요.

첫 번째 위치 인자는 실행할 에이전트를 식별해요. 내장 에이전트 이름 또는 샌드박스 키트 참조일 수 있어요. 샌드박스 키트 참조는 로컬 디렉토리, ZIP 파일, git 저장소 또는 OCI 참조일 수 있어요. 상대 로컬 참조는 ./my-kit 또는 ../my-kit.zip 같은 명시적 경로여야 해요. 베어 값은 에이전트 또는 샌드박스 이름 의미를 유지해요. 기존 샌드박스에 이름으로 다시 붙으려면 --name을 사용해요. 이름 있는 샌드박스가 이미 존재하면 에이전트 위치 인자는 선택 사항이고 그 명세에서 읽혀요.

에이전트 인자는 "--" 구분자 뒤에 전달해요. 추가 워크스페이스는 추가 인자로 제공할 수 있어요. ":ro"를 붙이면 읽기 전용으로 마운트돼요. 읽기 전용 인자는 단일 파일을 이름 지을 수 있어, 샌드박스가 쓸 수 있는 워크스페이스 안에서도 그 경로 하나를 닿지 못하게 해요.

경로를 생략하면 현재 디렉토리를 마운트해요. 경로를 전달하면 다른 워크스페이스를 마운트해요.

붙이지 않고 샌드박스만 만들려면 sbx create를 대신 사용하거나, --detached(-d)를 전달해 샌드박스 ID를 출력하고 인터랙티브 세션을 열지 않고 종료해요.

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

--cloud 사용 시: 클라우드 샌드박스에서 에이전트를 실행하고, 샌드박스가 없으면 만들어요.

첫 번째 위치 인자는 실행할 에이전트를 식별해요: 내장 에이전트 이름 또는 샌드박스 키트 참조(로컬 디렉토리, ZIP 파일, git 저장소 또는 OCI 참조). 상대 로컬 참조는 ./my-kit 또는 ../my-kit.zip 같은 명시적 경로여야 해요. 클라우드 샌드박스에는 호스트 워크스페이스가 없어 에이전트 뒤에 경로가 오지 않아요. 에이전트 인자는 "--" 구분자 뒤에 전달해요.

기존 샌드박스(실행 중이든 중지됐든)가 있는 에이전트를 실행하면 재사용할 것인지 새로 만들 것인지 선택하라는 프롬프트가 떠요. --new로 프롬프트를 건너뛰고 항상 새 샌드박스를 만들어요. --name NAME은 그 이름의 샌드박스가 존재하면 재사용·재시작하고, 없으면 만들어요. 키트 템플릿(샌드박스 키트 또는 빌드 콘텐츠가 있는 mixin)을 구운 실행은 항상 새로 만들어요. --detached는 프롬프트를 건너뛰어요: --name과 함께면 그 샌드박스가 존재할 때 재시작하고, 아니면 새로 만들어요. --detached 없는 비대화형 실행은 거부되므로 스크립트는 --detached를 전달해요(예: sbx --cloud run -d claude && sbx --cloud exec ...).

크기는 --cpus와 --memory에서 오며 과금 가능한 형태에 도달해야 해요. 없으면 클라우드 샌드박스는 2 CPU와 4 GiB를 받아요. -t/--template로 이름 지은 템플릿은 클라우드 레지스트리에 이미 존재해야 하고 CLI는 업로드하지 않아요. 클라우드 샌드박스 모델은 https://docs.docker.com/ai/sandboxes/ 를 참고해요.

옵션 (Options)

전역 옵션 (Global options)

| 옵션 | 기본값 | 설명 | | --cloud | | 로컬 sandboxd 대신 Docker Cloud Sandboxes API로 디스패치 (점점 더 많은 동사 지원 — 현재 목록은 'sbx --cloud --help' 실행) | | -D, --debug | | 디버그 로깅 활성화 |

예시 (Examples)

# 현재 디렉토리에서 claude로 샌드박스 생성·실행
sbx run claude

# 로컬 샌드박스 키트에서 생성·실행
sbx run ../path/to/my-agent/

# OCI 샌드박스 키트에서 생성·실행
sbx run ghcr.io/foo/my-agent:latest

# 내장 에이전트에 mixin 추가
sbx run claude --kit ./my-mixin/

# 추가 워크스페이스(읽기 전용)와 함께 생성·실행
sbx run claude . /path/to/docs:ro

# 이름으로 기존 샌드박스에 재붙임 (명세에서 에이전트 읽음)
sbx run --name existing-sandbox

# 이름으로 기존 샌드박스에 재붙이고 예상 에이전트 확인
sbx run claude --name existing-sandbox

# 에이전트 인자로 샌드박스 실행
sbx run claude -- --continue

# 새 클라우드 샌드박스에서 claude 실행
sbx --cloud run claude

# 비대화형으로 클라우드 샌드박스 생성하고 ID 출력
sbx --cloud run --detached claude

# 그 이름의 클라우드 샌드박스 재사용, 없으면 생성
sbx --cloud run --name my-project claude

# 에이전트 인자로 실행
sbx --cloud run claude -- --continue

더 알아보기 (Learn more)

샌드박스 생성만 하려면 sbx create, 포트 관리는 sbx ports, 제거는 sbx rm을 참고해요.