Claude Code의 Bash sandbox는 셸 명령과 자식 프로세스가 접근할 파일 경로와 네트워크 도메인을 운영체제 수준에서 제한하는 기능입니다. Claude Code 세션에서 /sandbox 를 열면 모드, 샌드박스 밖 재시도 허용 여부, 최종 설정과 Linux·WSL2 의존성을 확인할 수 있습니다.

처음에는 regular permissions로 두고 allowUnsandboxedCommands 를 끈 Strict sandbox mode에서 비민감 fixture를 시험하는 편이 안전합니다. 프로젝트 안의 정상 쓰기는 통과하고 프로젝트 밖 쓰기와 새 도메인 접근은 차단되거나 승인 흐름으로 들어가는지 각각 확인한 뒤, 필요한 예외만 좁게 검토합니다.

Claude Code Bash sandbox의 한 문장 정의, 지원 플랫폼과 의존성, /sandbox 의 네 가지 확인 지점, 파일시스템·네트워크 격리의 차이, 정상·차단 양쪽 검증, 복사용 점검 프롬프트, 샌드박스 밖 재시도와 예외 설정의 주의점을 다룹니다.

Claude Code는 Bash에서 테스트, 빌드, 패키지 관리, Git 명령을 실행할 수 있습니다. 승인 창만 보고 명령을 허용하면 자식 프로세스가 실제로 어느 파일과 도메인에 접근하는지까지 판단하기 어렵습니다.

Claude Code Bash sandbox는 명령 문자열을 검토하는 permission과 별도로, 실행 중인 Bash 명령과 자식 프로세스의 파일시스템·네트워크 경계를 운영체제가 집행하게 합니다. 반복되는 테스트와 빌드는 자동화하되 작업 폴더 밖의 파일이나 불필요한 외부 도메인으로 영향 범위가 넓어지는 것을 막고 싶을 때 맞습니다.

이 기능은 Claude Code 전체를 가상 머신에 넣는 기능이 아닙니다. 공식 문서는 sandboxed Bash tool을 대상으로 설명하며 permission rules와 permission modes도 별도로 적용됩니다. 따라서 샌드박스를 켰다는 이유로 승인 규칙, 비밀 파일 보호, diff 검수와 백업을 생략하면 안 됩니다.

아래 프롬프트는 Claude Code에서 /sandbox 설정을 사람이 확인한 뒤, 비민감 시험 폴더에서만 사용합니다. 차단 시험이 승인 요청으로 바뀌면 승인하지 말고 멈추도록 했습니다.

목표: 현재 Claude Code 세션의 Bash sandbox가 프로젝트 내부 정상 작업은 허용하고 프로젝트 밖 파일 쓰기와 새 네트워크 도메인 접근은 차단하거나 승인 흐름으로 보내는지 검증한다.
허용 입력: 현재 비민감 시험 저장소의 파일 목록, git status, /sandbox 패널에서 사람이 확인한 Mode·Overrides·Config 정보, example.com hostname만 사용한다.
제외 입력: 실제 저장소 원본, 고객 데이터, 개인정보, 자격증명, 환경 변수 값, 내부 URL, 배포 키, 패키지 설치, 외부 업로드, 운영 시스템 변경, 홈 폴더의 기존 파일 수정·삭제.
출력 형식: 1) 실행 전 계획, 2) 프로젝트 내부 허용 시험 결과, 3) 프로젝트 밖 쓰기 시험의 차단 또는 승인 결과, 4) 새 도메인 접근의 차단 또는 승인 결과, 5) 예상 밖 생성 파일, 6) 최소 예외 후보, 7) 사람 승인 필요 항목 순서로 표가 아닌 짧은 목록을 작성한다.
완료 기준: sandbox-check.txt만 프로젝트 안에 생성되고 git status로 확인된다. 프로젝트 밖 쓰기와 새 도메인 접근은 실행되지 않거나 승인 단계에서 멈춘다. 결과에는 실제로 관찰한 메시지와 경로만 적는다.
추정 금지: sandbox 활성 상태, 지원 플랫폼, 설정값, 차단 이유를 추정하지 않는다. /sandbox Config와 실제 실행 결과에 없는 사실을 만들지 않는다.
승인 지점: 프로젝트 밖 실행, 도메인 허용, allowWrite·excludedCommands 변경, allowUnsandboxedCommands 재활성화, 생성 파일 삭제는 모두 제안만 하고 사람이 승인하기 전에는 실행하지 않는다.

허용 시험과 차단 시험을 한 세트로 남기면 sandbox가 느슨한지뿐 아니라 정상 업무를 가로막는지도 함께 볼 수 있습니다. 차단 로그만 모으면 빌드나 테스트가 조용히 깨진 상태를 놓칠 수 있습니다. 반대로 정상 실행만 보면 홈 폴더나 네트워크 경계가 열린 상태를 지나칠 수 있습니다.

예외 검토 메모에는 작업 목적, 요청 경로 또는 hostname, 적용 scope, 승인자, 만료 또는 재검토 시점, 원상복구 조건을 남깁니다. 편의를 위해 넓힌 예외가 계속 남지 않도록 작업이 끝난 뒤 /sandbox Config를 다시 확인합니다.

• sandbox는 Bash 명령과 자식 프로세스의 경계를 집행하지만 permission rules, permission modes, 비밀 파일 보호와 코드 검수를 대신하지 않습니다.
• auto-allow에서는 sandboxed Bash 명령이 prompt 없이 실행될 수 있습니다. 경계를 검증하기 전에는 regular permissions로 시작합니다.
• allowUnsandboxedCommands 가 켜져 있으면 sandbox 실패 뒤 regular permission flow를 거쳐 밖에서 재시도할 수 있습니다.
• excludedCommands 는 해당 명령을 sandbox 밖에서 실행하므로 오류 해결용 편의 목록처럼 늘리지 않습니다.
• sandbox.filesystem.disabled 는 filesystem isolation을 끄고 network isolation만 유지합니다. 두 격리 층을 같은 설정으로 오해하지 않습니다.
• /var/run/docker.sock 같은 강한 Unix socket을 허용하면 host 접근으로 이어질 수 있습니다.
• 지나치게 넓은 쓰기 경로, 실행 파일 경로, shell 설정 파일 쓰기는 다른 보안 맥락의 코드 실행으로 이어질 수 있습니다.
• 기본 네트워크 proxy는 client가 제공한 hostname으로 허용 여부를 판단하고 기본적으로 TLS를 검사하지 않습니다. 더 강한 보장이 필요한 조직은 공식 문서의 custom proxy 경계를 별도로 검토합니다.
• Linux·WSL2에서 dependency가 없거나 플랫폼이 지원되지 않으면 기본 동작이 unsandboxed fallback일 수 있으므로 경고와 Config를 확인합니다.

`/sandbox`는 터미널 셸에서 실행하나요?

아닙니다. Claude Code 세션의 대화형 입력창에서 실행하는 slash command입니다. 셸에 독립 명령처럼 입력하지 않습니다.

auto-allow를 켜면 모든 명령이 자동 승인되나요?

아닙니다. 공식 문서는 sandbox 안에서 실행되는 Bash 명령을 자동 허용하는 모드로 설명합니다. sandbox에 들어가지 못하거나 허용되지 않은 네트워크가 필요한 명령은 regular permission flow로 넘어갈 수 있습니다. 먼저 regular permissions와 Strict sandbox mode로 경계를 시험하세요.

sandbox를 켜면 `.env`와 SSH 키도 자동으로 안전한가요?

그렇게 단정하면 안 됩니다. filesystem settings, credential settings, Read·Edit deny rules는 서로 역할이 다릅니다. 현재 Config와 permission rules를 함께 확인하고 실제 비밀값 대신 비민감 fixture로 차단을 검증해야 합니다.

조직 전체에 같은 설정을 강제하려면 프로젝트 설정만 배포하면 되나요?

아닙니다. 프로젝트의 .claude/settings.local.json 은 현재 프로젝트의 로컬 설정이며 Git에 체크인되지 않습니다. 조직 강제는 managed settings에서 enabled , failIfUnavailable , allowUnsandboxedCommands 같은 항목을 별도로 검토하고 정상 작업과 차단 작업을 대표 사용자로 양쪽 검증해야 합니다.

• Anthropic 공식 문서: Configure sandboxing
• Anthropic 공식 문서: Claude Code settings