Cmd. /sandbox
샌드박스 모드를 토글하고 파일 시스템·네트워크 격리 경계를 점검하는 명령
핵심 요약
/sandbox는 Mode·Overrides·Config 세 탭으로 구성된 샌드박스 패널을 여는 토글 명령입니다(지원 플랫폼 한정).- 샌드박스는 OS 수준(macOS Seatbelt, Linux/WSL2
bubblewrap)에서 Bash 명령의 파일 시스템·네트워크 접근을 제한합니다. - auto-allow 모드로 빌드·테스트를 권한 프롬프트 없이 돌리면서도 OS 경계가 안전을 지켜 줍니다.
- 네이티브 Windows는 미지원이며 WSL2 안에서 실행해야 하고, Dependencies 탭만 보이면
bubblewrap·socat을 설치하세요. - 기본 read 정책은
~/.ssh/·AWS 자격 증명까지 읽을 수 있으니 필요하면sandbox.filesystem.denyRead로 차단하세요.
명령어 원본 선언
/sandbox공식 설명 요약
공식 문서의 한 줄 설명은 다음과 같습니다.
Toggle sandbox mode. Available on supported platforms only. (샌드박스 모드를 토글합니다. 지원되는 플랫폼에서만 사용할 수 있습니다.)
/sandbox는 단순히 설정을 조회하는 명령이 아니라 샌드박스 패널을 여는 토글 명령입니다. 실행하면 세 개의 탭이 있는 패널이 나타납니다.
- Mode: 샌드박스된 Bash 명령을 어떻게 승인할지 선택 (auto-allow / regular permissions)
- Overrides: 샌드박스에서 실패한 명령을 비격리 상태로 폴백 실행할지 선택 (
allowUnsandboxedCommands설정) - Config: 최종 적용된 샌드박스 설정 확인
샌드박스는 OS 수준에서 Bash 명령과 그 하위 프로세스의 파일 시스템·네트워크 접근을 제한합니다. macOS는 내장 Seatbelt를, Linux와 WSL2는 bubblewrap을 씁니다. 명령마다 권한을 묻는 대신, 접근 가능한 경로와 도메인을 미리 정해 두면 OS가 그 경계를 대신 지킵니다.
Mode 탭에서 모드를 선택하면 프로젝트 로컬 설정(.claude/settings.local.json)에 기록됩니다. 모든 프로젝트에 적용하려면 사용자 설정(~/.claude/settings.json)의 sandbox.enabled를 true로 둡니다.
최소 지원 버전
- Changelog에 별도의 도입 버전이 명시되지 않은 내장 명령입니다. 공식 문서 명령 표에도
/sandbox에 대한min-version주석이 없습니다. 정확한 도입 버전이 확인되지 않아 임의로 버전을 적지 않습니다.
사용법
/sandbox- 인자나 별칭(alias)은 없습니다. 단독으로 실행해 패널을 토글합니다.
- 패널에 Dependencies 탭만 보인다면 필수 패키지가 빠져 있습니다. Linux/WSL2에서는
bubblewrap과socat을 설치한 뒤 Claude Code를 재시작하고 다시 실행하세요.
좋은 사용 예
- 자율 실행을 늘리기 위해 auto-allow 모드를 켜고 빌드·테스트를 권한 프롬프트 없이 실행
- 명령 실행 실패 원인이 샌드박스 경계(허용되지 않은 도메인/경로)인지 Config 탭으로 확인
- 보안 감사 대응을 위해 적용된 샌드박스 정책과 폴백 동작(Overrides) 점검
비슷한 명령어 추천
| 명령어 | 차이점 | 언제 선택 |
|---|---|---|
/sandbox | OS 수준 실행 격리 경계 토글 | Bash 격리 범위를 켜고 조정할 때 |
/permissions | 도구 실행 승인 규칙 변경 | 사용자 승인 흐름을 제어할 때 |
/doctor | 설치·환경 문제 진단 | 원인 분석이 필요할 때 |
/sandbox는 권한 모드(permission mode)가 아닙니다. 권한 모드는 도구 호출이 실행될지·프롬프트가 뜰지를 결정하고, 샌드박스는 실행된 Bash 명령이 무엇에 접근할 수 있는지를 제한합니다.
활용 사례
- CI/자율 실행 환경에서 auto-allow 모드로 권한 프롬프트를 줄이면서도 OS 경계로 안전을 유지
- 팀 보안 가드레일 표준화: managed settings로
sandbox.enabled,failIfUnavailable,allowUnsandboxedCommands를 조직 전체에 강제 - 넓은
sandbox.network.allowedDomains아래에서 특정 목적지 도메인만 차단하기 위해sandbox.network.deniedDomains설정 점검 kubectl·terraform·npm처럼 작업 디렉터리 밖에 써야 하는 도구를 위해sandbox.filesystem.allowWrite로 경로 허용
주의사항
- 샌드박스 우회 시도 대신 공식 설정(
allowWrite,allowedDomains,excludedCommands)으로 경계를 넓히세요. - 기본 read 정책은
~/.aws/credentials,~/.ssh/같은 자격 증명 파일까지 읽을 수 있게 두므로, 필요하면sandbox.filesystem.denyRead로 차단하세요. github.com같은 넓은 도메인 허용은 데이터 유출 경로가 될 수 있습니다. 내장 프록시는 TLS를 검사하지 않으므로 도메인 프론팅 등에 주의하세요.- 네이티브 Windows는 지원되지 않습니다. Windows에서는 WSL2 안에서 Claude Code를 실행해야 합니다(WSL1 미지원).
- 의존성이 없거나 플랫폼이 미지원이면 기본적으로 경고를 띄운 뒤 비격리 실행으로 폴백합니다. 이때 아예 실패로 처리하려면
sandbox.failIfUnavailable을true로 설정하세요.
출처
- Commands: https://code.claude.com/docs/en/commands
- Sandboxing: https://code.claude.com/docs/en/sandboxing