Docker Sandboxes 설정

Docker Sandboxes 설정

sbx settings로 호스트의 Docker Sandboxes를 구성해요. 클립보드 접근, 키트 소스, 샌드박스 생성 기본값을 포함해요. 설정은 로컬 샌드박스 전반에 적용돼요. 프로젝트별 구성에는 환경 파일을 사용해요. 명령은 로컬 데몬을 통해 설정을 읽고 써요(필요하면 시작). 오버라이드는 CLI 호출과 데몬 재시작 사이에 유지돼요.

출처: 문서

본문

설정 보기 (View settings)

효과 값, 유형, 소스, 설명과 함께 설정을 나열해요.

$ sbx settings list

긴 값과 설명은 표에서 잘려요. 전체 텍스트는 sbx settings list --no-trunc를, JSON 출력은 sbx settings list --json을 사용해요. JSON 레코드에는 가능한 곳에 기본값과 환경 변수 이름도 포함돼요.

하나의 설정을 검사하려면:

$ sbx settings get clipboard.imagePaste
false
$ sbx settings get clipboard.imagePaste --json

--json 없이 get은 효과 값만 출력해요. --json이 있으면 소스와 기본값을 포함한 전체 설정 레코드를 출력해요.

설정 변경하기 (Change a setting)

설정 키와 요구되는 유형의 값을 전달해 오버라이드를 설정해요. 예를 들어 샌드박스 에이전트가 호스트 클립보드의 이미지를 읽게 하려면:

$ sbx settings set clipboard.imagePaste true

JSON 값은 쉘이 그대로 전달하도록 인자를 따옴표로 감싸요. 이 예시는 Docker Hub와 조직의 GitHub 리포지토리의 키트를 허용해요.

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

JSON 배열·객체는 전체 값을 대체해요. 유지할 항목을 모두 포함하세요. 오버라이드를 제거하려면 unset을 사용해요.

$ sbx settings unset clipboard.imagePaste

설정이 환경 변수로 폴백하거나(설정된 경우) 기본값으로 폴백돼요. 내장 기본값과 같은 값을 설정해도 저장된 오버라이드가 제거돼요.

값 우선순위 (Value precedence)

각 설정에 대해 첫 번째로 가능한 값이 우선해요.

  1. 설정의 환경 변수(있다면)
  2. sbx settings set으로 쓴 사용자 오버라이드
  3. 내장 기본값

sbx settings list의 SOURCE 열이 선택된 소스를 envvar, override, default로 식별해요. 환경 변수가 우선하면 set은 여전히 저장된 오버라이드를 업데이트하고 효과 값이 왜 바뀌지 않았는지 보고해요. unset은 저장된 오버라이드만 제거하고 환경 변수는 제거하지 않아요.

변경이 적용되는 시점

대부분의 변경은 약 5초 안에 적용돼요. RESTART 열에 yes로 표시된 설정은 기존 데몬 측 소비자에 데몬 재시작이 필요해요.

$ sbx daemon restart

set과 unset 명령은 필요할 때 재시작 알림을 출력해요. 일부 설정은 샌드박스를 만들 때만 적용돼요. 템플릿 기본값이나 디스크 크기를 바꿔도 기존 샌드박스는 업데이트되지 않아요. 프록시 설정은 CLI 요청, 데몬 트래픽, 샌드박스 트래픽에 별도 타이밍이 있어요.

환경 변수 (Environment variables)

일부 설정에는 아래 레퍼런스 항목에 나열된 환경 변수 대응이 있어요. 이 변수들은 호스트의 Docker Sandboxes를 구성해요. 샌드박스 안의 환경 변수를 설정하지는 않아요. 데몬은 시작할 때 환경 변수를 상속해요. 첫 sbx 명령 전에 변수를 내보내거나, 설정된 셸에서 기존 데몬을 재시작해요. 예:

$ export DOCKER_SANDBOXES_CLIPBOARD_IMAGE_PASTE=true
$ sbx daemon restart
$ sbx settings get clipboard.imagePaste
true

셸 환경을 바꿔도 실행 중인 데몬의 환경은 바뀌지 않아요(재시작 없이 적용되는 설정조차). 저장된 오버라이드나 기본값으로 돌아가려면 변수를 제거하고 재시작해요.

$ unset DOCKER_SANDBOXES_CLIPBOARD_IMAGE_PASTE
$ sbx daemon restart

설정을 로컬로 읽는 CLI 연산은 매 호출마다 자신의 환경을 사용해요. 이런 변수를 쓸 때 CLI와 데몬 환경을 일관되게 유지해요. sbx settings set의 영속적 오버라이드는 각 셸에서 변수를 내보낼 필요를 없애줘요.

설정 레퍼런스 (Settings reference)

각 항목은 오버라이드 전의 내장 기본값을 나열해요. 직접 대응이 있는 경우에만 환경 변수가 나타나요. 설치된 버전이 지원하는 값을 검사하려면 sbx settings list를 사용해요.

에이전트와 호스트 접근

  • clipboard.imagePaste — boolean, 기본 false, 환경 변수 DOCKER_SANDBOXES_CLIPBOARD_IMAGE_PASTE. 켜면 스크린샷과 다른 호스트 클립보드 이미지를 Claude Code, Codex 같은 에이전트에 Ctrl+V로 붙여넣을 수 있어요. 텍스트 붙여넣기는 이 설정이 필요 없어요. 실행 중인 샌드박스에 재생성 없이 적용돼요. false로 설정하면 그 접근을 철회해요.
  • claude.remoteControl — boolean, 기본 false, 환경 변수 DOCKER_SANDBOXES_CLAUDE_REMOTE_CONTROL. 샌드박스 안에서 Claude Code의 /remote-control 명령을 사용하기 전에 켜요. 실행 중인 샌드박스의 요청에 적용돼요.
  • env.rememberHostCommands — boolean, 기본 false. 신뢰하는 환경 파일을 반복 실행하면서 호스트 명령을 한 번, 그 명령이 바뀔 때까지 승인하고 싶을 때 사용.
  • ssh.agentForwardingEnabled — boolean, 기본 true. 샌드박스가 호스트 SSH 에이전트에 서명을 요청하지 못하게 하려면 false로 설정. 데몬 재시작으로 기존 포워더에 적용.
  • ssh.agentSocketPath — string, 기본 빈 문자열. 모든 샌드박스가 같은 호스트 SSH 에이전트를 쓰게 하려면 고정 경로를 사용.

이미지와 저장소

  • platform.images.registryMirror — string, 기본 빈 문자열. 조직이 Docker Hub pull을 레지스트리 미러로 라우팅할 때 사용. 호스트를 URL 스킴 없이, 선택적으로 포트와 경로 접두사를 붙여 지정.
  • platform.images.useDHI — boolean, 기본 false, 환경 변수 DOCKER_SANDBOXES_USE_DHI. 기본 에이전트 템플릿으로 샌드박스를 만들 때 Docker Hardened Image 변형을 사용.
  • sandbox.disk.dockerVolume — string, 기본 10g. /var/lib/docker 아래 Docker 이미지·컨테이너·볼륨을 위한 공간이 더 필요할 때 이 기본값을 늘려요. 최소는 512 MiB.

키트

  • kit.allowedSources — JSON, 기본 ["docker.io/"], 환경 변수 DOCKER_SANDBOXES_KIT_ALLOWED_SOURCES. 원격 레지스트리나 Git 저장소에서 키트를 설치하기 전에 게시자를 여기에 추가. 값이 전체 허용 목록을 대체하므로 유지할 소스를 모두 포함.
  • kit.allowLocalKits — boolean, 기본 true, 환경 변수 DOCKER_SANDBOXES_KIT_ALLOW_LOCAL. 키트가 로컬 디렉터리나 ZIP 대신 원격 소스에서 와야 하게 하려면 false로 설정.
  • kit.allowExtractedAgents — boolean, 기본 true. 이전에 Docker Sandboxes에 포함된 일부 에이전트가 키트로 배포돼요. 기본적으로 Docker Sandboxes는 그 에이전트에 사용하는 정확한 고정 참조를 kit.allowedSources에 없어도 허용하고 kit.requireSignature에서 면제해요. 그 키트에도 소스·서명 요구사항을 적용하려면 false로 설정.
  • kit.requireSignature — boolean, 기본 false, 환경 변수 DOCKER_SANDBOXES_KIT_REQUIRE_SIGNATURE. 서명되지 않은 키트와 신뢰하는 서명자와 일치하지 않는 키트를 거부하려면 켜요. 먼저 kit.trustedSigners를 구성한 뒤 서명을 요구.
  • kit.trustedSigners — JSON, 기본 Docker 직원 신원. 키트 서명을 신뢰하는 신원 또는 공개 키 설정.
  • kit.ignoreTransparencyLog — boolean, 기본 false, 환경 변수 DOCKER_SANDBOXES_KIT_IGNORE_TLOG. --tlog-upload=false로 만든 프라이빗 키트의 경우 공개 Rekor 투명성 로그 항목을 요구하지 않게 하려면 사용.

MCP 게이트웨이

  • mcp.forceLocalGateway — boolean, 기본 false. 계정이 SaaS 게이트웨이를 사용할 때 로컬 MCP 게이트웨이를 쓰려면 true로 설정.

진단

  • diagnostics.autoUpload — string, 기본 빈 문자열. 데몬 오류 후 진단 번들을 자동 업로드할지 선택: yes(동의), no(거절·추가 프롬프트 억제), 빈 문자열(기록된 결정 없음).
  • diagnostics.autoUploadErrorCooldownInDays — integer, 기본 1. 자동 진단 번들 업로드를 덜 자주 하려면 늘려요. diagnostics.autoUpload가 yes여야 해요.

업스트림 프록시와 TLS

  • proxy — string, 기본 빈 문자열. 샌드박스 트래픽과 호스트 측 Docker Sandboxes 트래픽이 모두 통과해야 할 공유 업스트림 프록시를 설정.
  • proxy.sandbox — string, 기본 빈 문자열, 환경 변수 DOCKER_SANDBOXES_PROXY. 샌드박스 안의 트래픽이 데몬·CLI와 다른 경로가 필요할 때 사용.
  • proxy.daemon — string, 기본 빈 문자열. 이미지 pull 같은 데몬 요청을 샌드박스 트래픽과 별도로 라우팅.
  • no_proxy — string, 기본 빈 문자열. 선택된 업스트림 프록시를 우회할 대상 목록. 쉼표 구분 호스트, 도메인 접미사, IP 주소, CIDR 범위. *는 모든 대상에 대해 업스트림 프록시 우회.
  • no_proxy.sandbox — string, 기본 빈 문자열, 환경 변수 DOCKER_SANDBOXES_NO_PROXY. 일부 대상에 대해 샌드박스 트래픽만 우회.
  • no_proxy.daemon — string, 기본 빈 문자열. 데몬·지원되는 CLI 요청에 샌드박스 트래픽과 다른 프록시 제외가 필요할 때.
  • proxy.integratedAuth — boolean, 기본 false. 회사 프록시가 Windows 로그인 신원으로 NTLM이나 Kerberos 인증을 요구할 때 켜요. 호스트에서 발생하므로 Windows 자격 증명이 샌드박스에 들어가지 않아요. macOS·Linux에선 효과 없음.
  • tls.allowNegativeSerial — boolean, 기본 false, 환경 변수 DOCKER_SANDBOXES_TLS_ALLOW_NEGATIVE_SERIAL. TLS 검사 프록시가 음수 일련 번호의 인증서를 발급해 x509: negative serial number 오류가 날 때 호환성 설정으로 사용.

공유 에이전트 스킬

  • skills.defaultMode — string, 기본 readonly. --skills를 생략할 때 향후 샌드박스가 공유 에이전트 스킬 저장소를 사용하는 방식을 선택: readonly(읽기만), readwrite(읽기·수정), off(마운트 안 함).

명령 레퍼런스 (Command reference)

  • sbx settings list — 설정 나열. 별칭: sbx settings ls. --json 완전한 레코드 또는 --no-trunc 전체 텍스트. 상호 배타적.
  • sbx settings get <KEY> — 하나의 효과 값 출력. --json 완전한 설정 레코드.
  • sbx settings set <KEY> <VALUE> — 사용자 오버라이드 작성. 값은 설정 유형에 따라 bool, int, float, string, json으로 구문 분석.
  • sbx settings unset <KEY> — 사용자 오버라이드 제거.

도움말은 sbx settings <COMMAND> --help를 사용해요.

더 알아보기 (Learn more)