샌드박스란 무엇인가
문서에서는 이 경계를 한 문장으로 설명합니다: "샌드박스가 켜져 있는 동안, Claude가 실행하는 쉘 명령어와 그 명령어가 시작하는 프로세스는 샌드박스 경계 내부에서 시작됩니다."
직접 켜기 전까지는 꺼져 있습니다. 문서에 따르면: "샌드박스는 기본적으로 꺼져 있습니다."
강제 적용은 운영 체제 수준에서 이루어집니다. macOS에서 Claude Code는 내장된 Seatbelt 프레임워크를 사용합니다. Linux 및 WSL2에서는 bubblewrap과 socat이라는 두 패키지에 의존합니다. 문서에 따르면 Claude Code는 Anthropic의 오픈 소스 샌드박스 런타임 패키지를 기반으로 샌드박스를 구축합니다.
샌드박스 켜는 방법
세션에서 /sandbox를 실행하세요. 세 개의 탭이 있는 패널이 열립니다:
- Mode: 자동 허용(auto-allow) 또는 일반 권한(regular permissions) 중 선택합니다.
- Overrides: 샌드박스에서 실패한 명령을 샌드박스 없이 실행(fallback)할지 여부를 선택합니다.
- Config: 확인된 샌드박스 설정을 보여줍니다.
Linux에서는 누락된 항목이 있을 때 Dependencies 탭이 나타납니다. 이 탭만 보인다면 아직 샌드박스를 시작할 수 없는 상태입니다.
설정이 저장되는 위치가 중요합니다. 패널에서 모드를 선택하면 Claude Code는 이를 .claude/settings.local.json에 저장하므로 현재 프로젝트에만 적용됩니다. 모든 프로젝트에 샌드박스를 적용하려면 사용자 설정 파일인 ~/.claude/settings.json에서 sandbox.enabled를 true로 설정하세요.
확인해야 할 기본값이 하나 더 있습니다. 문서에서는 다음과 같이 경고합니다: "기본적으로 플랫폼이 샌드박스를 지원하지 않거나 시작 시 종속성 확인에 실패하면, Claude Code는 샌드박스 없이 명령을 실행합니다." 샌드박스를 보안 게이트로 사용한다면 sandbox.failIfUnavailable을 true로 설정하여 Claude Code가 시작 시 종료되도록 하세요.
작동 여부를 확인하려면, Claude에게 홈 디렉토리에 프로브 파일을 생성하는 것과 같이 홈 디렉토리에 쓰는 명령을 실행해 보라고 요청하는 것이 좋습니다. 샌드박스 내부에서는 macOS의 경우 operation-not-permitted 오류가, Linux의 경우 read-only file system 오류가 발생하며 실패합니다. 직접 쉘 프롬프트에 명령어를 입력하는 것은 테스트가 되지 않는데, 사용자가 직접 입력한 명령어는 보통 샌드박스 외부에서 실행되기 때문입니다.
기본적으로 제한되는 항목
문서에는 기본값 표가 제공됩니다. 요약하자면:
쓰기(Writes). 샌드박스 처리된 명령어는 작업 디렉토리, 사용자별 임시 디렉토리, 그리고 --add-dir 또는 /add-dir로 추가한 디렉토리에 쓸 수 있습니다. 보호된 경로는 계속 거부됩니다.
읽기(Reads). SSH 키나 AWS 자격 증명과 같은 자격 증명 파일을 포함하여 머신의 대부분을 읽을 수 있습니다. filesystem.denyRead 또는 자격 증명 설정을 사용하여 읽기 범위를 직접 좁혀야 합니다.
네트워크(Network). "직접적인 외부 경로가 없습니다. 연결은 머신의 프록시를 통해 이루어지며, 프록시는 허용된 도메인 목록(처음에는 비어 있음)과 대조하여 각 호스트를 확인합니다." 명령어가 새로운 도메인을 처음 필요로 할 때 Claude Code가 승인을 요청합니다.
환경 변수(Environment variables). 명령은 사용자가 제거하거나 마스킹하지 않는 한 "환경 내의 모든 비밀 정보(secrets)를 포함하여" Claude Code의 환경을 상속합니다.
샌드박스가 모든 것을 숨겨줄 것이라고 기대했다면 두 번째 포인트가 중요합니다. 읽기 권한은 기본적으로 광범위합니다. 샌드박스의 기본 역할은 프로젝트 외부로의 쓰기와 허용되지 않은 호스트로의 네트워크 트래픽을 차단하는 것입니다.
보호된 경로
샌드박스 처리된 명령이 쓸 수 있는 폴더 내에서도 일부 경로는 쓰기가 거부된 상태로 유지됩니다. 문서에서는 이를 네 가지 그룹으로 나열합니다:
- 작업 디렉토리 및 그 상위 디렉토리:
.claude설정 파일,.claude/skills,.claude/agents,.claude/commands,.claude/hooks디렉토리,.mcp.json, 그리고.claude/workflows및.claude/scheduled_tasks.json과 같이 Claude Code가 자체적으로 실행하는 파일들. - 작업 디렉토리 내에서만:
.bashrc및.zshrc와 같은 쉘 시작 파일,.gitconfig,.vscode및.idea디렉토리, 그리고.git내부의hooks및config항목들. - 작업 디렉토리를 bare git 저장소로 바꿀 수 있는 파일들: 최상위 수준의
HEAD,objects,refs및 관련 항목들. ~/.claude또는CLAUDE_CONFIG_DIR이 가리키는 폴더: 대부분의 내용물,~/.claude.json및 자격 증명 저장소.
공통점은 Claude Code가 읽는 설정과 실행하는 코드라는 점입니다. skill은 Claude가 따르는 지침입니다. hook은 Claude Code가 실행하는 스크립트입니다. 설정은 권한을 결정합니다. 만약 샌드박스 처리된 명령이 이것들 중 하나라도 다시 쓸 수 있다면, 다음 세션은 해당 명령이 작성한 내용으로 시작될 것입니다.
실수로 이 제한을 풀 수는 없습니다. 문서에 따르면 이러한 경로 중 하나를 포함하는 쓰기 허용 또는 편집 허용 규칙을 추가하더라도 "보호는 여전히 적용됩니다." 이를 해제하는 유일한 방법은 파일 시스템 격리(filesystem isolation)를 완전히 끄는 것인데, 이는 파일 시스템 레이어의 나머지 부분도 제거합니다.
사용자 머신에 적용된 경로를 확인하려면 /sandbox를 실행하고 Config 탭을 여세요. 거부된 항목(denied-within-allowed) 목록에서 확인할 수 있습니다.
이것은 서두의 예시를 설명해 줍니다. 샌드박스의 차단은 샌드박스 처리된 쉘 명령어에 적용됩니다. Claude의 내장 Edit 도구는 샌드박스가 아닌 권한 규칙(permission rules)을 따르며, 권한 시스템은 자체적인 보호 경로 목록을 유지하므로 해당 도구를 통한 편집은 거기서 결정됩니다.
이러한 경로를 업데이트할 수 없어 git 체크아웃이나 병합이 실패하는 경우를 위해 문서에는 문제 해결 항목이 있으며, 최근 Claude Code 릴리스에는 샌드박스 처리된 git 명령이 보호된 파일을 업데이트할 수 없을 때 Claude에게 이를 알리는 메모가 추가되었습니다.
샌드박스 외부에서 실행되는 항목
문서는 범위에 대해 정확하게 명시합니다: "샌드박스는 쉘 명령어를 감쌉니다." 다음은 Claude가 실행하는 쉘 명령어가 아닙니다:
- 내장 파일 및 웹 도구. Read, Edit, Write, WebFetch, WebSearch는 대신 권한 규칙을 따릅니다. 샌드박스의 읽기 거부 항목은 Read 도구를 막지 못하며, 허용 도메인 목록은 WebFetch를 제한하지 않습니다.
- Claude Code가 시작하는 기타 프로세스. 명령 hook, 로컬 MCP 서버, 플러그인 모니터, LSP 서버는 샌드박스 외부에서 실행됩니다.
- Mods, Claude Code 내부에서 자체 코드를 실행합니다.
일부 쉘 명령어도 외부에서 실행됩니다:
- 사용자가 직접 입력하는 명령어 (
!쉘 프롬프트에서 입력, 대부분의 세션). - 제외된 명령어(Excluded commands),
excludedCommands항목과 일치하는 경우. - 샌드박스 해제 후 재시도, 아래에서 다룹니다.
이 모든 것을 하나의 경계 안에 두고 싶다면 문서에서는 다른 도구를 제안합니다: Claude Code 프로세스 자체를 컨테이너, 가상 머신 또는 샌드박스 런타임에서 실행하세요.
자동 허용(Auto-allow) 대 일반 권한(Regular permissions)
두 모드 모두 동일한 파일 시스템 및 네트워크 제한을 적용합니다. 차이점은 승인 방식입니다.
자동 허용(Auto-allow)은 샌드박스 내부에서 실행될 때 프롬프트 없이 명령을 승인합니다. 하지만 여전히 프롬프트가 뜨는 경우가 있습니다: Bash 거부 규칙에 일치하는 명령, 중요한 경로를 대상으로 하는 rm, 그리고 git push 규칙과 같이 특정 콘텐츠로 범위가 지정된 ask 규칙 등입니다. 테스트 실행 전 환경 변수를 설정하는 것과 같이 프로그램 앞에 변수를 설정하는 명령도 일반적인 흐름을 거칩니다. 변수가 실행되는 프로그램을 바꿀 수 있기 때문입니다.
일반 권한(Regular permissions)은 샌드박스 여부와 관계없이 모든 Bash 명령을 일반적인 권한 흐름으로 보냅니다. 문서에서는 이를 더 많은 승인이 필요하지만 더 세밀한 제어가 가능한 방식이라고 설명합니다.
Claude가 샌드박스 해제 후 재시도를 요청하는 경우
문서에서는 이 재시도를 탈출구(escape hatch)라고 부릅니다: "샌드박스 해제 후 재시도는 샌드박스와 호환되지 않는 도구와 같이 샌드박스 내부에서 실패하는 명령을 위한 탈출구입니다."
샌드박스가 네트워크 연결을 차단하면 Claude Code는 명령 결과에 거부된 호스트 이름을 명시하여 Claude가 무엇이 실패했는지 알 수 있게 합니다. 그러면 Claude는 해당 명령 하나에 대해서만 샌드박스를 비활성화하는 매개변수를 사용하여 재시도할 수 있습니다. 재시도 승인 여부는 권한 모드에 따라 다릅니다:
- Manual 및 accept-edits 모드에서는 'Bash command (unsandboxed)'라는 제목의 프롬프트가 표시됩니다.
- auto 모드에서는 분류 모델이 명령을 평가합니다.
- bypass-permissions 모드에서는 프롬프트 없이 실행됩니다.
- don't-ask 모드에서는 거부됩니다.
두 가지 설정이 이를 변경합니다. 명령과 일치하는 허용 규칙은 재시도도 승인합니다. 그리고 disable-sandbox 매개변수에 대한 ask 규칙은 auto 및 bypass 모드에서도 프롬프트를 강제합니다.
이 탈출구를 제거하려면 allowUnsandboxedCommands를 false로 설정하세요. 문서에서는 이를 엄격한 샌드박스(strict sandbox) 모드라고 부릅니다. 이 경우 Claude가 실행하는 명령은 제외된 명령과 일치하지 않는 한 샌드박스 상태를 유지합니다. 사용자나 관리자가 관리형 설정이나 --settings로 이를 설정하면 샌드박스는 관리자 필수 사항이 되며, Claude Code는 이를 완화하려는 저장소 설정을 무시합니다.
자격 증명 보호
읽기 권한이 기본적으로 광범위하기 때문에 자격 증명에는 명시적인 규칙이 필요합니다. 문서에서는 자동으로 차단되는 것이 없음을 명확히 합니다: "내장된 자격 증명 거부 목록이 없으므로, 사용자가 나열한 파일과 변수만 제한됩니다."
sandbox.credentials 설정은 파일 경로와 환경 변수 이름을 받으며, 각각 다음 모드를 가집니다:
- Deny: 파일 읽기를 차단하고 각 샌드박스 명령 실행 전에 변수 설정을 해제합니다.
- Mask: 명령어에는 플레이스홀더를 보여주고, 샌드박스 프록시는 사용자가 허용한 호스트에 대한 요청에만 실제 값을 대체하여 넣습니다.
모든 설정 범위(scope)의 Deny 항목은 병합되며, 어떤 범위도 다른 범위가 추가한 항목을 제거할 수 없습니다. 마스킹은 프록시에서의 TLS 종료를 포함하여 더 많은 설정이 필요하며, 사용자 설정, 관리형 설정 또는 --settings에서만 허용됩니다.
프로젝트가 변경할 수 없는 설정
일부 샌드박스 설정은 특정 위치에서만 신뢰됩니다. 가장 명확한 예는 파일 시스템 격리를 끄는 것입니다. 문서에서는 그 위험성을 설명합니다. 이 기능이 꺼져 있고 명령이 자동 허용되면, 샌드박스 처리된 명령이 나중에 다른 명령이 읽게 될 파일(예: ~/.claude/settings.json)을 작성할 수 있고, "이를 사용하여 다음 실행 시 자신의 액세스 권한을 넓힐 수 있습니다."
따라서 .claude/settings.json 및 .claude/settings.local.json의 프로젝트 설정으로는 이를 설정할 수 없습니다. 사용자 설정, 관리형 설정 및 --settings만 가능합니다. 재시도를 비활성화한 경우, 프로젝트 설정에서 true라고 하더라도 사용자 설정의 false가 우선합니다.
우리는 Codex 권한 프로필 가이드에서 Codex가 쓰기 가능한 작업 공간 내에서 자체 설정 폴더를 읽기 전용으로 유지하며 유사한 경계를 긋는 방식을 다룬 바 있습니다.
사람들이 흔히 하는 실수
샌드박스가 켜져 있을 것이라고 예상함. 기본적으로 꺼져 있습니다.
자격 증명을 숨겨줄 것이라고 예상함. 자격 증명 규칙을 추가하기 전까지 읽기 권한은 광범위합니다.
.claude에 대한 허용 규칙 추가. 보호된 경로는 계속 보호됩니다.
hook과 MCP 서버까지 포함될 것이라고 예상함. 그것들은 외부에서 실행됩니다.
시작 실패 시 Claude Code가 중단될 것이라고 가정함. failIfUnavailable 설정이 없으면 명령은 샌드박스 없이 실행됩니다.
해결책: 의도적으로 샌드박스 구성하기
1단계: 원하는 곳에서 활성화하기
한 프로젝트에는 /sandbox를 사용하고, 모든 프로젝트에는 사용자 설정을 사용하세요.
2단계: 자격 증명 규칙 추가하기
명령어가 보지 말아야 할 파일과 변수를 거부(Deny)하거나 마스킹(Mask)하세요.
3단계: 탈출구 결정하기
프롬프트가 있는 샌드박스 해제 재시도를 유지하거나, 엄격 모드로 완전히 끄세요.
4단계: 각 설정의 이유 기록하기
허용한 도메인, 폴더, 제외 사항과 각각의 이유를 기록해 두세요.
MemoryLake에서 설정하기
샌드박스 설정은 설정 파일의 짧은 줄에 불과합니다. 도메인이 허용된 이유, 어떤 도구에 제외가 필요했는지, 또는 왜 특정 저장소에서 재시도가 꺼져 있는지와 같은 근거는 설정 파일이 설명해주지 못하는 프로젝트 컨텍스트(context)입니다. 몇 달 후 누군가 해당 규칙이 여전히 필요한지 물을 때, 그 근거가 도움이 됩니다.
MemoryLake는 보안 결정, 허용된 예외 사항 및 그 근거와 같은 프로젝트 컨텍스트를 위한 메모리 레이어입니다. 사용자가 관리하는 한 곳에 보관되며 ChatGPT, Claude Code, Codex 등 연결된 어시스턴트가 활용할 수 있습니다.
항목은 사용자가 직접 자신의 언어로 작성합니다. Claude Code 설정, .claude 폴더, 샌드박스 구성, 세션 또는 공급업체의 저장소에서 아무것도 읽거나 쓰거나 삭제하지 않습니다. 샌드박스는 Anthropic이 설명한 방식 그대로 작동합니다.
1단계: API 키 생성
로그인 후 대시보드에서 키를 생성하세요. 다른 자격 증명과 마찬가지로 저장소 외부에 보관하세요.

2단계: 첫 번째 메모리 업로드
해결책 4단계에서 작성한 내용부터 시작하세요: 각 샌드박스 예외 사항과 그 이유입니다. 한 항목당 하나의 예외를 작성합니다.

3단계: AI 및 에이전트 연결
Claude Code, Codex 및 사용하는 다른 어시스턴트를 연결하세요. 각 어시스턴트는 제안된 예외 사항을 이미 기록된 근거와 대조하여 확인할 수 있습니다.

실제적인 변화
첫 번째 차이점은 검토가 쉬워진다는 것입니다. 예외 사항이 추가된 이유와 함께 제공됩니다.
두 번째는 광범위한 규칙이 줄어든다는 것입니다. 원래의 필요성이 명확하면 좁은 경로 나 도메인을 선택하기가 더 쉽습니다.
세 번째는 도구 간의 일관성입니다. 동일한 보안 결정 사항을 Claude Code와 Codex 모두에서 사용할 수 있습니다.
Claude Code Sandbox 모범 사례
샌드박스에 의존한다면 failIfUnavailable을 설정하세요. 그렇지 않으면 시작 실패 시 명령이 샌드박스 없이 실행됩니다.
제외(Exclusions)보다는 좁은 쓰기 경로를 선호하세요. 제외된 명령어는 사용자의 전체 권한으로 실행됩니다.
자격 증명을 명시적으로 나열하세요. 기본적으로 거부되는 자격 증명은 없습니다.
보호된 경로는 그대로 두세요. 이 경로들은 Claude Code가 다음에 로드할 항목들을 보호합니다.
완전한 격리를 위해 컨테이너를 사용하세요. hook, MCP 서버 및 내장 도구는 샌드박스 외부에 있습니다.
프로브 명령으로 테스트하세요. 직접 입력하지 말고 Claude에게 실행해 보라고 요청하세요.
결론
Claude Code sandbox는 Claude가 실행하는 쉘 명령어와 그 명령어가 시작하는 프로세스를 감쌉니다. 기본적으로 꺼져 있습니다. 활성화되면 명령어는 작업 디렉토리, 임시 디렉토리 및 추가된 디렉토리에 쓸 수 있고, 읽기 권한은 광범위하게 유지되며, 네트워크 트래픽은 승인된 호스트만 허용하는 프록시를 통과합니다.
쓰기 가능한 폴더 내에서도 .claude 설정, skills, agents, commands, hooks 및 ~/.claude 대부분을 포함한 보호된 경로는 쓰기가 거부되므로, 명령어가 다음 세션이 로드할 구성을 다시 쓸 수 없습니다. 내장 도구, hook 및 MCP 서버는 샌드박스 외부에서 실행되며, 실패한 명령은 엄격 모드로 끄지 않는 한 샌드박스 없이 재시도될 수 있습니다.