샌드박스 환경 파일

샌드박스 환경 파일 (Sandbox environment files)

sbxenv.yaml 파일로 로컬·클라우드 샌드박스 설정을 캡처하고 공유하는 방법을 알아볼게요.

출처: 문서

본문

샌드박스 환경 파일은 로컬 또는 클라우드 샌드박스의 설정을 sbxenv.yaml 파일로 담아요. 프로젝트 기여자들과 공유하면 모두가 같은 에이전트, 도구, 리소스, 자격 증명을 CLI 플래그와 설정 단계를 반복하지 않고 사용할 수 있어요.

참고 (Note): sbx env는 실험적이에요. 명령 인터페이스와 파일 형식이 바뀔 수 있어요.

이 페이지의 예시는 명시되지 않는 한 로컬 샌드박스를 사용해요. 클라우드 설정과 수명 주기 차이는 Use a cloud environment 문서를 보세요.

환경 시작하기 (Start an environment)

환경 파일을 샌드박스에 마운트하는 디렉터리 밖에 두세요. 여기에는 기본 워크스페이스와 모든 additionalWorkspaces 마운트가 포함돼요. 예를 들어 프로젝트 옆에 두세요:

web-app-env/
├── sbxenv.yaml
└── web-app/

web-app-env/sbxenv.yaml을 만들어요. 이 예시는 에이전트에 공유 환경 변수와 Playwright 브라우저 테스트 도구를 주고, 애플리케이션의 개발 포트도 게시해요:

schemaVersion: "1"
name: web-app
agent: claude
workspace: ./web-app

kits:
  - docker.io/sbx/playwright-kit:latest

env:
  NODE_ENV: test

ports:
  - sandbox: 3000
    host: 3000

web-app-env에서 환경을 실행해요:

$ sbx env run

sbx가 환경 플랜을 보여주고 승인을 요청해요. 플랜을 승인하면 web-app 디렉터리가 워크스페이스가 되고, sbxenv.yaml은 샌드박스 밖에 남아요. 환경이 없으면 sbx가 web-app이라는 샌드박스를 만들고, Playwright와 Chromium을 설치하며, 샌드박스 포트 3000을 호스트에 게시해요. 그다음 에이전트에 붙어요. 이후 실행은 기존 샌드박스에 붙어요.

이 배치는 환경 파일을 에이전트가 쓰는 워크스페이스 밖에 두는 거예요. 나중에 additionalWorkspaces를 추가하면 sbxenv.yaml도 그 디렉터리들 밖에 두세요. 자세한 내용은 workspace 지침을 보세요.

명령 (Commands)

명령 (Command)	설명 (Description)
sbx env plan [PATH...]	환경을 적용하면 무엇이 바뀔지 변경·승인 없이 보여줌
sbx env run [PATH...]	승인된 플랜을 적용하고, 필요하면 환경을 만들고, 붙음
sbx env create [PATH...]	승인된 플랜을 적용하고 붙지 않고 환경을 만듦
sbx env exec [PATH...] -- COMMAND [ARG...]	수명 주기 명령 없이 기존 환경에서 명령 실행
sbx env rm [PATH...]	파괴 플랜(destroy plan)을 보여준 뒤 플랜에 이름이 있는 샌드박스와 리소스 제거

환경 파일을 쓰려면 그 경로를 sbx env에 전달해요. 디렉터리를 전달하면 sbx가 그 안에서 sbxenv.yaml을 찾아요. 경로를 전달하지 않으면 sbx가 명령을 실행하는 디렉터리에서 찾고, 있으면 사용자 기본값(user defaults)을 로드해요.

모든 sbx env 서브커맨드는 --name을 받아요. 이 플래그는 해당 명령의 샌드박스 이름을 설정하며, 파일의 name 필드나 자동 생성 이름을 덮어써요:

$ sbx env create --name web-app-test
$ sbx env exec --name web-app-test -- npm test
$ sbx env rm --name web-app-test

각 명령에 같은 파일 경로를 사용하세요. --name을 설정하면 샌드박스를 관리하는 모든 명령에 같은 이름을 사용하세요.

사용자 기본값 설정하기 (Set user defaults)

~/.sbxenv.yaml을 만들어 프로젝트 전반에 설정을 공유하세요. 예를 들어 이 파일은 Claude를 에이전트로 선택하고 sbx env를 실행하는 디렉터리를 마운트해요:

schemaVersion: "1"
agent: claude
workspace: ${{ env.projectDir }}

이 파일을 홈 디렉터리에 저장한 뒤 실행해요:

$ cd /projects/web-app
$ sbx env run

샌드박스는 /projects/web-app을 워크스페이스로 마운트해요. /projects/api에서 같은 명령을 실행하면 /projects/api를 마운트해요. 두 프로젝트에 별도의 sbxenv.yaml이 필요하지 않아요.

프로젝트에 sbxenv.yaml이 있으면 sbx는 그것을 사용자 기본값과 결합해요. 프로젝트 설정이 개별 기본값을 덮어써요. ports와 mcp.servers 같은 목록은 두 파일의 항목을 결합해요. 명령에 파일이나 디렉터리 경로를 전달하면 sbx는 ~/.sbxenv.yaml을 건너뛰어요.

~/.sbxenv.yaml에서 workspace를 ${{ env.projectDir }} 또는 ${{ env.projectDir }}/src 같은 하위 디렉터리로 설정할 수 있어요. 다른 워크스페이스 경로는 이 파일에서 받지 않아요.

사용자 기본값 파일은 name을 설정할 수 없어요. 샌드박스 이름은 프로젝트 환경 파일이나 --name으로 설정하세요.

디렉터리 참조 (Reference directories)

환경 파일에서 ${{ env.projectDir }}과 ${{ env.fileDir }}을 사용해 절대 디렉터리 경로를 넣을 수 있어요. 이것들은 호스트의 디렉터리를 가리켜요.

프로젝트 디렉터리 (Project directory)

${{ env.projectDir }}은 프로젝트 디렉터리의 절대 경로예요. sbx는 실행하는 명령에서 이 디렉터리를 골라요:

• sbx env run: 명령을 실행하는 디렉터리
• sbx env run /projects/web-app: /projects/web-app
• sbx env run /projects/web-app/custom.yaml: 파일이 들어 있는 /projects/web-app

여러 경로를 전달하면 첫 번째가 프로젝트 디렉터리를 설정해요. 그 명령이 로드하는 모든 파일은 env.projectDir에 같은 값을 사용해요.

이 참조를 각 프로젝트의 파일을 가리켜야 하는 공유 설정에 사용하세요. 예를 들어 workspace: ${{ env.projectDir }}/src는 선택한 프로젝트의 src 디렉터리를 마운트해요.

파일 디렉터리 (File directory)

${{ env.fileDir }}은 참조를 쓰는 환경 파일이 들어 있는 디렉터리의 절대 경로예요. 예를 들어 /shared/environment.yaml 안에서는 그 값이 /shared예요.

이 참조를 환경 파일이 옆에 저장된 파일을 찾아야 할 때 사용하세요. 예를 들어 설정 스크립트가 /shared/scripts/setup.sh라고 해요. /shared/environment.yaml에 이 수명 주기 명령을 추가해 /shared에서 스크립트를 실행해요:

lifecycle:
  initialize:
    - command: ./scripts/setup.sh
      workdir: ${{ env.fileDir }}

이 환경 파일을 다른 디렉터리의 프로젝트와 함께 써도 명령은 /shared에서 실행돼요.

상대 워크스페이스 경로는 이미 환경 파일이 들어 있는 디렉터리를 기준으로 해요. 예를 들어 /shared/environment.yaml의 workspace: ./src는 /shared/src를 마운트해요.

두 디렉터리 참조는 YAML 값에는 나타날 수 있지만, 필드 이름이나 args 블록 안에는 쓸 수 없어요.

환경 파라미터화하기 (Parameterize an environment)

같은 환경 파일을 쓰임새마다 값이 달라질 때는 최상위 args 블록에서 입력을 선언해요. 각 인자는 default 또는 required: true 중 정확히 하나를 가져야 해요:

schemaVersion: "1"
name: web-app
agent: claude

args:
  channel:
    default: stable
    description: Release channel
    enum:
      - stable
      - beta
  endpoint:
    required: true
    description: API endpoint
  cpus:
    default: "4"
    pattern: "[1-9][0-9]*"

env:
  RELEASE_CHANNEL: ${{ env.args.channel }}
  API_ENDPOINT: ${{ env.args.endpoint }}

sandboxOptions:
  cpus: ${{ env.args.cpus }}

선언된 인자는 YAML 값이 나타날 수 있는 곳 어디서든 ${{ env.args.NAME }}으로 참조해요. 참조는 필드 이름이나 args 블록 안에는 쓸 수 없어요. 따옴표 없는 참조는 치환 후 YAML 값으로 해석되므로, 이 예시의 cpus 값은 정수가 돼요. 참조를 따옴표로 감싸 문자열로 유지하세요.

모든 sbx env 명령은 반복 가능한 --env-arg NAME=VALUE 플래그를 받아요. 플래그로 준 값이 환경 파일의 기본값을 대체해요:

$ sbx env run --env-arg endpoint=https://api.example.com --env-arg channel=beta

--env-args-file로 파일에서 값을 로드해요. 빈 줄이 아니고 주석이 아닌 각 줄은 NAME=VALUE 형태여야 해요:

# production.args
channel=beta
endpoint=https://api.example.com

$ sbx env run --env-args-file production.args

여러 인자 파일을 전달할 수 있어요. 나중 파일이 앞 파일보다 우선하고, --env-arg 플래그가 모든 인자 파일보다 우선해요. 값은 =를 포함할 수 있고, 인자 파일의 값은 셸이 확장하지 않고 리터럴로 읽어요.

인자 참조와 두 디렉터리 참조만 환경 파일에서 확장되는 변수 표현식이에요. ${VAR} 같은 셸 스타일 표현식은 호스트 환경에서 확장되지 않아요. 다른 달러 기호는 리터럴로 남으므로, $PATH:/opt/bin 같은 값은 그대로 전달돼요. $${{ env.args.NAME }}을 쓰면 리터럴 텍스트 ${{ env.args.NAME }}을 만들어요. 치환된 값은 두 번째 확장되지 않아요.

흔한 워크플로 (Common workflows)

다음 예시들은 환경 파일 필드를 프로젝트에 맞게 적용할 수 있는 구성으로 결합해요.

팀 기본값과 개인 설정 결합하기 (Combine team defaults and personal settings)

공유 구성을 마운트된 워크스페이스 밖의 버전 관리되는 환경 디렉터리에 두세요. 머신별 설정은 버전 관리에서 제외된 파일에 두세요. 예를 들어 web-app 디렉터리 옆에 base.sbxenv.yaml을 커밋해요:

schemaVersion: "1"
name: web-app
agent: claude
workspace: ./web-app

env:
  NODE_ENV: development

sandboxOptions:
  cpus: 4
  memory: 8g

local.sbxenv.yaml을 .gitignore에 추가하고 개인 설정에 사용해요:

env:
  LOG_LEVEL: debug

sandboxOptions:
  memory: 12g

두 파일을 병합 순서대로 전달해요:

$ sbx env run base.sbxenv.yaml local.sbxenv.yaml

중첩 매핑은 키별로 병합되고, 목록은 이어붙여지며, 나중 파일의 값이 앞의 스칼라 값을 대체해요. 이 예시에서 샌드박스는 4 CPU, 12 GB 메모리, 그리고 두 환경 변수를 가져요. 각 상대 워크스페이스 경로는 그것을 선언한 파일의 디렉터리를 기준으로 해석돼요.

여러 저장소에 걸쳐 작업하기 (Work across multiple repositories)

에이전트가 변경을 조정하거나 공유 코드·문서를 참조해야 할 때 관련 저장소를 기본 프로젝트 옆에 마운트해요:

# sbxenv.yaml in the directory above the repositories
schemaVersion: "1"
name: web-platform
agent: codex

workspace: ./web-app

additionalWorkspaces:
  - path: ./shared-components
  - path: ./architecture-docs
    readOnly: true

에이전트는 web-app에서 시작하고, shared-components를 수정할 수 있으며, architecture-docs를 바꾸지 않고 읽을 수 있어요. 환경 파일은 세 워크스페이스 모두 밖에 있어요. 상대 경로는 그 경로를 선언한 환경 파일의 디렉터리를 기준으로 해석돼요. 기본 워크스페이스가 clone mode여도 추가 워크스페이스는 직접 마운트돼요.

자동화에서 환경 재사용하기 (Reuse an environment in automation)

대화형 개발과 자동화 작업에 같은 커밋된 환경을 사용해요. 개발자는 run으로 에이전트에 붙어요:

$ sbx env run

자동화는 붙지 않고 샌드박스를 만들고, 그 안에서 명령을 실행하고, 끝나면 제거할 수 있어요:

$ sbx env create --auto-approve
$ sbx env exec -- npm test
$ sbx env rm --force

--auto-approve는 그 호출의 플랜을 승인하며, 이후 호출의 동의를 기록하지 않아요. 무인 create·run마다 이 플래그를 사용하세요. --force는 파괴 플랜을 승인하고, 샌드박스가 사용 중이어도 제거해요.

secrets 아래의 명령과 볼트 참조는 호스트에서 해석되므로, 자동화 실행기가 참조하는 도구와 인증을 제공해야 해요. 시크릿 값은 환경 파일 밖에 남아요.

클라우드 환경 사용하기 (Use a cloud environment)

sbx --cloud env로 환경 파일에서 클라우드 샌드박스를 관리해요. 계정·CLI 요구사항은 Cloud sandboxes 문서를 보세요.

다음을 cloud.sbxenv.yaml로 저장해요:

schemaVersion: "1"
name: cloud-project
agent: shell

env:
  PROJECT_NAME: example

sandboxOptions:
  cpus: 2
  memory: 4g

플랜을 검토하고, 붙지 않고 샌드박스를 만들고, 명령을 실행해요:

$ sbx --cloud env plan ./cloud.sbxenv.yaml
$ sbx --cloud env run --detached ./cloud.sbxenv.yaml
$ sbx --cloud env exec ./cloud.sbxenv.yaml -- printenv PROJECT_NAME

클라우드 환경은 에이전트와 키트, 환경 변수, CPU·메모리 한도, 지원되는 제공 업체의 자격 증명, 호스트 수명 주기 명령을 지원해요. 리소스 한도는 클라우드 크기와 일치해야 해요. 수명 주기 명령은 여전히 여러분의 머신에서 여러분의 권한으로 실행돼요.

로컬 파일을 클라우드 모드에서 쓰기 전에 workspace, additionalWorkspaces, clone 옵션, ports, registries, MCP 서버 정의를 제거하세요. 클라우드 환경은 GPU, USB, 디스플레이, 공유 스킬, 템플릿, 거버넌스 프로필 같은 로컬 샌드박스 옵션도 거부해요. 이 확인들은 호스트 명령이나 프로비저닝 전에 실행돼요. 프로젝트 파일은 sbx --cloud cp로 전송하거나 샌드박스 안에서 저장소를 클론하세요.

플랜은 상속된 클라우드 자격 증명을 보여줘요. 샌드박스 범위 자격 증명이 계정 기본값을 덮어쓰고, secrets에 선언된 자격 증명이 둘 다를 덮어써요. 리터럴 값을 선언하거나 snapshot: true를 사용해 호스트 명령이나 볼트 참조를 한 번 해석하세요. 동적 시크릿 소스와 커스텀 자격 증명 제공 업체는 지원되지 않아요. 자격 증명 바인딩은 키트 자격 증명에 대한 클라우드 지원과 키트의 주입 도메인에 대한 명시적 승인이 필요해요.

시크릿과 바인딩 변경은 샌드박스를 다시 만들어야 해요. 업데이트된 env 값은 이후 세션에 적용돼요. 실행 중인 에이전트에 다시 합류하면 그 프로세스의 환경이 유지돼요.

이후 명령에는 같은 머신, Docker 정체성, 클라우드 엔드포인트, 순서가 같은 파일 경로를 사용하세요. sbx login은 환경 상태를 여러분의 Docker 정체성과 연결해요. DOCKER_ACCESS_TOKEN을 쓰면 토큰을 바꾸면 별도의 상태 범위가 시작돼요.

작업이 끝나면 환경을 제거해요:

$ sbx --cloud env rm ./cloud.sbxenv.yaml

제거는 샌드박스와 이 환경이 프로비저닝한 시크릿만 삭제해요. 상속된 시크릿은 남아요. --prune-bindings를 전달하지 않으면 전역 바인딩은 유지돼요. 무인 실행에는 create·run에 --auto-approve, rm에 --force를 사용하세요.

생성이 중단되면 23시간 안에 같은 명령과 변경되지 않은 선언으로 재시도하세요. 해결되지 않은 요청은 제거를 막아요. 복구 메시지를 따르고, 원래 요청이 해결될 때까지 그 저널을 보관하세요.

환경 플랜 검토하기 (Review an environment plan)

sbx env create, sbx env run, sbx env rm은 환경이 샌드박스 밖에서 만드는 변경을 보여주고 적용 전 승인을 요청해요. 플랜에는 호스트 명령, 자격 증명, 바인딩, MCP 등록, 디렉터리, 키트, 게시된 포트, 샌드박스 옵션, 환경 변수가 포함돼요.

sbx env plan을 실행해 적용 플랜을 변경·승인·기록 없이 검사해요:

$ sbx env plan

플랜은 환경 파일을 환경의 마지막 적용 상태와 호스트의 리소스와 비교해요. 변경되지 않고 이미 승인된 리소스는 생략해요. 리터럴 시크릿 값은 SHA-256 다이제스트로 나타나요. 시크릿 참조, 호스트 명령, 환경 변수, 포트, 경로, 바인딩 도메인은 검토할 수 있게 보여요.

대화형 승인은 sbx 상태 디렉터리 아래 환경에 기록돼요. 호스트 명령이 없는 플랜은 환경이 바뀌거나 리소스가 없어질 때까지 이후 호출에서 자동으로 적용돼요. --auto-approve로 준 승인은 그 호출에만 적용돼요.

환경 업데이트하기 (Update an environment)

기존 샌드박스에서 sbx env run은 업데이트된 env 값을 새 에이전트 세션에 적용하고 선언된 MCP 서버를 조정해요. 워크스페이스, 키트, 포트, 시크릿, 바인딩, sandboxOptions 변경은 샌드박스가 다음에 만들어질 때만 적용돼요. sbx env rm으로 환경을 제거한 뒤 다시 만들어 그 변경을 적용하세요.

환경 제거하기 (Remove an environment)

시크릿과 레지스트리 자격 증명은 샌드박스 범위예요. 자격 증명 바인딩과 MCP 서버 등록은 호스트 전역이며 여러 샌드박스가 공유할 수 있어요.

sbx env rm은 호스트의 리소스에서 파괴 플랜을 만든다. 플랜에는 환경 파일이 더 이상 선언하지 않는 자격 증명을 포함해 샌드박스 범위에 저장된 모든 자격 증명이 들어가요. 승인 후 sbx는 플랜에 이름이 있는 리소스만 제거해요.

--prune-bindings를 전달하지 않으면 전역 자격 증명 바인딩은 유지돼요. MCP 등록은 다른 샌드박스에서 계속 사용할 수 있어요.

실패한 만들기 후 정리하기 (Clean up after a failed create)

시크릿 프로비저닝, 바인딩 업데이트, MCP 서버 등록은 샌드박스 생성 전에 일어나요. 샌드박스 생성이 실패하면 범위 시크릿은 남고, 바인딩과 MCP 등록도 남을 수 있어요. 같은 경로로 sbx env rm을 실행해 범위 시크릿을 제거하세요. 선언된 전역 바인딩도 제거하려면 --prune-bindings를 전달하세요. MCP 등록은 호스트 전역이라 정리 후에도 남아요.

파일 참조 (File reference)

최상위 필드 (Top-level fields)

필드 (Field)	타입 (Type)	필수 (Required)	기본값 (Default)	설명 (Description)
schemaVersion	string	예	없음	스키마 버전. 지원되는 값은 "1"
name	string	아니요	<agent>-<workspace-basename>	샌드박스 이름, --name으로 덮어씀
agent	string	예	없음	기본 제공 에이전트 또는 에이전트 키트 이름
args	map	아니요	없음	환경 인자. args 참조
kits	list	아니요	없음	생성 시 설치할 키트. kits 참조
workspace	string 또는 object	아니요	호스트 마운트 없음	기본 워크스페이스. workspace 참조
additionalWorkspaces	list	아니요	없음	마운트할 추가 디렉터리. additionalWorkspaces 참조
env	문자열 map	아니요	없음	샌드박스용 환경 변수
sandboxOptions	object	아니요	없음	생성 옵션. sandboxOptions 참조
secrets	map	아니요	없음	서비스 자격 증명. secrets 참조
bindings	map	아니요	없음	자격 증명 주입 승인. bindings 참조
registries	map	아니요	없음	레지스트리 pull 자격 증명. registries 참조
mcp	object	아니요	없음	MCP 서버. mcp 참조
ports	list	아니요	없음	포트 매핑. ports 참조
lifecycle	object	아니요	없음	호스트 명령. lifecycle 참조

args

args는 인자 이름을 선언에 매핑해요. 이름은 문자나 밑줄로 시작해야 하고, 문자·숫자·밑줄·하이픈을 포함할 수 있어요. 각 선언은 default 또는 required: true 중 정확히 하나를 설정해야 해요.

필드 (Field)	타입 (Type)	기본값 (Default)	설명 (Description)
default	string	없음	명령이 인자를 제공하지 않을 때 쓰는 값
required	boolean	false	명령이 인자를 제공하도록 요구
description	string	없음	명령 출력에 표시되는 설명
enum	문자열 list	없음	인자에 허용되는 값
pattern	string	없음	전체 인자 값에 일치하는 Go(RE2) 표현식

enum과 pattern은 함께 쓸 수 없어요.

kits

kits는 로컬 디렉터리, ZIP 아카이브, OCI 레지스트리 참조, git+https:// 또는 git+ssh:// 접두사가 있는 Git URL을 받아요. 키트는 도구를 설치하고, 샌드박스를 설정하고, 에이전트에 프로젝트별 지침을 줄 수 있어요. 이 페이지의 예시는 기본 제공 에이전트와 v2 믹스인을 짝지워요. 그 형식은 Kits v2를, v3 키트 선택 시 Version compatibility를 보세요.

환경 파일은 키트를 선택하고 샌드박스의 호스트 리소스를 설정해요. 키트 디스크립터(descriptor)는 패키지 자체를 정의해요. 환경 파일의 schemaVersion은 키트 디스크립터의 스키마 버전과 무관해요.

명시적 상대 경로는 그 경로를 선언한 환경 파일의 디렉터리를 기준으로 해석돼요. 여기에는 ., .., ./나 ../로 시작하는 경로, .zip으로 끝나는 상대 경로가 포함돼요. organization/kit 같은 맨 참조는 레지스트리 참조로 유지돼요.

객체 항목을 사용해 키트에 인자를 전달해요. source를 키트 참조로 설정하고 args 아래의 값에 키트의 인자 이름을 매핑해요:

kits:
  - source: ./kits/tool
    args:
      version: ${{ env.args.channel }}

원격 키트 소스는 kit.allowedSources 설정과 일치해야 해요. Docker Hub는 기본적으로 허용돼요. docker/sbx-kits-contrib의 Git 키트를 쓰려면 그 소스를 추가해요:

$ sbx settings set kit.allowedSources '["docker.io/","github.com/docker/"]'

이 설정은 전체 허용 목록을 대체하므로 유지하고 싶은 기존 소스를 포함하세요. 재현 가능한 설치를 위해 Git 키트는 ref URL 파라미터로 고정하고, OCI 키트는 불변 태그나 다이제스트로 고정하세요.

workspace

문자열로 지정하면 workspace는 경로예요. clone mode에는 객체 형태를 사용하세요. workspace를 생략하면 호스트 바인드 마운트 없는 샌드박스를 만들어요. workspace: .을 설정하면 그 경로를 선언한 환경 파일이 들어 있는 디렉터리를 마운트해요.

sbx는 환경 파일을 샌드박스 안에 읽기 전용으로 마운트해요. 파일을 직접 마운트된 워크스페이스 밖, 또는 워크스페이스 루트에 직접 두세요.

필드 (Field)	타입 (Type)	필수 (Required)	기본값 (Default)	설명 (Description)
path	string	예	없음	워크스페이스 디렉터리. 상대 경로는 선언 파일의 디렉터리 기준
clone	boolean	아니요	false	sbx create --clone에 해당하는 개인 클론 사용

--clone 또는 --clone=false로 한 create·run 호출의 workspace.clone을 덮어쓸 수 있어요.

additionalWorkspaces

각 추가 워크스페이스는 기본 워크스페이스 뒤에 마운트돼요. 상대 경로는 그 경로를 선언한 환경 파일의 디렉터리를 기준으로 해석돼요.

필드 (Field)	타입 (Type)	필수 (Required)	기본값 (Default)	설명 (Description)
path	string	예	없음	마운트할 디렉터리
readOnly	boolean	아니요	false	디렉터리를 읽기 전용으로 마운트

sandboxOptions

필드 (Field)	타입 (Type)	기본값 (Default)	설명 (Description)
template	string	없음	커스텀 샌드박스 템플릿 이미지
memory	string	없음	메모리 한도. 8g 또는 512m처럼
cpus	integer	0	CPU 수. 0은 모든 호스트 CPU를 할당
pullPolicy	string	always	이미지 pull 정책: always, missing, never
profile	string	없음	거버넌스 프로필 이름
skills	string	데몬 기본값	공유 에이전트 스킬 저장소 접근: off, readonly, readwrite
display	boolean	false	그래픽 애플리케이션용 디스플레이 소켓 프로비저닝
gpu	boolean	false	호스트 GPU를 샌드박스로 패스스루
usb	문자열 list	없음	샌드박스로 패스스루할 USB 장치 선택자

skills는 공유 에이전트 스킬 저장소 접근을 제어해요. off로 설정하면 마운트를 생략하고, readonly는 저장소를 읽기 전용으로 마운트하며, readwrite는 샌드박스가 공유 스킬을 수정하게 해요. 생략하면 조직이 바꾸지 않는 한 데몬의 기본값(readonly)을 사용해요.

lifecycle

lifecycle 블록은 여러분의 사용자 권한으로 호스트에서 실행되는 명령을 선언해요. 워크스페이스 만들기, 픽스처 시딩, 상태 아카이브처럼 샌드박스 밖에서 해야 하는 작업에 수명 주기 명령을 사용하세요.

lifecycle:
  initialize:
    - name: Prepare workspace
      command: test -d web-app || git clone https://github.com/example/web-app
      timeout: 5m
  postCreate:
    - command: ./scripts/seed-fixtures.sh
      workdir: web-app
  preRemove:
    - command: ./scripts/archive-state.sh

수명 주기 단계는 다음 시점에 실행돼요:

단계 (Phase)	시점 (Timing)
initialize	다른 create·run 작업 전. 모든 create·run마다 실행
postCreate	새 샌드박스 생성 후. run에서는 붙기 전. 기존 샌드박스에 붙을 때는 실행되지 않음
preRemove	제거를 승인한 뒤 sbx가 리소스를 삭제하기 전. 실패는 경고를 내고 제거는 계속됨

sbx env exec는 수명 주기 명령을 실행하지 않아요. 한 단계 안의 명령은 순서대로 실행되고 첫 실패에서 멈춰요. initialize 명령을 두 번 이상 실행해도 안전하게 만들어 두세요.

preRemove 명령이 끝나면 sbx가 파괴 플랜을 다시 생성해요. 명령이 승인된 플랜에 포함되지 않은 변경을 만들면 제거가 멈춰요.

각 명령은 command가 필요하고 다음 필드를 받아요:

필드 (Field)	타입 (Type)	기본값 (Default)	설명 (Description)
name	string	명령 텍스트	진행·플랜 출력에 표시되는 라벨
command	string	없음	사용자의 셸에 전달되는 명령
workdir	string	프로젝트 디렉터리	호스트 작업 디렉터리. 상대 경로는 첫 파일의 디렉터리 기준
timeout	string	없음	최대 실행 시간. 90s 또는 5m처럼

명령은 sbx 프로세스의 환경을 상속하고 다음 변수를 받아요:

• SBX_LIFECYCLE_PHASE
• SBX_ENV_FILE 및 SBX_ENV_FILES
• SBX_ENV_DIR
• SBX_SANDBOX_NAME
• SBX_AGENT
• SBX_WORKSPACE

환경 파일의 env 값과 해석된 시크릿은 호스트 명령에 전달되지 않아요.

수명 주기 명령이나 자격 증명 command 소스가 있는 플랜은 명령 텍스트가 바뀌지 않아도 기본적으로 매 호출 승인이 필요해요. --auto-approve로 한 호출을 승인하거나, --skip-host-commands로 수명 주기 명령을 건너뛰거나, env.rememberHostCommands를 켜서 명령이 바뀔 때까지 승인을 기억하게 해요:

$ sbx settings set env.rememberHostCommands true

secrets

secrets는 서비스 이름을 시크릿 소스에 매핑해요. 각 항목은 value, ref, command 중 정확히 하나를 설정해야 해요. 시크릿은 환경이 생성될 때 샌드박스 범위로 저장돼요.

필드 (Field)	타입 (Type)	기본값 (Default)	설명 (Description)
value	string	없음	리터럴 시크릿 값
ref	string	없음	op://Vault/Item/field 같은 볼트 URI
command	string	없음	표준 출력이 시크릿이 되는 호스트 셸 명령
snapshot	boolean	false	ref나 command를 호스트에서 한 번 해석하고 결과를 리터럴로 저장
refresh	string	없음	ref·command의 해석 정책. on-demand 또는 55m처럼
backend	string	자동	ref의 리졸버: sdk 또는 cli
noVerify	boolean	false	프로비저닝 중 ref·command가 해석되는지 검증 건너뛰기

경고 (Warning): 리터럴 value는 파일에 읽기 접근이 있는 누구에게나 보여요. ref로 볼트 URI를 쓰거나 command로 런타임에 값을 얻으세요.

secrets:
  anthropic:
    ref: op://Private/Anthropic/api-key
    refresh: 55m
  github:
    command: gh auth token

클라우드 환경에서는 ref·command 소스에 snapshot: true를 설정해요:

secrets:
  github:
    command: gh auth token
    snapshot: true

명령은 플랜 승인 후 호스트에서 실행돼요. 해석된 값은 리터럴 시크릿으로 저장되고 새로고침되지 않아요. 회전하려면 환경을 다시 만들어요. 스냅샷은 로컬 환경에서도 동작해요. 스냅샷은 refresh나 noVerify를 설정할 수 없어요. 클라우드 스냅샷은 볼트 참조에 CLI 리졸버를 사용하고 backend: sdk를 지원하지 않아요.

bindings

bindings는 각 서비스의 자격 증명 주입 도메인을 승인해요. 환경은 이 승인을 사용자의 전역 credentials.yaml에 병합해요. 각 서비스는 apiKey 블록, oauth 블록, 또는 둘 다를 포함할 수 있어요. 각 블록은 domains 목록을 포함해요:

bindings:
  github:
    apiKey:
      domains:
        - api.github.com

sbx env rm은 기본적으로 전역 바인딩을 보존해요. 환경 파일이 선언한 모든 서비스 바인딩을 제거하려면 --prune-bindings를 전달하세요.

경고 (Warning): --prune-bindings는 환경 파일에 선언된 모든 서비스의 완전한 전역 바인딩 항목을 삭제해요. 그 서비스 바인딩을 공유하는 다른 샌드박스에 영향을 줄 수 있어요.

registries

registries는 레지스트리 호스트 이름을 pull 자격 증명에 매핑해요. 각 항목은 secret이 필요하고 선택적 username을 받아요. 두 필드 다 value, ref, command 중 정확히 하나를 가진 시크릿 소스를 받아요.

username을 생략하면 sbx는 토큰 전용 자격 증명을 저장해요. GHCR과 GitLab 같은 레지스트리는 토큰 전용 자격 증명을 받아요.

registries:
  ghcr.io:
    secret:
      command: gh auth token

mcp

mcp.servers 목록은 내장 MCP 게이트웨이에 서버를 등록하고 샌드박스에 추가해요. MCP 등록은 호스트 전역이며 sbx env rm 후에도 유지돼요.

필드 (Field)	타입 (Type)	필수 (Required)	기본값 (Default)	설명 (Description)
name	string	예	없음	서버 이름
url	string	아니요	없음	원격 서버 URL, 레지스트리 참조, OCI 참조
command	string	아니요	없음	로컬 stdio 서버용 명령
args	문자열 list	아니요	없음	command에 전달되는 인자

각 서버는 url 또는 command 중 정확히 하나를 설정해야 해요.

ports

ports는 환경이 생성될 때 샌드박스 포트를 게시해요. 키트가 노출하지만 이 목록에 없는 포트는 임시(ephemeral) 호스트 포트를 받아요.

필드 (Field)	타입 (Type)	필수 (Required)	기본값 (Default)	설명 (Description)
sandbox	integer	예	없음	1~65535의 샌드박스 포트
host	integer	아니요	임시	1~65535의 호스트 포트
protocol	string	아니요	tcp4, IPv6 hostIP는 tcp6	tcp, tcp4, tcp6, udp, udp4, udp6
hostIP	string	아니요	루프백	바인딩할 호스트 인터페이스

protocol: tcp를 설정하면 IPv4와 IPv6를 모두 바인딩해요. 명시적 주소는 자신의 IP 계열만 바인딩하므로 이중 스택 바인딩에는 hostIP를 비워 두세요.

포트를 게시할 수 없으면 샌드박스 생성이 실패하고 새 샌드박스를 제거해요.

더 알아보기 (Learn more)

관련 문서와 심화 내용은 원문을 참고해 주세요.