샌드박스 환경 선택

기준일: 2026-07-26
난이도: 중급
공식 기준: Choose a sandbox environment

Claude Code를 격리하면 세션이 읽·쓰·네트워크로 접근할 수 있는 범위를 제한합니다. 권한 프롬프트를 줄이거나, 무인 실행하거나, 신뢰하지 않는 코드를 다룰 때 특히 중요합니다.

개요

호스트 OS 위 경량 샌드박스부터 완전 분리 VM까지 여러 옵션이 있습니다. 이 페이지는 (1) 무엇을 격리하는지, (2) 위협 모델별 선택, (3) 조직 강제 방법을 공식합니다.

관련: 보안, Agent SDK Secure deployment.

핵심 개념

접근	격리 대상	Docker 필요	설정 난이도
Sandboxed Bash tool	Bash 및 자식 프로세스	아니오	macOS 최소 / Linux·WSL2 낮음
Sandbox runtime	Claude Code 전체(파일 도구·MCP·훅 포함)	아니오	낮음
Dev container	전체 개발 환경	예	중간
Custom container	전체 개발 환경	예	중~고
Virtual machine	전체 OS	아니오	높음
Claude Code on the web	Anthropic 호스팅 VM	아니오	없음(구독+GitHub)

중요 차이: Sandboxed Bash tool은 Bash만 제한합니다. Read/Edit/WebFetch 등 내장 파일 도구·MCP·훅은 호스트에서 그대로 실행됩니다. 표의 나머지 방식은 프로세스 전체를 경계 안에 넣습니다.

경고 (공식)

• 샌드박스는 침해 영향을 줄이지만 위험을 제거하지 않습니다.
• 네트워크 egress가 허용되면 에이전트가 읽은 데이터가 유출될 수 있습니다.
• 프로젝트 디렉터리를 쓰기 가능으로 마운트하면 그 코드는 수정될 수 있습니다.
• 격리는 모델로 전송되는 내용을 바꾸지 않습니다. 프롬프트와 읽은 파일은 샌드박스 유무와 관계없이 API/프로바이더로 갑니다. Data usage 참고.

격리 vs 권한 모드

축	역할
Permission modes	도구 호출을 실행할지, 먼저 물을지
Isolation	실행 이후 접근 가능한 범위

--dangerously-skip-permissions 사용 시 프롬프트가 거의 없으므로 격리 경계가 시스템을 지킵니다. 항상 컨테이너·VM 또는 sandbox runtime 안에서 돌리세요. Auto mode는 액션별 분류기이므로 격리 대체가 아닙니다.

상세

목적별 선택

목표	시작점
일상 작업에서 권한 프롬프트 감소	/sandbox로 Sandboxed Bash tool
--dangerously-skip-permissions 또는 auto 무인 실행	dev container / 컨테이너·VM / sandbox runtime
Docker 없이 MCP·훅까지 격리	sandbox runtime
신뢰하지 않는 저장소	전용 VM 또는 (구독+GitHub) Claude Code on the web
팀 표준 환경	저장소에 예제 dev container 복사
로컬 설정 없는 기기	Claude Code on the web
조직 전 개발자 격리 강제	조직 강제 섹션
네이티브 Windows 호스트	컨테이너·VM, 또는 WSL2 안 Bash sandbox

Sandboxed Bash tool

• 네이티브 Windows 미지원 → WSL2 또는 컨테이너/VM 사용
• macOS Seatbelt, Linux/WSL2 bubblewrap
• 기본: 작업 디렉터리 쓰기 허용, 새 네트워크 도메인은 최초 프롬프트
• 활성화: /sandbox
• 미적용: 내장 파일 도구(권한 규칙으로 게이트), MCP·훅(호스트 무제약 프로세스)

Sandbox runtime

• 패키지: @anthropic-ai/sandbox-runtime (beta research preview)
• 전체 프로세스(도구·훅·MCP)를 Seatbelt/bubblewrap으로 감쌈
• 기본 deny-all write/network → 사전 설정 필수
• ~/.srt-settings.json 또는 --settings로 프로젝트 경로, ~/.claude, ~/.claude.json, /tmp, API 도메인 허용
• 실행:

npx @anthropic-ai/sandbox-runtime claude

Dev containers

• VS Code 등이 관리하는 Docker + 프로젝트 마운트
• 공식 예제: default-deny iptables 방화벽 → --dangerously-skip-permissions 무인 작업에 적합
• 저장소에 복사 후 allowlist·베이스 이미지·버전 pin 조정

Custom container / VM / Web

• Custom container: 기존 CI·인프라에 맞춘 Docker/OCI. 쓰기 마운트, 자격 증명, egress 정책 검토. 컨테이너 안에서 Bash sandbox 중첩 가능
• VM: 커널 분리 최강. 비신뢰 코드·컴플라이언스. Docker Desktop sandboxes(microVM) 등
• Claude Code on the web: Anthropic 관리 VM + 네트워크 프록시 allowlist + GitHub 토큰은 샌드박스 밖 프록시. 구독+GitHub 필요

조직에서 강제

방식	강제 수단
Built-in Bash sandbox	Claude Code 자체 강제 — managed settings의 sandbox 키 (MDM 또는 server-managed settings)
Dev containers	저장소 컨벤션. Claude Code가 컨테이너를 강제하지 않음 → MDM/소프트웨어 allowlist로 보완
Custom container/VM	승인 이미지 배포 + 장치 관리로 외부 설치 차단

체크리스트

• 위협 모델(일상 / 무인 / 비신뢰 코드 / 조직 강제)을 골랐다
• Bash-only 샌드박스와 전체 프로세스 격리의 차이를 이해했다
• --dangerously-skip-permissions는 컨테이너·VM·runtime 안에서만 쓴다
• 네트워크 egress와 쓰기 마운트 위험을 검토했다
• 모델로 전송되는 데이터는 샌드박스와 무관함을 팀에 공유했다

다음 단계

• Sandboxing — Bash sandbox 설정
• Dev container
• Security
• Settings sandbox keys

공식 원문: https://code.claude.com/docs/en/sandbox-environments