Docker Sandboxes 설정

Docker Sandboxes 설정 (Docker Sandboxes settings)

sbx settings가 머신에서 sbx가 실행되는 방식을 어떻게 제어하는지 설정 참조로 정리해 드릴게요.

출처: 문서

본문

참고 (Note): sbx settings의 범위는 예고 없이 바뀔 수 있어요. 이 페이지는 우리가 검증한 값들을 문서화해요. 여기에 보이는 일부 설정은 아직 실험적이며 바뀔 수도 있어요.

설정은 sbx가 머신에서 실행되는 방식을 제어해요. 데몬, CLI, 샌드박스를 구성해요. 각 설정은 범위(daemon, cli, sandbox)를 가지며 즉시, 다음 명령 때, 또는 데몬 재시작 후에 적용돼요.

명령 (Commands)

값을 설정·조회·나열·해제해요:

$ sbx settings set <key> <value>
$ sbx settings get <key>
$ sbx settings ls
$ sbx settings unset <key>

설정 참조 (Settings reference)

아래 표들은 sbx settings 값을 문서화해요. 각 설정은 범위(daemon, cli, sandbox)를 가져요. "Takes effect"의 빈 칸은 기본값이 즉시/다음 명령임을 뜻해요. "Restart daemon" 칸은 데몬을 재시작해야 변경이 적용됨을 뜻해요.

핵심 (Core)

설정 (Setting)	범위 (Scope)	설명 (Description)
`agent.default`	sandbox	아무것도 지정하지 않을 때 쓰는 기본 에이전트. 예: `claude`
`agent.registry`	sandbox	인증된 에이전트용 개인 레지스트리
`agent.registry.enableSCM`	sandbox	활성화 시 SCM 워크플로로 촉발되는 컨테이너 이미지 push·pull

값 (Values)

설정 (Setting)	범위 (Scope)	설명 (Description)	적용 시점 (Takes effect)
`values.platform.version`	daemon	데몬이 사용하는 플랫폼 값의 버전	Restart daemon
`values.daemon.auth.warnUpgrade`	daemon	로그인 전에 `sbx` CLI 업그레이드 경고	Restart daemon
`values.daemon.auth.quota`	daemon	Docker Sandboxes 기능의 할당량과 사용량	Restart daemon
`values.daemon.auth.organization`	daemon	샌드박스 데몬에 대한 요청에 쓰이는 서명된 클레임 "organization"	Restart daemon
`values.cli.features`	cli	서버의 `sbx` 기능 플래그, CLI가 사용	Next command
`values.cli.providers`	cli	서버의 모델 제공 업체 정의, CLI가 사용	Next command
`values.api.publicKey`	daemon	로그인 서비스용 공개 키 정체성	Restart daemon
`values.api.publicKeyType`	daemon	공개 키 정체성의 타입	Restart daemon
`values.api.bearer.token`	daemon	키 캐시와 API용 앱 수준 bearer 토큰. 값은 로그인 시 설정되므로 수동으로 설정하지 마세요	Restart daemon

보안 (Security)

설정 (Setting)	범위 (Scope)	설명 (Description)	적용 시점 (Takes effect)
`security.policy`	sandbox	네트워크 정책의 최대 우선순위 설정
`security.rootless`	sandbox	샌드박스 생성에 rootless 인프라 요구	Restart daemon
`security.daemon.socket.access`	sandbox	데몬 소켓 접근 제한: `readonly` 또는 `readwrite`
`security.daemon.socket.access.allowlist`	sandbox	데몬 소켓 접근 허용 목록의 호스트 경로 허용 목록

`sbx` CLI

설정 (Setting)	범위 (Scope)	설명 (Description)	적용 시점 (Takes effect)
`cli.color`	cli	CLI 출력에 색을 입힐지 설정
`cli.debug`	cli	CLI에 디버그 로깅 활성화

샌드박스 네트워킹 (Sandbox networking)

설정 (Setting)	범위 (Scope)	설명 (Description)	적용 시점 (Takes effect)
`network.mirror`	daemon	샌드박스 네트워크용 네트워크 미러 이그레스 프록시 네임스페이스	Restart daemon
`network.mirror.dns`	daemon	샌드박스 네트워크용 네트워크 미러 DNS	Restart daemon
`network.mirror.interface`	daemon	네트워크 미러에 연결된 호스트의 인터페이스	Restart daemon
`network.mirror.ip`	daemon	네트워크 미러 IP	Restart daemon
`network.mirror.gateway`	daemon	네트워크 미러 게이트웨이	Restart daemon
`network.dns.bootstrap`	daemon	샌드박스 네트워크용 부트스트랩 DNS	Restart daemon
`network.dns`	daemon	샌드박스 네트워크용 기본 DNS	Restart daemon
`network.dns.search...`	daemon	샌드박스 네트워크용 검색 도메인	Restart daemon
`network.dnsPort`	daemon	샌드박스 네트워크용 DNS 포트	Restart daemon
`network.enableIPv6`	daemon	샌드박스에서 IPv6 네트워킹 활성화	Restart daemon
`network.proxy`	daemon	샌드박스 네트워크의 호스트 프록시	Restart daemon
`network.proxy.httpsPort`	daemon	샌드박스 네트워크에서 호스트 프록시가 쓰는 HTTPS 포트	Restart daemon
`network.proxy.httpPort`	daemon	샌드박스 네트워크에서 호스트 프록시가 쓰는 HTTP 포트	Restart daemon
`network.proxy.socksPort`	daemon	샌드박스 네트워크에서 호스트 프록시가 쓰는 SOCKS 포트	Restart daemon
`network.proxy.scope`	daemon	샌드박스 네트워크 프록시 범위: `local` 또는 `remote`	Restart daemon
`network.proxy.disableSandboxAuth`	daemon	True면 HTTP 프록시에 대한 식별 요구를 해제	Restart daemon
`network.proxy.disableNativeTokenAuth`	daemon	true면 프록시가 proxy-managed 토큰 변수를 갱신하지 않음	Restart daemon
`network.proxy.hostAccessList`	daemon	호스트 프록시를 통해 접근 가능한 호스트 목록	Restart daemon
`network.mirror.hostAccessList`	daemon	네트워크 미러를 통해 접근 가능한 호스트 목록	Restart daemon

샌드박스 (Sandbox)

설정 (Setting)	범위 (Scope)	설명 (Description)
`sandbox.name`	sandbox	샌드박스 이름
`sandbox.profile`	sandbox	만들어지거나 갱신되는 샌드박스의 프로필
`sandbox.template`	sandbox	샌드박스의 템플릿 이미지 이름
`sandbox.cpus`	sandbox	샌드박스의 CPU 수
`sandbox.memory`	sandbox	샌드박스의 메모리 한도
`sandbox.arch`	sandbox	샌드박스의 아키텍처
`sandbox.workspace`	sandbox	샌드박스의 워크스페이스
`sandbox.workspace.clone`	sandbox	clone mode 활성화
`sandbox.workspace.clone.fetchArgs`	sandbox	clone fetch용 인자
`sandbox.workspace.clone.fetchRefSpec`	sandbox	clone fetch용 refspec
`sandbox.vm.label`	sandbox	샌드박스용 VM 라벨 지정
`sandbox.container.label`	sandbox	샌드박스용 컨테이너 라벨
`sandbox.volumes`	sandbox	샌드박스용 볼륨
`sandbox.secrets.configHash`	sandbox	시크릿 프로비저닝용 구성 해시
`sandbox.timeout.action`	sandbox	샌드박스가 타임아웃될 때 취할 타임아웃 동작
`sandbox.timeout.ttl`	sandbox	샌드박스의 수명(time-to-live)
`sandbox.hook.*`	sandbox	사전·사후 액션 훅

플랫폼과 환경 (Platform and environment)

설정 (Setting)	범위 (Scope)	설명 (Description)	적용 시점 (Takes effect)
`platform.images.registryMirror`	sandbox	(로컬 전용) 템플릿과 키트용 레지스트리 미러
`platform.images.cacheDir`	daemon	이미지 캐시 디렉터리	Restart daemon
`platform.images.cacheDir.enabled`	daemon	이미지 캐시 디렉터리에서 이미지 캐싱 활성화	Restart daemon
`platform.name`	daemon	플랫폼 이름	Restart daemon
`platform.profiles.verbose`	daemon	프로필을 verbose로 설정 가능	Restart daemon
`platform.allowExperimentalFeatures`	daemon	CLI가 실험 기능을 쓰게 허용	Restart daemon
`platform.arch`	daemon	플랫폼 아키텍처	Restart daemon
`platform.virtiofsCache`	daemon	virtiofs 캐싱 활성화/비활성화. macOS 읽기에 영향을 줄 수 있음	Restart daemon
`feature.sandbox-gpu`	daemon	GPU 패스스루 기능 활성화	Restart daemon
`feature.model`	daemon	모델 선택 기능 활성화	Restart daemon
`feature.sandbox-*`	daemon	다른 실험 기능	Restart daemon

인증과 계정 (Authentication and account)

설정 (Setting)	설명 (Description)	적용 시점 (Takes effect)
`auth.enabled`	인증 활성화	Next command
`auth.oidc.issuer_url`	OIDC 흐름의 발급자 URL
`auth.oidc.issuer_document`	OIDC 흐름의 발급자 문서(JSON)
`auth.oidc.client_id`	OIDC 흐름의 클라이언트 ID
`auth.oidc.client_secret`	OIDC 흐름의 클라이언트 시크릿
`auth.oidc.api_base`	애플리케이션의 API 기본 URL
`auth.oidc.api_key_tokens_url`	API 키 토큰 URL
`auth.oidc.api_key_tokens_issues_url`	API 키 토큰 이슈 URL
`auth.oidc.api_key_tokens_refresh_uri`	API 키 토큰 재발급 URI
`auth.oidc.api_key_tokens_revoke_uri`	API 키 토큰 폐기 URI
`auth.oidc.auth_request_uri`	인증 요청 URI
`auth.oidc.auth_callback_uri`	인증 콜백 URI
`auth.oidc.logout_uri`	로그아웃 URI
`auth.oidc.end_session_uri`	세션 종료 URI
`auth.oidc.token_audience`	OIDC 흐름의 토큰 오디언스
`auth.oidc.token_request_url`	토큰 요청 URL
`auth.oidc.token_grant_type`	토큰 요청의 grant type
`auth.oidc.token_scope`	토큰 요청의 scope
`auth.oidc.refresh_grant_type`	재발급 요청의 grant type
`auth.oidc.refresh_scope`	재발급 요청의 scope
`auth.oidc.refresh_token_field`	재발급 토큰의 필드 이름
`auth.oidc.access_token_field`	접근 토큰의 필드 이름
`auth.oidc.id_token_field`	ID 토큰의 필드 이름
`auth.oidc.audience_field`	오디언스 필드 이름
`auth.oidc.tokens_issued_url`	토큰이 발급되는 URL

기타 설정 (Other settings)

설정 (Setting)	범위 (Scope)	설명 (Description)	적용 시점 (Takes effect)
`ssh.agentSocketPath`	daemon	사용할 SSH 에이전트 소켓 경로	Restart daemon
`ssh.agentForwardingEnabled`	daemon	SSH 에이전트 전달 활성화	Restart daemon
`ssh.daemon.socket`	daemon	SSH 데몬 소켓	Restart daemon
`ssh.remote.authentication`	daemon	원격 SSH 인증 설정	Restart daemon
`ssh.remote.authMethod`	daemon	CLI + 데몬의 SSH-through-proxy 설정	Restart daemon
`env.rememberHostCommands`	cli	승인된 호스트 명령을 기억할지 여부
`git.config.*`	cli	Git 기본값과 파일 구성
`kit.allowedSources`	sandbox	키트를 설치할 수 있는 소스 목록 제어
`kit.mixedSources`	cli	단일 키트에 여러 아카이브 형식을 쓸 수 있는지 결정
`kit.eagerInstall`	sandbox	true면 키트가 생성 후 즉시 탐욕적으로 설치됨
`kit.installTimeout`	sandbox	키트 설치 타임아웃
`settings.defaults`	daemon	설정 기본값 설정	Restart daemon
`settings.path`	daemon	설정 파일 경로	Restart daemon
`proxy`	daemon	사용할 프록시	Restart daemon
`proxy.sandbox`	daemon	샌드박스 트래픽용 프록시	Restart daemon
`proxy.daemon`	daemon	데몬 트래픽용 프록시	Restart daemon
`no_proxy`	daemon	프록시를 우회하는 호스트 목록	Restart daemon
`no_proxy.sandbox`	daemon	샌드박스 프록시를 우회하는 호스트 목록	Restart daemon
`no_proxy.daemon`	daemon	데몬 프록시를 우회하는 호스트 목록	Restart daemon
`proxy.integratedAuth`	daemon	프록시 통합 인증 활성화	Restart daemon

더 알아보기 (Learn more)

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