AI 샌드박스 FAQ

AI 샌드박스 FAQ (FAQ)

Docker Sandboxes에 대해 자주 묻는 질문과 답변을 알아볼게요.

출처: 문서

본문

이 페이지의 호스트 통합과 워크스페이스 지침은 로컬 샌드박스를 설명해요. 그 워크플로를 클라우드에 적용하기 전에 Local and cloud differences 문서를 보세요.

Docker Sandboxes는 무료인가요? 상업적으로 쓸 수 있나요?

sbx CLI와 로컬 샌드박스 컴퓨팅은 상업·전문 작업을 포함해 무료로 쓸 수 있어요. 클라우드 샌드박스 컴퓨팅은 종량제 구독(pay-as-you-go)을 사용해요. 모델 제공자 요금은 샌드박스 컴퓨팅과 별개예요.

로컬 샌드박스의 조직 거버넌스는 중앙 관리 네트워크·파일시스템·MCP 정책, 로그인 강제, 감사 로그를 포함해요. 이 조직 거버넌스 기능은 별도의 유료 구독이 필요해요. 시작하려면 Docker Sales에 문의하세요.

왜 로그인이 필요한가요?

Docker Sandboxes는 당신과 당신의 에이전트가 팀이라는 생각으로 만들어졌어요. 로그인하면 각 샌드박스에 검증된 신원이 생겨서 Docker가 다음을 할 수 있어요:

샌드박스를 실존 인물에 연결해요. 에이전트가 컨테이너를 빌드하고, 패키지를 설치하고, 코드를 푸시할 수 있다면 거버넌스가 중요해져요. Docker 신원이 그 기준점이에요.
팀 기능을 켜요. 조직 거버넌스, 공유 환경, 감사 로그 같은 팀 규모 기능은 "누구"라는 개념이 필요해요. 나중에 추가하는 건 모두에게 더 나쁘기 때문이에요.
Docker 인프라에 대해 인증해요. 샌드박스는 이미지를 땡기고, 데몬을 실행하고, Docker 서비스와 통신해요. Docker 계정이 그 요청들을 인증해요.

Docker 계정 이메일은 마케팅이 아니라 인증에만 쓰여요.

조직 전체에 샌드박스 정책을 적용할 수 있나요?

네. 관리자는 네트워크·파일시스템·MCP 정책을 중앙 관리할 수 있어요. 이 통제들은 조직의 로컬 샌드박스에 적용돼요. 조직 거버넌스가 활성화되면 조직 allow 규칙만 접근을 허용해요. sbx policy로 설정한 로컬 allow 규칙은 더 이상 평가되지 않지만, 로컬 deny 규칙은 여전히 위에 적용돼요.

Organization policies 문서를 보세요. 이 기능은 별도의 유료 구독이 필요해요. 시작하려면 Docker Sales에 문의하세요.

클라우드 샌드박스는 별도의 네트워크 정책 구성을 사용해요. 클라우드 통제는 Cloud network policy 문서를 보세요.

Docker Sandboxes가 동작하려면 어떤 도메인을 허용해야 하나요?

조직이 방화벽이나 프록시로 아웃바운드 네트워크 접근을 제한한다면, 로컬 샌드박스용으로 sbx가 인증·이미지 풀·진단 보고를 할 수 있도록 다음 도메인을 허용 목록에 추가하세요. 클라우드 작업은 https://api.sandboxes-cloud.docker.com에도 연결돼요.

도메인	설명
https://login.docker.com	인증
https://hub.docker.com	Docker Hub
https://api.docker.com	Docker API
https://marlin-2.docker.com	텔레메트리
https://marlin-api.docker.com	텔레메트리
https://registry-1.docker.io	Docker pull/push
https://auth.docker.io	레지스트리 인증
https://dhi.io	Docker Hardened Images
https://sbx-diagnostics.s3.us-east-1.amazonaws.com	진단 업로드

CLI가 텔레메트리를 수집하나요?

sbx CLI는 CLI 호출에 대한 기본적인 사용 데이터를 수집해요:

어떤 명령을 실행했는지
성공했는지 실패했는지
얼마나 걸렸는지
로그인했다면 Docker 사용자 이름

CLI 사용 텔레메트리는 프롬프트나 코드를 포함하지 않아요. 클라우드 샌드박스는 Docker가 관리하는 인프라에서 실행되므로, 클라우드로 전송하는 파일은 클라우드에 저장돼요.

CLI 사용 분석을 거부하려면 SBX_NO_TELEMETRY 환경 변수를 설정하세요:

$ export SBX_NO_TELEMETRY=1

샌드박스 안에 사용자 정의 환경 변수를 어떻게 설정하나요?

sbx 0.39.0 버전부터 sbx run과 sbx create에서 -e/--env 또는 --env-file을 쓸 수 있어요. 문법, 우선순위 규칙, 기존 샌드박스의 지속 설정, 자격 증명 안내는 환경 변수 설정 문서를 보세요.

/etc/sandbox-persistent.sh의 변수는 sbx run으로 시작한 대화형 세션과 에이전트에서 쓸 수 있어요. 변수는 추가된 후 시작된 세션과 에이전트에만 적용돼요. 실행 중인 에이전트를 재시작하거나 샌드박스를 중지·시작하면 새 값을 반영해요.

에이전트가 왜 승인 프롬프트 없이 실행되나요?

샌드박스 자체가 안전 경계(safety boundary)예요. 에이전트가 네트워크 정책, 자격 증명 격리, 그리고 명시적으로 공유한 경로 밖의 호스트 시스템 접근이 없는 격리된 microVM 안에서 실행되므로, 승인 프롬프트의 일반적인 이유(파괴적 명령 방지, 네트워크 접근, 파일 변경)는 샌드박스 격리 계층이 대신 처리해요.

승인 프롬프트를 다시 켜고 싶다면 세션 안의 권한 모드를 바꾸세요. 대부분의 에이전트는 시작 후 권한 모드를 바꿀 수 있어요. Claude Code에서는 /permissions 명령으로 대화형으로 모드를 바꿔요.

모든 세션의 기본값으로 승인 프롬프트를 만들려면, 내장 에이전트를 확장하고 시작 옵션을 바꾸는 v2 샌드박스 키트를 만드세요. 완전한 예시는 Fork an existing agent 문서를 보세요.

전부 v3 키트로 만든 환경이라면 워크로드 Dockerfile에서 실행 명령을 설정하세요. Build a v3 agent kit 문서를 보세요.

에이전트가 샌드박스 안에서 실행 중인지 어떻게 알 수 있나요?

에이전트에게 물어보세요. 에이전트는 자신이 샌드박스 안에서 실행 중인지 볼 수 있어요. Claude Code에서는 진행 중인 작업을 방해하지 않고 물어보는 /btw 슬래시 명령을 쓰세요:

/btw are you running in a sandbox?

샌드박스가 왜 내 사용자 수준 에이전트 구성을 사용하지 않나요?

로컬 샌드박스는 사용자 수준 에이전트 구성을 전부 가져오지 않아요. ~/.claude 같은 디렉터리 아래의 hooks, 설정, 기타 파일은 호스트에 남아요. 작업 디렉터리의 프로젝트 수준 구성은 샌드박스 안에서 계속 쓸 수 있어요.

공유 에이전트 스킬은 예외예요. sbx skills add로 Git 저장소에서 스킬을 설치하거나, sbx skills import로 지원되는 호스트 디렉터리에서 스킬을 복사하세요. sbx는 스킬을 샌드박스와 공유하는 지속 저장소에 보관해요. 저장소 관리, 지원되는 호스트 디렉터리, 마운트 동작, 샌드박스별 거부는 Share agent skills 문서를 보세요.

프로젝트별 스킬과 그 밖의 에이전트 구성을 프로젝트 자체에 두세요. 그러면 구성이 코드와 함께 버전 관리돼요. 호스트 경로에 심볼릭 링크를 쓰지 마세요. 샌드박스 안의 에이전트는 샌드박스 밖으로 심볼릭 링크를 따라갈 수 없어요.

에이전트에 이미지를 붙여넣을 수 있나요?

로컬 샌드박스에서 이미지 붙여넣기는 기본적으로 꺼져 있어요. 텍스트 붙여넣기는 터미널이 직접 보내므로 동작해요. Ctrl+V로 이미지나 스크린샷을 붙여넣는 건 달라요. 에이전트가 호스트 클립보드에서 읽는데, 샌드박스는 선택하지 않는 한 그 접근을 차단해요.

clipboard.imagePaste를 켜세요:

$ sbx settings set clipboard.imagePaste true

그러면 Ctrl+V가 클립보드를 읽는 에이전트(Claude Code, Codex 포함)에 호스트 이미지를 붙여넣어요. 이 설정은 실행 중인 샌드박스에도 몇 초 안에 적용돼요.

이 기능은 샌드박스의 격리를 완화하므로 선택(opt-in)이에요. 켜면 샌드박스 안의 프로세스가 호스트 쪽 프록시를 통해 호스트 클립보드를 읽을 수 있어요. 노출 범위는 좁아요. 붙여넣을 때만 읽고, 이미지 데이터(image/png)만 반환하며, 클립보드 내용은 캐시되거나 기록되지 않아요. 하지만 여전히 호스트 데이터가 샌드박스로 들어가는 것이므로 켜기 전까지는 꺼져 있어요.

다시 끄려면:

$ sbx settings set clipboard.imagePaste false

헤드리스 Linux에서 Docker Sandboxes를 쓸 수 있나요?

네. Linux의 로컬 샌드박스에서 sbx는 GNOME Keyring이나 KDE Wallet 같은 데스크톱 키링이 노출하는 Secret Service에 비밀을 저장해요. 헤드리스 서버와 일부 WSL 설정에는 실행 중인 Secret Service가 없으므로, sbx는 $XDG_CONFIG_HOME/com.docker.sandboxes 아래의 파일로 폴백해요. $XDG_CONFIG_HOME이 설정되지 않으면 기본값은 ~/.config/com.docker.sandboxes예요. 설정이 필요 없어요. 그런 호스트에 비밀을 저장하면 sbx가 알림을 출력해요:

No keychain detected - this secret will be stored on disk, protected by file permissions rather than a password

sbx는 0700 권한의 디렉터리에 파일을 저장해요. 이는 ~/.docker/config.json에 쓰는 것과 같은 파일 권한 모델이에요. 파일을 읽을 수 있는 어떤 사용자나 프로세스든 저장된 자격 증명을 가져올 수 있으므로, 그 디렉터리를 민감하게 취급하세요. 가능하면 애플리케이션별로 접근을 중재하는 키체인을 선호하세요.

대신 비밀을 키링에 보관하려면, 저장하기 전에 호스트에서 Secret Service를 실행하세요. gnome-keyring을 설치하고 dbus-run-session을 시작하거나, 로그인 세션에서 잠금 해제되는 키링 데몬을 실행하세요. 동작하는 Secret Service가 있으면 sbx는 새 비밀을 다시 키체인에 저장해요. 플랫폼별 비밀 저장 위치는 Where secrets are stored 문서를 보세요.

더 알아보기 (Learn more)

Local and cloud differences, Organization policies, Cloud network policy, Set environment variables, Fork an existing agent, Build a v3 agent kit, Share agent skills, Where secrets are stored 문서를 참고하세요.