Claude Code 샌드박스 설정: WSL2에서 파일·네트워크 접근 제한하기

먼저 구분할 용어

용어이 글에서의 의미

WSL2	Windows에서 Linux 환경을 실행하는 기능
샌드박스	셸 명령과 자식 프로세스의 파일·네트워크 접근을 제한하는 경계
권한 규칙	Claude Code 도구의 실행 허용·승인·거부를 정하는 규칙
허용 목록	접속을 허용할 호스트 목록

프로젝트 수정은 맡기면서 개인 파일과 외부 접속을 제한하려면 셸 샌드박스와 파일 도구 권한을 함께 설정해야 합니다. 기준일은 2026-10-10이며, 아래 코드는 공식 문서 기반 예시입니다. 이 글을 위해 WSL2 설치나 차단 실험을 실행하지 않았습니다.

1. WSL2와 의존성 확인

Claude Code 내장 샌드박스는 WSL2를 지원합니다. 네이티브 Windows와 WSL1은 지원 대상이 아닙니다(Anthropic, Sandboxing 문서).

Windows PowerShell에서 wsl -l -v로 배포판의 VERSION이 2인지 확인합니다. Ubuntu·Debian 계열 WSL 안에서는 다음 의존성을 설치합니다.

sudo apt-get install bubblewrap socat

WSL의 Linux용 Claude Code를 다시 시작하고 /sandbox에서 의존성과 활성화 상태를 확인합니다. 실패하면 공식 문서의 AppArmor 조건 등을 점검하세요.

2. 사용자 설정에 파일·접속 제한 넣기

아래 예시는 WSL의 ~/.claude/settings.json에 적용할 내용입니다. 기존 파일 전체를 덮어쓰지 말고 해당 항목을 병합하세요. 이 위치의 설정은 여러 프로젝트에 영향을 줍니다.

USER와 project는 실제 사용자명과 폴더명으로 바꿉니다. .env는 민감 파일 예시입니다.

{
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "allowUnsandboxedCommands": false,
    "filesystem": {
      "denyRead": ["~/.ssh", "/home/USER/project/.env", "/mnt/c"],
      "denyWrite": ["/home/USER/project/.env", "/mnt/c"]
    },
    "network": {
      "allowedDomains": ["registry.npmjs.org"],
      "strictAllowlist": true
    }
  },
  "permissions": {
    "deny": [
      "Read(~/.ssh/**)",
      "Read(//home/USER/project/.env)",
      "Read(//mnt/c/**)",
      "Edit(//home/USER/project/.env)",
      "Edit(//mnt/c/**)"
    ]
  }
}

이 예시는 프로젝트가 /home/USER/project에 있다고 가정합니다. /mnt/c 아래 프로젝트에는 맞지 않습니다. Microsoft의 WSL 파일시스템 문서에 따르면 C 드라이브는 보통 /mnt/c로 보이며, 다른 드라이브나 사용자 지정 마운트도 별도로 점검해야 합니다.

파일 제한은 읽기와 쓰기를 나눕니다

denyRead는 읽기, denyWrite는 쓰기를 막습니다. 기본 읽기 범위는 넓으므로 프로젝트 밖 파일이 모두 숨겨진다고 생각하면 안 됩니다. 쓰기는 작업 디렉터리·추가 허용 디렉터리·사용자 임시 디렉터리 등이 기본 허용 범위입니다.

permissions.deny는 내장 파일 도구 접근도 제한하려고 함께 넣었습니다. 권한 규칙의 절대 경로는 //mnt/c/..., 샌드박스 경로는 /mnt/c/...처럼 표기가 다릅니다(Anthropic, Configure permissions).

네트워크 목록은 실제 적용값을 확인합니다

strictAllowlist: true는 목록 밖 호스트를 거부하도록 설정합니다. 프로젝트 설정 파일에서는 효력이 없으므로 사용자·관리자·명령행 설정에 넣어야 합니다. 조사 문서가 명시한 지원 기준은 v2.1.219 이상이며, 설치 버전의 동작을 확인하세요.

예제의 호스트는 npm 저장소입니다. 다른 설정이나 WebFetch 허용 규칙이 합쳐질 수 있으므로 실제 허용 대상도 확인하세요.

3. 실제 차단은 더미 파일로 확인

설정 저장 후 /status로 설정 출처를, /sandbox로 적용 상태를 확인합니다. 기존 excludedCommands도 살펴보세요. allowUnsandboxedCommands: false는 제한 밖 재시도를 막지만 제외 명령은 별도로 검토해야 합니다.

1. 비밀정보가 없는 임시 파일을 만들고 읽기 금지·쓰기 금지 경로로 지정합니다. Linux에서는 대상 파일이 존재하는지도 확인합니다.
2. 같은 파일을 Claude의 Read 도구와 셸 명령으로 각각 읽도록 요청합니다. 두 접근 방식의 거부 결과를 구분해 기록합니다.
3. 프로젝트의 허용 파일 쓰기와 금지 파일 쓰기를 각각 요청하고 실제 변경 여부를 확인합니다.
4. Claude가 실행하는 셸에서 허용 호스트와 비허용 호스트 접속을 요청합니다. 정책 거부인지, 이름 해석이나 서버 장애인지 구분합니다.

일반 터미널에서 직접 실행한 결과는 샌드박스 검증을 대신하지 못합니다. 오류가 나면 설정 출처·병합된 목록·의존성을 확인합니다.

적용 범위와 남는 한계

이 샌드박스는 Read·WebFetch·외부 도구 서버·훅 전체를 감싸지 않습니다. 허용된 서버로의 업로드나 환경변수 속 비밀정보까지 해결하는 설정도 아닙니다.

WSL의 Windows 실행 파일 연동은 Unix 소켓을 사용합니다. 소켓 차단에는 선택적 seccomp 필터가 필요하며, allowAllUnixSockets를 켜면 경계가 넓어집니다. 먼저 /sandbox에서 실제 적용 상태를 확인하고 더미 파일 하나로 읽기 차단부터 검증하세요.

출처

• Anthropic, Configure the sandboxed Bash tool · 2026-10-10 확인
• Anthropic, Configure permissions · 2026-10-10 확인