Claude Code 샌드박스 설정: /sandbox 켜는 법과 권한 규칙 차이

Windows 11에서 설정에 {"sandbox":{"enabled":true}}를 넣고, 비대화형 claude -p로 Claude에게 프로젝트 폴더 밖에 파일을 하나 써 달라고 해 봤습니다. 샌드박스가 켜져 있으니 막혀야 정상이죠.

그런데 파일이 그냥 만들어졌습니다. 남은 건 표준 오류의 경고 한 줄과 종료 코드 0뿐이었어요.

네이티브 Windows는 원래 샌드박스 없이 실행하는 플랫폼이고, 샌드박스가 못 뜨면 기본값은 샌드박스 없이 그냥 실행하는 것이더라고요. 스크립트나 CI에서 표준 오류를 버리면 샌드박스가 켜졌다고 믿은 채 제한 없이 돌게 되고, 대화형 세션에서는 그 경고조차 뜨지 않았습니다.

샌드박스는 세션에서 /sandbox를 열거나 설정에 "sandbox": {"enabled": true}를 두면 켜지고, Bash·PowerShell·Monitor 명령과 그 자식 프로세스가 닿는 파일과 도메인을 운영체제가 막습니다. 도구를 쓰기 전에 할지 말지 정하는 권한 규칙과는 하는 일이 달라서 서로를 대신하지 못해요. 그리고 Windows라면 WSL2에서 쓰고, failIfUnavailable을 꼭 함께 켜길 권합니다.

2026년 9월 15일 공식 문서(샌드박스 설정, 샌드박스 환경 고르기) 기준입니다. 리눅스 의존 패키지와 AppArmor 확인은 Ubuntu 24.04 · Claude Code 2.1.270에서, 네이티브 Windows에서 켰을 때의 동작은 2026년 9월 30일 Windows 11 · PowerShell 5.1 · Claude Code 2.1.283 테스트 환경에서 직접 확인했고, 10월 14일 2.1.296에서 다시 돌려 봤습니다.

규칙 문법은 allow·deny 규칙 문법과 자주 새는 패턴에서 다뤘습니다.

권한 규칙과 뭐가 다른가

npm run build를 allow에 넣어 두었는데 그 빌드 스크립트가 작업 폴더 밖 파일을 고치거나 낯선 서버에 접속하려 한다고 해 봅시다. 권한 규칙은 명령 문자열을 보고 이미 통과시킨 뒤예요. 이때 막을 수 있는 건 실행 중인 프로세스에 운영체제가 거는 경계, 곧 샌드박스입니다.

	권한 규칙	샌드박스
언제	도구 실행 전	명령 실행 중
대상	모든 도구	Bash·PowerShell·Monitor 명령과 자식 프로세스
누가 막나	Claude Code(auto에선 분류기)	운영체제(macOS Seatbelt, Linux·WSL2 bubblewrap)
정하는 것	이 호출을 할지	닿을 수 있는 경로·도메인

/sandbox는 권한 모드가 아니고, 설정도 permissions가 아니라 sandbox 아래에 따로 있습니다(Monitor는 명령을 백그라운드로 돌리며 출력 줄마다 Claude에게 넘겨 주는 도구입니다).

그래도 둘은 합쳐서 돕니다. Edit allow 규칙은 sandbox.filesystem.allowWrite처럼 쓰기 권한을 주고, Read·Edit deny와 WebFetch(domain:...) 규칙도 최종 샌드박스 구성에 들어가요.

샌드박스를 켜면 권한 규칙은 손 안 대도 될 것 같지만, 그렇지 않습니다. 샌드박스 밖에서 도는 게 꽤 많거든요.

• 내장 파일·웹 도구: Read·Edit·Write·WebFetch·WebSearch는 권한 규칙을 따릅니다. 그래서 샌드박스의 denyRead는 Read 도구를 막지 못하고, allowedDomains는 WebFetch를 제한하지 않습니다.
• MCP 서버와 훅: 호스트에서 제약 없이 도는 별도 프로세스입니다.
• Claude Code가 띄우는 다른 프로세스: 명령 훅, 로컬 MCP 서버, 플러그인 모니터, LSP 서버, 상태 표시줄 명령, apiKeyHelper 같은 보조 명령, 모드(mod)가 띄운 프로세스는 사용자 권한 그대로 돕니다.
• 환경 변수: 샌드박스로 도는 명령은 기본적으로 부모 환경을 물려받아, 거기 든 자격 증명도 함께 들어옵니다.

서브에이전트는 부모와 같은 프로세스에서 같은 샌드박스 설정을 쓰므로, 부모에서 켜져 있으면 서브에이전트의 Bash도 샌드박스 안에서 돕니다. 이 범위를 “샌드박스 탈출”로 읽은 공개 보고도 있는데(아래 공개 사례 절), 지금 문서는 이걸 설계된 범위로 설명합니다. 어느 쪽으로 읽든 할 일은 같아요. 파일 도구를 제한하려면 권한 규칙을 쓰세요.

켜면 좁아지는 것과 그대로인 것

대상	기본 경계
쓰기	작업 폴더와 하위, --add-dir·/add-dir·permissions.additionalDirectories로 더한 폴더, $TMPDIR 세션 임시 폴더
읽기	일부 거부 폴더를 뺀 컴퓨터 전체
네트워크	허용 도메인 0개에서 시작, 모두 로컬 프록시 경유

쓰기 밖은 ~/.bashrc 같은 셸 설정과 /bin/의 시스템 바이너리까지 포함해 명시적 허가 없이는 고칠 수 없습니다.

반면 읽기는 넓어서, 기본값에서도 ~/.aws/credentials나 ~/.ssh/가 읽혀요. 제가 보기엔 이 부분이 가장 놓치기 쉽습니다.

기본으로 가려지는 자격 증명 목록은 없으니, 막으려면 sandbox.credentials에 파일 경로와 환경 변수를 직접 적어야 합니다. 적은 것만 읽기가 막히거나 변수가 지워집니다.

허용 목록 밖 호스트에 연결하면 명령은 샌드박스 안에서 결정을 기다리고, 누가 정하는지는 권한 모드에 따릅니다.

• 수동·acceptEdits: 사용자에게 묻습니다.
• auto: 명령이 그 호스트를 미리 적었고 분류기가 승인한 경우가 아니면 거부합니다.
• dontAsk: 거부합니다.

sandbox.network.allowedDomains에 미리 적어 두면 묻지 않습니다.

쓸 수 있는 폴더 안에서도 예외가 있어요. .claude 설정 파일과 .claude/skills·agents·commands·hooks, .mcp.json, .git 안의 hooks와 config 같은 보호 경로는 쓰기가 거부되고, allowWrite나 Edit allow로도 풀 수 없습니다. 끄는 방법은 파일 계층 전체를 끄는 filesystem.disabled뿐입니다.

도메인을 넓게 여는 것이 가장 흔한 구멍입니다. github.com처럼 넓은 도메인을 열면 데이터가 빠져나갈 길이 생기고, 내장 프록시는 기본적으로 TLS를 풀어 내용을 보지 않습니다(실험적 network.tlsTerminate로 TLS를 종료하게 해도 내용 필터링은 더해지지 않습니다).

무엇이 왜 나가려 하는지는 프롬프트 인젝션이 에이전트에서 성립하는 방식과 같은 문제입니다.

auto-allow여도 묻는 것

샌드박스 모드는 둘이고 경계는 같습니다. 다른 건 승인뿐이에요.

auto-allow는 샌드박스로 돌릴 수 있는 명령을 묻지 않고 실행하고, regular permissions는 샌드박스 안에서도 평소 권한 흐름을 탑니다. auto-allow로 두어도 다음은 남습니다.

1. 명시적 deny 규칙은 항상 지켜집니다.
2. 크리티컬 경로를 향한 rm·rmdir은 평소 권한 흐름을 탑니다.
3. Bash(git push *)처럼 내용이 붙은 ask 규칙은 샌드박스 명령에도 묻습니다.
4. 내용 없는 Bash ask(와 Bash(*))는 샌드박스 명령에서 건너뛰고, 샌드박스 밖으로 떨어진 명령에는 적용됩니다. plan 모드에서는 건너뛰지 않아 읽기 전용 명령까지 묻습니다(v2.1.212 이전에는 plan에서도 건너뜀).

auto-allow는 권한 모드와 따로 동작합니다(예외: plan 모드, 명령별 허용 도메인을 단 auto 모드 명령, auto 모드에서 서버 쪽 분류기가 샌드박스 명령을 검토하는 경우). 그래서 수동 모드 세션에서도, 경계 안에서 파일을 고치는 Bash 명령은 묻지 않고 실행됩니다. 같은 일을 파일 편집 도구로 했다면 물었을 상황에서도요.

막힌 명령이 그대로 끝나지는 않습니다. 네트워크가 막히면 막힌 호스트 이름이 결과에 담겨 Claude에게 가고, Claude가 실패를 보고 dangerouslyDisableSandbox를 붙여 다시 시도할 수 있어요. 재시도한 명령은 샌드박스 밖이라 다시 권한 흐름을 탑니다.

이 탈출구를 닫는 게 allowUnsandboxedCommands: false이고, /sandbox의 Overrides 탭에 Strict sandbox mode로 보입니다.

다만 이건 Claude가 실행하는 명령에만 적용돼, 사람이 ! 셸 모드로 친 명령은 샌드박스 밖에서 돕니다(백그라운드 세션과 CLAUDE_CODE_SUBPROCESS_ENV_SCRUB이 설정된 리눅스 세션은 예외, v2.1.260 이전에는 모든 세션에서 안에서 돌았음).

명령이 샌드박스 안에서 돌았는지는 프롬프트 제목으로 알 수 있습니다. 수동·acceptEdits 모드에서 샌드박스로 돌릴 수 없어 평소 권한 흐름으로 떨어진 명령은 제목이 “Bash command”가 아니라 “Bash command (unsandboxed)“로 보이고, 지금 적용 중인 설정은 /sandbox의 Config 탭에서 봅니다.

또 하나, 의존 패키지가 없거나 플랫폼이 지원 대상이 아니라 샌드박스가 못 뜨면 기본값은 샌드박스 없이 실행하는 것입니다. 도입에서 겪은 게 바로 이거예요. 이걸 실패로 바꾸는 설정이 sandbox.failIfUnavailable: true입니다.

무인 실행이라면 컨테이너부터

목적별 출발점은 이렇게 고릅니다.

하고 싶은 것	출발점
사용자 컴퓨터에서 매일 승인 대화 줄이기	/sandbox 내장 샌드박스
--dangerously-skip-permissions·auto로 맡겨 두기	dev container, 컨테이너·VM, sandbox runtime
MCP 서버·훅까지 Docker 없이 격리	sandbox runtime
믿을 수 없는 저장소 열기	전용 VM, 또는 Claude Code on the web
네이티브 Windows에서 작업	컨테이너·VM, 또는 WSL2 안 샌드박스

내장 샌드박스는 셸 명령만 묶으므로 어느 모드로든 완전 무인 실행에는 부족합니다. 프롬프트 없는 --dangerously-skip-permissions 세션은 파일 도구·MCP 서버·훅까지 경계 안에 들도록 컨테이너, VM, sandbox runtime 안에서 돌리세요. 컨테이너 안에서 내장 샌드박스를 켜면 명령 단위 제한이 한 겹 더 얹힙니다.

샌드박스는 위험을 줄일 뿐 완전한 격리 경계가 아니고, 프로세스 전체를 감싸는 @anthropic-ai/sandbox-runtime은 설정 형식이 바뀔 수 있는 베타 연구 미리보기입니다.

리눅스·WSL2 준비

샌드박스는 macOS, Linux, WSL2에서 돕니다. macOS는 내장 Seatbelt를 쓰니 설치할 게 없고, 리눅스·WSL2는 아래 순서로 준비합니다. WSL1은 bubblewrap이 요구하는 커널 기능이 없어 지원하지 않아요.

1. bubblewrap과 socat이 있는지 보기

파일 격리는 bubblewrap, 샌드박스 프록시로 트래픽을 넘기는 중계는 socat이 맡습니다. ripgrep은 네이티브 바이너리에 들어 있고, Unix 도메인 소켓을 막는 seccomp 필터는 선택입니다.

command -v bwrap socat || echo "찾지 못함"

Ubuntu 24.04 테스트 환경에서는 찾지 못함이 나왔습니다. 이 상태로 /sandbox를 열면 Dependencies 탭만 보여요. 배포판 패키지 관리자로 설치하고(sudo apt-get install bubblewrap socat), 의존성 검사는 시작할 때 돌므로 Claude Code를 다시 띄웁니다.

2. Ubuntu 24.04 이상이면 AppArmor 값 보기

Ubuntu 24.04 이상의 기본 AppArmor 정책은 bubblewrap이 격리에 쓰는 사용자 네임스페이스를 못 만들게 막을 수 있습니다.

sysctl kernel.apparmor_restrict_unprivileged_userns

0이면 넘어가고, No such file or directory면 키가 없는 것이라 역시 넘어가고, 1이면 bwrap에 userns를 허용하는 AppArmor 프로필을 추가합니다. 제 테스트 환경은 키가 없는 경우였지만, 같은 Ubuntu 24.04여도 값이 다를 수 있으니 직접 돌려 보세요.

3. 켜고, 필요하면 탈출구 닫기

세션 안에서 /sandbox를 열어 켜거나 설정 파일에 sandbox.enabled를 둡니다. --sandbox 같은 명령줄 옵션은 없습니다(2.1.270 --help 기준). 설정 파일을 건드리지 않고 한 세션만 막힌 명령의 샌드박스 밖 재시도까지 닫고 시작하려면 공식 문서의 예시처럼 --settings를 씁니다.

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

네이티브 Windows에서 켜 봤더니

도입에서 말한 그 경고입니다.

⚠ Sandbox disabled: sandbox is enabled but the Windows sandbox is not active on this session (feature gate off)
  Commands will run WITHOUT sandboxing. Network and filesystem restrictions will NOT be enforced.

Windows 11 · 2.1.283에서 {"sandbox":{"enabled":true}}를 켜고 claude -p로 프로젝트 폴더 밖에 파일을 쓰라고 시키자, 표준 오류에 이 경고만 남기고 종료 코드 0으로 파일을 실제로 만들었습니다. 경고에 Windows 샌드박스와 기능 플래그 얘기가 나오지만, 네이티브 Windows는 샌드박스 없이 실행한다는 게 문서의 설명이니 곧 지원된다는 뜻으로 읽지 않는 게 좋습니다.

failIfUnavailable을 함께 켜면({"sandbox":{"enabled":true,"failIfUnavailable":true}}) 결과가 바뀌었습니다.

설정	종료 코드	프로젝트 밖 파일
enabled만	0	생김
enabled + failIfUnavailable	1	안 생김

Error: sandbox required but unavailable: sandbox is enabled but the Windows sandbox is not active on this session (feature gate off)
  sandbox.failIfUnavailable is set — refusing to start without a working sandbox.

10월 14일 2.1.296에서도 두 결과가 그대로였습니다. 경고 문구도 한 글자 다르지 않았어요.

대화형 세션은 더 조용했습니다. 같은 {"sandbox":{"enabled":true}}로 claude를 띄우니 시작 화면에도, 15초가 지나서도 경고가 없었고, 프로젝트 밖에 파일을 쓰라는 요청도 아무 표시 없이 끝났어요. 파일은 실제로 생겼습니다.

샌드박스 상태를 직접 물어봐야 알 수 있습니다. 같은 세션에서 /sandbox를 열면 그제야 지원하지 않는다는 오류가 나와요.

샌드박스를 믿고 권한을 느슨하게 잡는 설정이라면 failIfUnavailable을 같이 켜 두세요. 조용히 그냥 도는 것보다 시작을 거부하는 쪽이 훨씬 낫습니다. 네이티브 Windows에서 제한이 필요하면 권한 규칙으로 막거나 WSL2에서 실행합니다.

자주 나는 오류

bwrap: Can't mount proc on /newroot/proc: Operation not permitted

권한 없는 컨테이너 안에서는 bubblewrap이 새 /proc을 마운트할 수 없습니다. sandbox.enableWeakerNestedSandbox를 true로 두면 안쪽 샌드박스가 컨테이너의 기존 /proc을 바인드 마운트해요. 바깥 컨테이너가 이미 필요한 격리를 해 줄 때만 쓰세요.

unable to unlink old

git merge나 git checkout이 이 메시지로 실패하고, 리눅스·WSL2에서는 Read-only file system이 붙습니다. 바꿀 파일이 보호 경로이거나 denyWrite에 걸렸거나 쓸 수 있는 폴더 밖이기 때문입니다. Claude가 샌드박스 밖 재시도를 제안하면 승인하거나 다른 터미널에서 직접 실행합니다(allowUnsandboxedCommands: false면 제안이 없으니 직접).

자주 걸리는 명령은 excludedCommands에 넣으면 되는데, v2.1.282부터는 자리가 중요합니다. managed 설정이나 --settings가 allowUnsandboxedCommands: false를 두거나 managed 설정이 allowManagedDomainsOnly: true를 두면, 프로젝트·로컬 설정의 excludedCommands 항목은 무시됩니다.

그때 어디에 적어야 하는지는 변경 기록에 없고, 2026년 9월 28일의 설정 문서는 여전히 세션이 읽는 모든 범위의 항목을 합친다고 설명해 변경 기록과 어긋납니다.

네트워크를 쓰는 명령이 허용되지 않은 호스트로 실패할 때

기본 허용 도메인이 0개라 처음 보는 호스트는 승인 대상입니다. 물을 때 승인하거나 allowedDomains에 더하세요. 조직이 allowManagedDomainsOnly로 목록을 잠갔다면 묻지도 않으니 관리자에게 호스트 추가를 요청해야 합니다.

jest가 멈추거나 docker 명령이 실패할 때

watchman과 docker는 샌드박스와 호환되지 않습니다. jest --no-watchman으로 돌리고, docker는 docker compose *처럼 필요한 명령만 excludedCommands에 넣어 밖에서 실행합니다.

docker *처럼 넓게 넣으면 그 도구가 할 수 있는 모든 일을 사용자 권한으로 열어 주게 돼요. 위의 v2.1.282 조건도 똑같이 적용됩니다.

다른 사람들이 겪은 문제

버전(2.0.73~2.1.117)과 운영체제가 제각각이라 지금 같은 증상이 난다는 뜻은 아닙니다.

• SAIL-Fang(2025-12-30, #15789)은 Ubuntu/Debian · 2.0.76에 sandbox.enabled: true를 켰는데 Bash는 막혔지만 Glob과 Write는 상위 폴더를 훑고 파일을 썼다고 보고했고, not planned로 닫혔습니다. 앞에서 말한 “샌드박스는 셸 명령만 감싼다”는 범위 그대로의 동작입니다.
• talpah(2025-12-19, #14719)는 Ubuntu/Debian, 커널 6.8.0-90-generic, bubblewrap 0.9.0, 2.0.73에서 bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted로 곧바로 실패했다고 했습니다. kernel.unprivileged_userns_clone = 1이고 AppArmor 제한도 없었다며, 네트워크 격리가 필요 없는 명령에 --share-net을 쓰자고 제안했습니다. not planned로 닫혔습니다.
• dfaivre-pcs(2026-02-28, #29596)는 WSL2 · 2.1.63에서 프로젝트 설정의 sandbox.network.allow에 api.github.com을 적었는데도 gh 명령마다 승인을 물었다고 했습니다. 지금 문서의 키 이름은 sandbox.network.allowedDomains로 다르지만, 그 차이가 원인이라고 단정하지는 않겠습니다. 저장소 안에 두면 효력이 없는 키(strictAllowlist 등)가 있다는 점은 확실합니다.
• mb21(2026-04-23, #52322)은 macOS · Claude Code for VSCode 2.1.117에서 allowWrite에 넣은 경로에 Edit·Write·touch는 되는데 rm은 Operation not permitted로 거부됐다고 했습니다. 설정에는 denyWrite: ["/"]와 denyRead: ["/"]가 함께 있었습니다.

걸리는 자리를 보면 범위 오해, 커널 기능, 도메인 키, 삭제 권한으로 저마다 다릅니다. 같은 증상을 만나면 먼저 그 명령이 셸 명령인지, 그리고 지금 버전의 문서가 쓰는 키 이름과 맞는지부터 보세요.

마치며

샌드박스는 셸 명령에 치는 울타리이고, 파일 도구·MCP 서버·훅은 그 울타리 밖에 있습니다. 거기에 읽기는 기본으로 넓어 자격 증명도 읽히고요.

그중에서도 제가 가장 조심하라고 말하고 싶은 건, 샌드박스가 못 뜨면 조용히 그냥 실행해 버린다는 점이에요. 켜 둔 보호 장치가 실제로 막는지는 한 번 막혀 봐야 압니다.

리눅스나 WSL2라면 지금 command -v bwrap socat부터 돌려 보고, 설정에 "failIfUnavailable": true를 함께 넣으세요.

같은 질문을 다른 도구에 던진 결과는 Claude Code·Codex·Gemini CLI 샌드박스 비교와 Codex CLI 샌드박스 모드와 승인 정책으로 이어집니다.