Cmd. /sandbox
샌드박스 모드를 토글하고 파일 시스템·네트워크 격리 경계를 점검하는 명령
핵심 요약
- 지원 플랫폼의 sandbox mode 전환
- 입력 위치·지원 조건을 확인한 뒤 아래 실행 예를 사용합니다.
역할
지원 플랫폼의 sandbox mode 전환
/sandbox사용 조건
| 항목 | 기준 |
|---|---|
| 입력 위치 | 실행 중인 CLI의 입력창 |
| 종류 | 내장 명령 |
| 상태 | 조건부 |
| 별칭 | — |
| 공식 최소 버전 | 명시되지 않음 |
| 검증 기준 | 2026-09-22 · Claude Code 2.1.278 |
macOS와 Linux·WSL2에서 지원합니다. native Windows에서는 사용할 수 없으며 Linux·WSL2에서는 bubblewrap·socat 의존성을 확인합니다.
사용 예
/sandbox세션 시작부터 제한 프로필이 필요하면 CLI에서 claude --restricted를 사용합니다. 이는 /sandbox 패널의
단순 별칭이 아니므로 조직 정책과 managed settings 적용 결과를 /doctor·/status에서 함께 확인하세요.
- 인자나 별칭(alias)은 없습니다. 단독으로 실행해 패널을 토글합니다.
- 패널에 Dependencies 탭만 보인다면 필수 패키지가 빠져 있습니다. Linux/WSL2에서는
bubblewrap과socat을 설치한 뒤 Claude Code를 재시작하고 다시 실행하세요.
선택 시점
- 자율 실행을 늘리기 위해 auto-allow 모드를 켜고 빌드·테스트를 권한 프롬프트 없이 실행
- 명령 실행 실패 원인이 샌드박스 경계(허용되지 않은 도메인/경로)인지 Config 탭으로 확인
- 보안 감사 대응을 위해 적용된 샌드박스 정책과 폴백 동작(Overrides) 점검
관련 명령 선택
| 명령어 | 차이점 | 언제 선택 |
|---|---|---|
/sandbox | OS 수준 실행 격리 경계 토글 | Bash 격리 범위를 켜고 조정할 때 |
/permissions | 도구 실행 승인 규칙 변경 | 사용자 승인 흐름을 제어할 때 |
/doctor | 설치·환경 문제 진단 | 원인 분석이 필요할 때 |
/sandbox는 권한 모드(permission mode)가 아닙니다. 권한 모드는 도구 호출이 실행될지·프롬프트가 뜰지를 결정하고, 샌드박스는 실행된 Bash 명령이 무엇에 접근할 수 있는지를 제한합니다.
실행 결과와 유지 범위
지원 플랫폼에서 도구 실행을 제한하는 샌드박스 모드를 변경합니다.
공식 문서의 한 줄 설명은 다음과 같습니다.
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로 둡니다.
주의사항
v2.1.248+에서는 claude --restricted 또는 CLAUDE_CODE_RESTRICTED=1로 제한된 실행 프로필을 시작할 수 있습니다.
- 샌드박스 우회 시도 대신 공식 설정(
allowWrite,allowedDomains,excludedCommands)으로 경계를 넓히세요. - 기본 read 정책은
~/.aws/credentials,~/.ssh/같은 자격 증명 파일까지 읽을 수 있게 두므로, 필요하면sandbox.filesystem.denyRead로 차단하세요. github.com같은 넓은 도메인 허용은 데이터 유출 경로가 될 수 있습니다. 내장 프록시는 TLS를 검사하지 않으므로 도메인 프론팅 등에 주의하세요.- 네이티브 Windows는 지원되지 않습니다. Windows에서는 WSL2 안에서 Claude Code를 실행해야 합니다(WSL1 미지원).
- 의존성이 없거나 플랫폼이 미지원이면 기본적으로 경고를 띄운 뒤 비격리 실행으로 폴백합니다. 이때 아예 실패로 처리하려면
sandbox.failIfUnavailable을true로 설정하세요.
공식 근거
전체 명령 목록 · 검증 범위 · 이 명령의 변경 기록