요약
- /sandbox 명령은 Mode·Overrides·Config 탭이 있는 패널을 엽니다. auto-allow 모드는 샌드박스 bash 명령을 허가 프롬프트 없이 실행하고, regular permissions은 모든 프롬프트를 유지합니다.
- 경계는 프롬프트가 아니라 커널이 강제합니다. macOS는 Seatbelt, Linux와 WSL2는 bubblewrap. 네이티브 Windows와 WSL1은 미지원입니다.
- 샌드박스 명령이 쓸 수 있는 곳은 작업 디렉터리, 사용자별 임시 디렉터리, --add-dir로 추가한 경로뿐입니다. 네트워크 트래픽은 도메인을 하나도 미리 허용하지 않는 프록시를 거칩니다.
- 읽기는 기본적으로 막히지 않습니다. sandbox.credentials 규칙을 추가하기 전까지 ~/.ssh와 ~/.aws는 그대로 읽힙니다. VS Code Sandbox 대화상자는 v2.1.280에 들어왔습니다.
Claude Code Sandbox Explained
영상:The Art of Vibe Coding4:29
How auto mode works with Claude Code
영상:Claude5:42
Configure the sandboxed Bash tool (official docs)
문서:code.claude.com
첫 번째 영상은 모션 그래픽 해설로, 이 페이지의 프레임은 스크린샷이 아니라 스타일화된 삽화이며 일부 주장은 아래 단계에서 정정됩니다(자격 증명은 기본적으로 읽힘. 영상의 settings 키 예시는 실제 키와 다름). 두 번째 영상은 Anthropic 공식 녹화로, 실제 터미널과 설정 UI만 사용했습니다.
사실 확인은 code.claude.com/docs/en/sandboxing과 anthropics/claude-code CHANGELOG(v2.1.280–2.1.283) 기준. 스틸 컷은 해설을 위해 녹화의 짧은 구간을 인용한 것입니다.
12단계로 설정하는 Claude Code 샌드박스
경계 이해하기
- 1
승인 피로 문제 인식하기
샌드박스가 없으면 제안된 명령마다 y/n에서 멈춥니다. npm install, git status, 그리고 다음 명령. Anthropic이 측정했듯 Claude Code 권한 요청의 97%가 승인됩니다. 그래서 샌드박스는 검사를 개별 명령에서 한 번만 설정하면 되는 경계로 옮긴 것입니다.
샌드박스가 대체하는 명령별 y/n 루프의 재현 — Enter를 47번 누쯤 읽기를 포기하게 됩니다.0:22 보기 - 2
지원 플랫폼에서 Claude Code 시작하기
프로젝트에서 세션을 엽니다. macOS는 샌드박스가 내장되어 있고 Seatbelt가 OS에 포함되어 설치가 필요 없습니다. Linux와 WSL2에서는 먼저 패키지 관리자로 bubblewrap과 socat을 설치하세요. 네이티브 Windows와 WSL1은 미지원이며, Windows 사용자는 WSL2 배포판 안에서 Claude Code를 돌립니다.
~/Documents/code/acme에서의 세션 — 이 작업 디렉터리가 샌드박스가 쓸 수 있는 영역이 됩니다.0:35 보기 - 3
/sandbox 실행 후 패널 읽기
세션에서 /sandbox를 입력합니다. 패널에는 탭이 셋 있습니다. Mode(샌드박스 명령 승인 방식), Overrides(실패한 명령이 샌드박스 밖에서 재시도할 수 있는지 — allowUnsandboxedCommands 설정), Config(완전히 해석된 샌드박스 설정). Linux에는 누락된 항목(bubblewrap, socat, 선택적 seccomp 필터 등)을 나열하는 Dependencies 탭이 더 생깁니다. v2.1.281부터는 방향키로 탭을 전환할 수 있고, VS Code에는 v2.1.280에서 같은 설정의 Sandbox 대화상자가 추가됐습니다.
켜기
- 4
auto-allow 또는 regular permissions 선택
Mode 탭에서 auto-allow는 샌드박스 명령을 묻지 않고 실행하고, regular permissions은 샌드박스 명령이라도 프롬프트를 유지합니다. 선택은 프로젝트의 .claude/settings.local.json에 저장되며 Claude Code가 gitignore 해 줍니다. 모든 프로젝트를 커버하려면 ~/.claude/settings.json에 "sandbox": undefined를, 단일 세션이면 --settings로 전달하세요.
2단계 퀵스타트: /sandbox에서 모드를 고르고, settings.json에 영구 설정을 맡깁니다.4:00 보기 - 5
auto-allow도 묻는 것들 알아두기
auto-allow는 음소거 버튼이 아닙니다. 명시적 deny 규칙은 언제나 이기고, 중요 경계를 겨냥한 rm이나 rmdir은 여전히 프롬프트를 내며, Bash(git push *) 같은 내용 기반 ask 규칙도 확인을 강제합니다. 샌드박스에서 실행할 수 없는 명령은 "Bash command (unsandboxed)" 제목의 프롬프트와 함께 일반 흐름으로 폴백합니다. auto-allow는 권한 모드와도 독립적으로 작동해 Manual 모드에서도 샌드박스 bash는 프롬프트 없이 돌아갑니다.
shift+tab은 권한 모드를 순환합니다 — 샌드박스의 auto-allow와는 별개 조작입니다.0:28 보기 - 6
OS가 경계를 긋는 방식 보기
제한은 커널 강제이지 정중한 부탁이 아닙니다. macOS는 Seatbelt, Linux와 WSL2는 bubblewrap. ~/.ssh를 읽으려 하거나 외부로 연락하려는 프롬프트 인젝션 명령도 같은 벽에 부딪힙니다. 규칙은 실행 중 프로세스와 그 자식 모두에 묶이므로, 모델은 말로 커널을 넘을 수 없습니다.
애플리케이션 계층의 권한 검사는 우회할 수 있지만, 커널 계층은 우회할 수 없습니다.2:07 보기
파일 시스템, 자격 증명, 네트워크
- 7
파일 시스템 기본값과 읽기 주의점 이해하기
샌드박스 명령이 쓸 수 있는 곳은 작업 디렉터리와 그 하위 디렉터리, 사용자별 임시 디렉터리, --add-dir이나 permissions.additionalDirectories로 추가한 폴더입니다. 읽기는 기본적으로 열려 있습니다. ~/.aws/credentials와 ~/.ssh를 포함한 디스크 전체가 직접 막기 전까지 읽힙니다. 해설 영상은 자격 증명이 "안 보이게 된다"고 말하기 쉽지만, 문서는 냉정하게 sandbox.credentials나 denyRead 규칙으로 지키는 건 당신 몫이라고 말합니다.
쓰기는 샌드박스 벽에서 멈춥니다. 읽기는 다음 단계에서 닫기 전까지 열려 있습니다.1:30 보기 - 8
자율 실행 전에 자격 증명 지키기
sandbox.credentials 블록을 추가합니다. ~/.ssh나 ~/.aws/credentials 같은 파일을 "mode": "deny"로 나열하고 GITHUB_TOKEN 같은 비밀 환경 변수도 넣으면 샌드박스 명령 안에서 unset됩니다. mask 모드는 한 걸음 더 나아가 명령에는 센티널 값이 보이고 샌드박스 프록시가 허용한 호스트에서만 실제 값으로 바꿔 줍니다. 파일 도구 위에는 permissions.deny Read 규칙이 얹힙니다.
curl과 .env 읽기에 대한 deny 규칙 — 같은 settings 파일이 sandbox 블록도 함께 담습니다.4:35 보기 - 9
스택에 필요한 네트워크 도메인 허용하기
샌드박스 트래픽은 모두 프록시를 거치며 미리 허용된 도메인은 없습니다. 명령이 처음 호스트를 필요로 하면 Claude Code가 프롬프트를 내고, "Yes, and don't ask again"으로 답하면 WebFetch(domain:...) allow 규칙을 이후 세션을 위해 저장합니다. sandbox.network.allowedDomains으로 레지스트리를 미리 허용하고, deniedDomains으로 특정 호스트를 막고, strictAllowlist를 설정하면 목록이 프롬프트 후보가 아니라 상한선이 됩니다.
레지스트리 요청은 프록시를 통과합니다. evil.com으로 연락하는 postinstall 스크립트는 통과하지 못합니다.1:51 보기 - 10
설정 범위 정하기: 프로젝트, 사용자, 관리
.claude/settings.json의 프로젝트 설정은 쓰기 가능 경로와 도메인을 추가할 수 있지만, 파일 시스템 격리를 끄거나 Apple Events를 켤 수는 없습니다. 그 키들은 사용자 설정, 관리 설정, --settings 플래그에서만 존중되므로 체크아웃한 저장소가 샌드박스를 약화시킬 수 없습니다. 팀은 관리 설정에서 enabled, failIfUnavailable, allowUnsandboxedCommands를 true/false/false로 두어 샌드박스를 강제합니다.
관리 설정 파일은 조직의 신뢰 환경을 기술합니다. 관리자가 놓고 개발자가 상속합니다.4:10 보기
검증과 수정
- 11
실제 작업으로 검증하기
빌드나 테스트 실행을 부탁해 보세요. 샌드박스 명령은 프롬프트 없이 실행되고, 무언가 막히면 위반이 명령 결과에 경로나 호스트를 알려 주므로 Claude가 적응할 수 있습니다. /sandbox의 Config 탭을 열면 어떤 설정도 덮어쓸 수 없는 보호 경로까지 해석된 규칙이 모두 읽힙니다. 일회성 엄격 시험은 claude --settings 'undefined}'로 시작하세요.
작업 하나 입력, 명령별 프롬프트 없음 — 당신이 없어도 경계는 유지됩니다.0:32 보기 - 12
흔한 실패 문제 해결하기
jest가 멈춤 — watchman과 호환되지 않으므로 jest --no-watchman으로 실행. docker 실패 — 샌드박스에서 돌 수 없으므로 excludedCommands에 "docker *" 추가. macOS에서 open이나 osascript가 -600 오류 — allowAppleEvents가 true가 아니면 Apple Events는 차단됩니다. git merge나 checkout이 "unable to unlink old"로 실패 — 보호 경로나 denyWrite 규칙이 가로막은 것이므로 샌드박스 밖 재시도를 승인하거나 직접 실행. 컨테이너 안에서 bwrap이 Operation not permitted — enableWeakerNestedSandbox 설정. 클립보드 파이프가 비어 있음 — pbcopy 대신 /copy 사용.
중요한 샌드박스 설정들
/sandbox 패널이 기본을 써 주지만, 진짜 지렛대는 settings.json에 있습니다. 다음은 공식 샌드박싱 레퍼런스가 문서화한 키들입니다. 모두 "sandbox" 블록 아래 놓입니다(마지막 하나만 "permissions" 아래).
- 1sandbox.enabled — 직접 뒤집기 전까지는 꺼져 있습니다. ~/.claude/settings.json에서 true로 두면 모든 프로젝트에 적용되고, /sandbox 패널은 프로젝트 로컬 사본을 .claude/settings.local.json에 씁니다.
- 2sandbox.autoAllowBashIfSandboxed — auto-allow 스위치로 기본값은 true. false로 두면 샌드박스 안에서 도는 명령에도 권한 프롬프트가 유지됩니다.
- 3sandbox.allowUnsandboxedCommands와 sandbox.failIfUnavailable — 첫 번째를 false로 하면 dangerouslyDisableSandbox 재시도가 죽고(Overrides 탭에서 Strict sandbox mode로 표시), 두 번째를 true로 하면 의존성 누락이 경고가 아니라 하드한 시작 실패가 됩니다.
- 4sandbox.filesystem — 도구가 프로젝트 밖에서 필요로 하는 경로의 allowWrite("~/.kube", "/tmp/build"), 민감한 위치의 denyRead와 allowRead, 그리고 네트워크 격리를 유지한 채 파일 시스템 계층을 내리는 disabled(v2.1.216+).
- 5sandbox.network — allowedDomains과 deniedDomains, 목록에 없는 것은 모두 금지하는 strictAllowlist(v2.1.219+), dev 서버가 포트를 bind하게 하는 allowLocalBinding, 프록시에서 자격 증명을 마스킹하는 tlsTerminate.
- 6sandbox.credentials — deny 또는 mask 모드의 파일과 envVars 항목. mask는 tlsTerminate를 요구하며 사용자·관리·--settings 소스에서만 존중됩니다. permissions.blockReadsOutsideWorkingDirectories와 짝을 이루면 작업 디렉터리 밖의 모든 읽기를 끊습니다.
Seatbelt vs bubblewrap: 플랫폼 차이
macOS는 OS에 내장된 Seatbelt를 씁니다 — 설치할 것이 없습니다. 거친 부분은 구체적입니다. gh, gcloud, terraform 같은 Go 기반 CLI는 Seatbelt 아래에서 TLS 검증에 실패할 수 있으므로 excludedCommands에 나열하세요. open, osascript, 브라우저 인증 흐름은 allowAppleEvents를 설정하기 전까지 -600 오류로 실패하며, 이는 격리를 약화시키고 프로젝트 설정에서는 무시됩니다.
Linux와 WSL2는 패키지 관리자로 설치하는 bubblewrap과 socat을 씁니다. 선택적 seccomp 필터(npm install -g @anthropic-ai/sandbox-runtime)는 Unix 도메인 소켓 차단을 더하고, WSL2가 Windows 바이너리를 밀어내는 장치이기도 합니다. Ubuntu 24.04 이상은 bubblewrap이 사용자 네임스페이스를 만들지 못하게 하는 AppArmor 정책을 싣고 있으므로 문서의 bwrap 프로파일을 추가하고 AppArmor를 리로드하세요. 비특권 컨테이너 안에서는 enableWeakerNestedSandbox를 설정하면 bubblewrap이 기존 /proc를 bind 마운트합니다.
WSL1은 전혀 지원되지 않습니다 — bubblewrap은 WSL2에만 있는 커널 기능을 필요로 합니다. 성능 오버헤드는 최소지만 일부 파일 시스템 작업은 약간 느립니다. 서브에이전트는 부모 세션과 같은 프로세스에서 돌고 그 샌드박스 설정을 상속하므로, 에이전트 안의 백그라운드 bash도 샌드박스화됩니다.
샌드박스 처리는 릴리스 사이에서 계속 움직입니다. v2.1.280은 VS Code Sandbox 대화상자를, v2.1.281은 /sandbox 탭 탐색과 dev 서버용 allowLocalBinding 힌트를, v2.1.282–2.1.283은 excludedCommands 매칭, TMPDIR 쓰기, 관리 설정 파싱을 수정했습니다. 엣지 케이스 동작에 의존하기 전에 CHANGELOG를 훑으세요.