Claude Code 샌드박스

한 줄 요약: Claude Code 공식 문서 "Configure the sandboxed Bash tool". Claude가 내 기기에서 돌리는 셸 명령(Bash, PowerShell, Monitor)과 그 하위 프로세스 둘레에 운영체제가 강제하는 경계를 켜고, 닿을 수 있는 파일·네트워크 도메인을 정하고, 그 경계가 깨뜨리는 도구를 고치는 법을 다룬다. 샌드박스가 막지 못하는 것(파일 도구, MCP 서버, 훅, 사용자가 직접 친 명령, 제외 명령, 샌드박스 밖 재시도)과 보안 한계도 함께 적는다.

원본 정보#

• 제목: Configure the sandboxed Bash tool
• 발행: Anthropic, Claude Code 공식 문서. 본문에 날짜 없음(원본 날짜 미상). 서버 Last-Modified 2026-10-20
• URL: https://code.claude.com/docs/en/sandboxing (새 창)
• 수집(fetch)일: 2026-10-21. 본문의 설정 키, 명령, 버전 조건(v2.1.186~v2.1.285)은 이 날짜 기준이다.
• 구성: 샌드박스가 제한하는 것(기본값 표, 샌드박스 밖에서 도는 것) → 시작하기(/sandbox, 모드 고르기, 작동 확인, Linux·WSL2 설치) → 샌드박스 모드(auto-allow, regular, 샌드박스 밖 재시도, strict sandbox mode, 임시 디렉터리) → 설정(allowWrite·denyRead·allowRead, excludedCommands, 파일 격리 끄기, 자격 증명 보호·가리기) → 작동 원리(파일 격리, 보호 경로, 네트워크 격리, OS별 강제) → 권한 규칙·권한 모드와의 관계 → 조직 설정(managed 강제, 정책 넓히기 막기, 관리자 필수 샌드박스, 사용자 프록시) → 문제 해결 15가지 → 한계.

핵심 주장#

1. 샌드박스는 셸 명령만 감싼다. 제한은 Bash, PowerShell, Monitor 명령과 그 명령이 시작한 프로세스에 적용되고, 기본으로 꺼져 있다. Read·Edit·Write·WebFetch·WebSearch 같은 내장 도구는 권한 규칙을 따르므로 denyRead가 Read 도구를 막지 않고 allowedDomains가 WebFetch를 제한하지 않는다. 훅 명령, 로컬 MCP 서버, 플러그인 monitor, LSP 서버, 상태 줄 명령, apiKeyHelper는 사용자의 전체 권한으로 돈다. 이것들까지 한 경계 안에 넣으려면 Claude Code 프로세스 자체를 컨테이너·VM·sandbox runtime에서 돌리라고 원본은 말한다. → 샌드박스
2. 기본값은 "쓰기는 좁게, 읽기는 넓게, 네트워크는 허용 목록"이다. 쓰기는 작업 디렉터리, 사용자별 임시 디렉터리, 추가한 디렉터리뿐이고 보호 경로는 그 안에서도 막힌다. 읽기는 ~/.ssh, ~/.aws/credentials 같은 자격 증명 파일을 포함해 기기 대부분을 읽을 수 있다. 네트워크는 직접 나가는 길이 없고 내 기기의 프록시를 거치며, 허용 도메인은 빈 목록에서 시작한다. 환경 변수는 Claude Code의 환경(비밀 값 포함)을 물려받는다. 내장 자격 증명 차단 목록은 없어서 적은 파일·변수만 막힌다. → 샌드박스, Claude Code 샌드박스 설정하기
3. 운영체제마다 강제 방식과 결과가 다르다. macOS는 내장 Seatbelt, Linux와 WSL2는 bubblewrap과 socat을 쓰고, Windows 네이티브에서는 샌드박스 없이 명령을 돌린다(WSL1도 미지원). 자격 증명 파일 mask는 Linux·WSL2에서는 가짜 값(sentinel) 사본을 보여 주지만 macOS에서는 파일을 아예 못 읽게 막는다. SSH remote에 대한 git fetch·pull·push는 macOS 샌드박스 안에서 실패하고, Linux·WSL2에서는 호스트를 허용하면 된다. localhost 서버 접속도 macOS는 allowLocalBinding, Linux·WSL2는 제외 명령으로 푼다. → 샌드박스
4. 샌드박스 밖으로 나가는 길이 세 가지 있고, 각각 조건이 다르다. (1) 사용자가 ! 셸 모드에 직접 친 명령은 대부분의 세션에서 샌드박스 밖에서 돈다. (2) excludedCommands에 맞는 명령은 파일 제한·네트워크 프록시 없이 사용자의 전체 권한으로 돈다. (3) 샌드박스 안에서 실패한 명령을 Claude가 dangerouslyDisableSandbox로 다시 돌리자고 할 수 있고, 누가 승인하는지는 권한 모드가 정한다(bypassPermissions는 묻지 않음, dontAsk는 거부). allowUnsandboxedCommands: false(strict sandbox mode)가 (3)을 닫고, 샌드박스가 못 뜰 때 샌드박스 없이 도는 것은 failIfUnavailable이 막는다. → 샌드박스, Claude Code 관리자 권한 통제
5. 샌드박스는 위험을 줄이지만 완전한 격리 경계가 아니다. 내장 프록시는 기본으로 TLS를 풀어 보지 않고 클라이언트가 대는 호스트 이름으로 허용 여부를 정하므로, github.com 같은 넓은 도메인을 허용하면 데이터 유출 경로가 될 수 있고 domain fronting 같은 기법으로 허용 목록 밖에 닿을 가능성이 있다. Unix 소켓 허용(예: /var/run/docker.sock), 넓은 쓰기 허용($PATH 실행 파일 디렉터리, .bashrc), enableWeakerNestedSandbox, allowAppleEvents는 경계를 약하게 만든다. 원본은 파일 격리와 네트워크 격리가 둘 다 있어야 효과가 있다고 경고한다. → 샌드박스
6. 조직은 managed settings로 샌드박스를 "관리자 필수"로 만들 수 있다. allowUnsandboxedCommands: false(managed나 --settings)나 managed allowManagedDomainsOnly: true가 있으면, 저장소의 .claude/settings.json·.claude/settings.local.json이 샌드박스를 느슨하게 하는 설정(excludedCommands, allowedDomains, allowWrite 등)을 무시한다(v2.1.285 이상). 다만 개발자 자신의 ~/.claude/settings.json과 --settings의 같은 설정은 managed 전용 잠금이 없는 한 계속 적용된다. → Claude Code 관리자 권한 통제, managed settings

원본의 설정 예시 (원문 그대로, 2026-10-21 기준)#

설정 예시 전체는 Claude Code 샌드박스 설정하기에 원문 글자 그대로 옮겼다. 대표 두 개:

한 세션만 샌드박스를 켜고 샌드박스 밖 재시도를 닫기:

claude --settings '{"sandbox": {"enabled": true, "allowUnsandboxedCommands": false}}'

조직 전체에 강제(managed settings):

{
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "allowUnsandboxedCommands": false
  }
}

원본에 없는 것#

• 컨테이너·dev container·VM 같은 다른 격리 방식의 비교: 원본은 Sandbox environments 문서로 넘긴다.
• 클라우드 세션의 격리: 원본은 Claude Code on the web 문서의 Security and isolation으로 넘긴다.
• 각 설정 키의 전체 필드(extract, decode, maskClaims, onExtractNoMatch, maskDuplicates, awsPairs, sigv4, 경로 접두사 규칙): settings reference로 넘긴다. 이 위키의 Claude Code 설정 키 레퍼런스는 이 세부 필드를 뺐다.
• 샌드박스를 실제 조직에 배포한 사례나 차단 건수 같은 숫자: 원본에 없다.

원본이 링크한 관련 문서#

Sandbox environments, Claude Code on the web(Security and isolation), Environment variables(CLAUDE_CODE_SUBPROCESS_ENV_SCRUB, CLAUDE_CODE_TMPDIR), Interactive mode(셸 모드), Agent view(백그라운드 세션), Network config(프록시), Server-managed settings, Errors, Tools reference(Monitor, LSP), Plugins(monitors, mods), Status line, Worktrees, Computer use, Desktop, Dev container, Corporate launcher, Security, Agent SDK(settingSources), @anthropic-ai/sandbox-runtime 저장소, claude-code 저장소의 예시 설정 디렉터리. 이 사이트에서 다룬 문서: Permissions(Claude Code 권한 설정), Permission modes(Claude Code 권한 모드), Settings(Claude Code 설정 파일과 우선순위), settings reference(Claude Code 설정 키 전체 레퍼런스), Managed settings(Claude Code managed settings 배포), Hooks, MCP, Subagents, CLI reference.