샌드박스 환경 선택
샌드박스 환경 선택
Claude Code 샌드박스 옵션(내장 샌드박스 Bash 도구, 샌드박스 런타임, dev 컨테이너, Docker, VM)을 비교해 위협 모델에 맞는 격리 수준을 고르는 방법을 다루는 페이지입니다. 격리는 세션이 읽고·쓰고·네트워크로 닿을 수 있는 것을 제한하며, 권한 프롬프트를 줄여 자동 실행하거나 완전히 신뢰하지 않는 코드를 대상으로 할 때 특히 중요합니다. 가벼운 명령 단위 샌드박스부터 완전 분리 VM까지 여러 수준이 있습니다.
출처: 공식문서
본문
샌드박싱 접근 비교
표에서 처음 두 접근은 호스트 OS에서 컨테이너 없이 실행되고, 나머지는 컨테이너·VM 안에 둡니다.
| 접근 | 격리되는 것 | Docker 필요 | 설정 노력 |
|---|---|---|---|
| 샌드박스 Bash 도구 | Bash 명령과 자식 프로세스 | 아니오 | macOS 최소, Linux·WSL2 낮음 |
| 샌드박스 런타임 | 전체 Claude Code 프로세스(파일 도구·MCP·훅 포함) | 아니오 | 낮음 |
| Dev 컨테이너 | 전체 개발 환경 | 예 | 중간 |
| 커스텀 컨테이너 | 전체 개발 환경 | 예 | 중간~높음 |
| 가상 머신 | 전체 OS | 아니오 | 높음 |
| 웹의 Claude Code | 전체 OS(Anthropic 호스팅) | 아니오 | 없음; Claude 구독 필요 |
샌드박스 Bash 도구는 Claude Code에 내장돼 Bash 명령만 제한합니다. 내장 파일 도구·MCP·훅은 여전히 호스트에서 직접 실행됩니다. 나머지는 전체 Claude Code 프로세스를 격리 경계 안에 두므로 파일 도구·MCP·훅도 제한됩니다.
⚠️ 샌드박스 격리는 침해 영향은 줄이지만 리스크를 없애진 않습니다. 네트워크 이그레스를 허용하는 접근은 에이전트가 읽는 데이터를 누출할 수 있고, 프로젝트 디렉터리를 쓰기 가능으로 마운트하면 그 코드를 수정할 수 있습니다. 또한 격리는 모델에 보내는 것을 바꾸지 않습니다 — 프롬프트·읽은 파일은 샌드박스 유무와 무관하게 전송됩니다.
접근 선택
| 원하는 것 | 시작 |
|---|---|
| 자신의 머신에서 일상 작업 권한 프롬프트 줄이기 | 샌드박스 Bash 도구 (/sandbox) |
--dangerously-skip-permissions·auto 모드로 무인 작업 |
사전 구성된 dev 컨테이너·컨테이너·VM·샌드박스 런타임 |
| Docker 없이 Bash 외 MCP·훅까지 격리 | 샌드박스 런타임 |
| 신뢰할 수 없는 저장소 작업 | 전용 VM, 또는 Claude 구독 시 웹의 Claude Code |
| 팀 전체에 샌드박스 환경 표준화 | 저장소에 복사한 사전 구성 dev 컨테이너 |
| 로컬 셋업 없는 기기에서 사용 | 웹의 Claude Code |
| 조직 모든 개발자에게 격리 강제 | 조직 전체 격리 강제 |
| 네이티브 Windows 호스트에서 작업 | 컨테이너·VM, 또는 WSL2 안에서 Bash 샌드박스 |
격리와 권한 모드의 관계
권한 모드는 도구 호출이 실행되는지·프롬프트가 먼저 뜨는지를 정하고, 격리는 일단 실행된 명령이 닿을 수 있는 것을 제한합니다. --dangerously-skip-permissions를 넘기면 Claude가 묻지 않고 행동하므로, 선택한 격리 경계가 시스템을 지키는 유일한 수단입니다 — 항상 컨테이너·VM·샌드박스 런타임 안에서 실행해 파일 도구·MCP·훅도 경계 안에 두세요. Linux·macOS에서 루트로 이 플래그를 실행하면 시작이 거부되므로 비루트로 실행하세요. auto 모드는 프롬프트를 검토하는 분류기로 대체합니다 — 분류기는 액션 단위 통제이지 격리 경계가 아니라, 무인 실행에 방어 심층으로 격리가 여전히 유용합니다. 샌드박스 Bash 도구만으로는 Bash만 제한하므로 완전 무인 실행엔 충분하지 않습니다 — 컨테이너·VM 안에서 층을 겹치는 게 좋습니다.
샌드박스 Bash 도구
네이티브 Windows는 미지원. Windows 호스트에선 WSL2 또는 컨테이너·VM을 쓰세요.
Claude Code에 내장된 도구로, OS 프리미티브로 Claude가 실행하는 모든 Bash 명령의 파일시스템·네트워크 접근을 제한합니다. /sandbox 명령으로 패널을 열고 모드를 고릅니다. 명령 단위 샌드박스는 세션에서 실행되는 모든 것을 덮진 않습니다 — Read·Edit·WebFetch 같은 다른 내장 도구는 프로세스 안에서 실행되고, MCP·명령 훅은 제약 없는 별도 프로세스입니다. 내장 도구·MCP·훅을 모두 한 OS 경계 뒤에 두려면 샌드박스 런타임·dev 컨테이너·커스텀 컨테이너 안에서 전체 프로세스를 실행하세요.
샌드박스 런타임
@anthropic-ai/sandbox-runtime 패키지는 내장 Bash 샌드박스와 같은 Seatbelt·bubblewrap 격리로 전체 프로세스를 감쌉니다. 이를 통해 세션의 모든 도구·훅·MCP 서버를 제한합니다(베타 연구 프리뷰, 구성 형식이 바뀔 수 있음).
Linux·WSL2에서 런타임은 내장 샌드박스와 같은 bubblewrap·socat + ripgrep에 의존합니다. macOS는 추가 패키지 불필요. 기본적으로 네트워크 접근을 거부하고 내장 런타임 경로로만 쓰기를 제한하므로, 구성은 ~/.srt-settings.json(또는 --settings)에 두고 최소한 다음을 허용하세요:
- 프로젝트 디렉터리
~/.claude·~/.claude.json(Claude Code 구성 경로)/tmp(런타임 파일)
네트워크 도메인은 api.anthropic.com(또는 구성한 공급자 엔드포인트, WebFetch 도메인 안전 검사가 api.anthropic.com을 계속 호출하므로 타사 공급자에서도 유지), OAuth 로그인·토큰 갱신에 필요한 claude.ai·platform.claude.com.
Linux·WSL2에서 쓰기 허가는 이미 존재하는 경로에만 적용됩니다. 새 환경에선 먼저:
mkdir -p ~/.claude && echo '{}' > ~/.claude.json
설정 파일을 둔 뒤 실행:
npx @anthropic-ai/sandbox-runtime claude
런타임은 스스로 고위험 쓰기를 차단합니다: denyWrite가 allowWrite보다 우선하고, 프로젝트 루트에서 .git/hooks, .git/config(filesystem.allowGitConfig: true 아니면), .mcp.json, .claude/commands, .claude/agents, 셸 시작 파일을 거부합니다. 유효하지 않은 ~/.srt-settings.json이면 네트워크를 차단하고 내장 런타임 경로로만 쓰기 제한한 채 시작하므로, 깨끗한 시작을 설정 로드 증명으로 믿지 마세요.
Dev 컨테이너
개발 컨테이너는 VS Code·호환 에디터가 관리하는 Docker 컨테이너 안에서 Claude Code를 실행하고 프로젝트를 마운트합니다. claude-code 저장소는 기본 거부 iptables 방화벽이 있는 예시 dev 컨테이너를 게시합니다. 방화벽이 승인되지 않은 이그레스를 차단하므로 이런 구성은 --dangerously-skip-permissions 무인 작업을 지원합니다.
커스텀 컨테이너
자체 네트워크 정책·볼륨·seccomp 프로필로 어떤 Docker·OCI 컨테이너 이미지에서도 실행할 수 있습니다. 기존 컨테이너 인프라·CI 러너가 있는 조직의 일반적 경로. 마운트되는 쓰기 가능 볼륨, 내부에서 닿을 수 있는 자격 증명·토큰, 네트워크 이그레스 정책이 허용하는 것을 검토하세요. 명령 단위 제한을 위해 컨테이너 안에 내장 Bash 샌드박스를 겹칠 수 있습니다(권한 없는 컨테이너는 중첩 샌드박스 설정 필요).
가상 머신
전용 VM은 자체 커널로(클라우드·마이크로VM에선 가상화 하드웨어) 가장 강한 분리입니다. 신뢰할 수 없는 코드 평가, 커널 레벨 분리가 필요한 정책, 호스트 레벨 접근으로는 컴플라이언스 미충족 시 사용하세요. Docker Sandboxes는 자체 Docker 데몬·워크스페이스 동기화가 있는 마이크로VM으로, Docker Sandboxes가 설치된 모든 호스트에서 Claude Code를 실행할 수 있는 Docker의 무료 독립 제품입니다(Docker Desktop 불필요).
웹의 Claude Code
웹의 Claude Code는 각 세션을 격리된 Anthropic 관리 VM에서 실행합니다. 네트워크 프록시가 기본 allowlist를 강제하고, 별도 프록시가 샌드박스 밖에서 GitHub 토큰을 보관하면서 안에는 범위 지정 자격 증명을 발급합니다. 조직이 셀프 호스팅 환경으로 라우팅한 세션은 사용자가 프로비저닝한 인프라에서 실행됩니다. Claude 구독이 필요하고, 웹 인터페이스에서 시작하면 GitHub 계정 연결도 필요합니다. CLI에서 --cloud로 시작하면 로컬 저장소를 번들·업로드할 수 있습니다.
조직 전체 격리 강제
- 내장 Bash 샌드박스: 유일하게 Claude Code가 자체 강제하는 접근.
sandbox설정 키를 관리 설정으로 전달. 관리 설정으로 샌드박스 강제 참조. - Dev 컨테이너: 예시 컨테이너를 저장소에 커밋해 팀 표준화 — Claude Code가 컨테이너를 요구하진 않으므로 관례지 강제가 아닙니다.
- 커스텀 컨테이너·VM: 승인된 이미지로 배포하고 기기 관리·소프트웨어 allowlist 도구로 그 밖 설치를 차단.