이 페이지의 목차
확인 2026-10-21근거 자료 2건갱신 2026-10-26언급 12곳
이 페이지의 목차
확인 날짜 안내

공식 문서 Claude Code 샌드박스(본문 날짜 없음, 서버 Last-Modified 2026-10-20, 수집 2026-10-21) 기준이다. 설정 키·명령·버전 조건은 몇 주 단위로 바뀌므로 고객사 적용 전에 공식 문서를 다시 확인한다. 설정 예시와 명령은 원본 글자 그대로 옮겼다.

Claude Code가 돌리는 셸(용어 사전) 명령을 운영체제 경계 안에 넣고, 닿을 파일·도메인을 정하고, 그 경계가 깨뜨리는 도구를 고치는 절차다. 샌드박스가 무엇이고 무엇을 막지 못하는지는 샌드박스에 있다. 먼저 알아 둘 것: 샌드박스는 Bash·PowerShell·Monitor 명령과 그 하위 프로세스만 감싸고, Read·Edit·WebFetch 같은 내장 도구, 훅, 로컬 MCP 서버, 사용자가 !로 직접 친 명령(대부분의 세션. 예외는 샌드박스)은 밖에서 돈다. Claude Code 샌드박스

  1. 1단계. 의존성 설치

    Linux·WSL2만

  2. 2단계. /sandbox로 켜고

    모드 고르기

  3. 3단계. 됐는지 확인

  4. 4단계. 경계 조정

    쓰기·읽기·네트워크

  5. 5단계. 자격 증명 보호

  6. 6단계. 꼭 필요할 때만

    샌드박스 밖으로

  7. 7단계. 재시도 닫기·조직 배포

준비물(필요한 것)#

필요한 것내용
지원 OSmacOS(내장 Seatbelt를 써서 설치할 것 없음), Linux, WSL2. Windows 네이티브는 샌드박스 없이 명령을 돌리므로 Windows 기기에서는 WSL2 배포판 안에서 Claude Code를 돌린다. WSL1은 지원하지 않는다(1절) Claude Code 샌드박스
(Linux·WSL2) 도구 두 개와 설치 권한bubblewrap(파일 격리), socat(네트워크 중계). 원본 설치 명령이 sudo apt-get·sudo dnf이므로 패키지를 설치할 수 있는 권한이 필요하다. Ubuntu 24.04 이상은 경우에 따라 AppArmor 프로필도 더한다(1절) Claude Code 샌드박스
(선택) seccomp 필터Unix 도메인 소켓 차단용. npm install -g @anthropic-ai/sandbox-runtime으로 설치한다. 없어도 샌드박스는 켜진다(1절) Claude Code 샌드박스
Claude Code 세션/sandbox 명령을 칠 세션. Claude Code 설치 절차는 이 페이지의 원본이 다루지 않는다 Claude Code 샌드박스
(조직 전체에 강제할 때) managed settings 배포 수단7절 → Claude Code managed settings 배포·점검Claude Code 샌드박스

1. 의존성 설치 (Linux·WSL2)#

macOS는 내장 Seatbelt를 쓰므로 바로 2단계로 간다. Linux와 WSL2는 bubblewrap(파일 격리)과 socat(네트워크 중계)이 필요하다. 아직 설치하지 않았어도 /sandbox부터 실행하면 패널이 빠진 것을 보여 준다. Windows 네이티브는 샌드박스 없이 명령을 돌리므로, Windows 기기에서는 WSL2 배포판 안에서 Claude Code를 돌린다. Claude Code 샌드박스

Ubuntu/Debian:

bash
sudo apt-get install bubblewrap socat

Fedora:

bash
sudo dnf install bubblewrap socat
  • 의존성 검사는 시작 때 도므로 설치 뒤 Claude Code를 다시 시작한다. 필수 의존성이 없으면 /sandbox에 Dependencies 탭만 보이고, 선택 사항인 seccomp 필터(Unix 도메인 소켓 차단)만 없으면 다른 탭과 함께 보인다. seccomp 필터는 npm install -g @anthropic-ai/sandbox-runtime으로 설치한다. ripgrep은 네이티브 바이너리에 들어 있다. Claude Code 샌드박스
  • Ubuntu 24.04 이상: sysctl kernel.apparmor_restrict_unprivileged_userns가 1을 돌려주면 bwrap에 user namespace를 허용하는 AppArmor 프로필을 더한다(0이거나 No such file or directory면 건너뛴다). 이 프로필은 bwrap 자체에만 적용되고 샌드박스 안에서 도는 명령에는 적용되지 않는다. Claude Code 샌드박스
bash
sudo tee /etc/apparmor.d/bwrap > /dev/null <<'EOF'
abi <abi/4.0>,
include <tunables/global>

profile bwrap /usr/bin/bwrap flags=(unconfined) {
  userns,
  include if exists <local/bwrap>
}
EOF
bash
sudo systemctl reload apparmor
  • WSL2: PowerShell에서 wsl -l -v로 버전을 본다. Sandboxing requires WSL2가 보이면 WSL1이다. Claude Code 샌드박스

2. 켜고 모드 고르기#

세션에서 /sandbox를 실행하면 Mode·Overrides·Config 탭이 열린다. Claude Code 샌드박스

  • Mode: auto-allow(샌드박스 안 명령은 묻지 않음) 또는 regular permissions(샌드박스 안이라도 일반 확인 창). auto-allow에서도 deny 규칙, Bash(git push *) 같은 내용 지정 ask 규칙, 치명 경로 rm·rmdir, Monitor 명령, FOO=bar npm test처럼 실행 프로그램이 바뀔 수 있는 명령은 여전히 막히거나 묻는다(세부는 샌드박스).
  • Overrides: 샌드박스에서 실패한 명령이 샌드박스 밖으로 다시 돌 수 있는지(allowUnsandboxedCommands). 끄면 Strict sandbox mode로 표시된다.
  • Config: 해석된 샌드박스 설정. 보호 경로 대부분이 Denied within allowed 아래 보인다.

어디에 저장되나: Claude Code 샌드박스

원하는 범위방법
이 프로젝트만/sandbox 패널에서 고른다. .claude/settings.local.json에 저장되고, Claude Code가 이 파일을 전역 gitignore에 더한다
내 모든 프로젝트~/.claude/settings.json에 sandbox.enabled: true
한 세션만--settings 플래그
조직 전체 강제managed settings(7단계)

한 세션만 샌드박스를 켜고, 막힌 명령을 샌드박스 밖에서 다시 돌리지 못하게 하는 원본 예:

bash
claude --settings '{"sandbox": {"enabled": true, "allowUnsandboxedCommands": false}}'

3. 됐는지 확인하는 법#

아래 두 줄을 Claude에게 돌려 달라고 한다. !로 직접 치면 대개 샌드박스 밖에서 돌아 시험이 되지 않는다. Claude Code 샌드박스

명령샌드박스 안에서의 결과
touch ~/sandbox-probemacOS는 Operation not permitted, Linux·WSL2는 Read-only file system으로 실패
curl --noproxy '*' https://example.com샌드박스 프록시를 돌아갈 길이 없어 Could not resolve host로 실패

Claude가 실패한 명령을 샌드박스 밖에서 다시 돌리자고 하면 거절한다. touch가 성공했고 홈 디렉터리가 쓰기 허용 디렉터리가 아니라면 ~/sandbox-probe를 지우고 /sandbox로 샌드박스가 켜졌는지, 의존성이 있는지 본다. Claude Code 샌드박스

4. 경계 조정: 쓰기·읽기·네트워크#

쓰기 경로 더하기. kubectl, terraform, npm 같은 도구가 작업 디렉터리 밖에 써야 하면, 도구를 샌드박스에서 빼지 말고 그 경로만 연다. 이 경로는 OS 수준에서 강제돼 하위 프로세스도 따른다. Claude Code 샌드박스

json
{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": ["~/.kube", "/tmp/build"]
    }
  }
}
  • 경로 표기: /tmp/build는 절대 경로, ~/.kube는 홈 기준이다. 권한 규칙의 Read·Edit 경로(//path가 절대, /path가 프로젝트 기준)와 다르다. Claude Code 샌드박스 → Claude Code 권한 규칙 문법
  • 같은 파일 시스템 배열을 여러 설정 범위에 두면 항목을 합친다(잠금이 덮는 항목은 빠진다). 세션 중에 고치면 다음 샌드박스 명령부터 새 경로가 적용된다. Claude Code 샌드박스

읽기 막기와 다시 열기. 겹치는 읽기 규칙은 더 좁은 경로가 이긴다. Claude Code 샌드박스

규칙 예결과
"denyRead": ["~/"] + "allowRead": ["~/projects"]~/projects만 읽히고 나머지 홈은 막힘
"allowRead": ["~/"] + "denyRead": ["~/.env"]~/.env는 막히고 나머지 홈은 읽힘. 넓은 allow가 비밀 파일을 몰래 다시 열지 못한다
"allowRead": ["~/"] + "denyRead": ["~/**/.env"]홈 아래 모든 .env가 막힘. 와일드카드 deny도 넓은 allow 안에서 유지된다

홈 전체 읽기를 막고 현재 프로젝트만 읽게 하는 원본 예. 상대 경로 .이 프로젝트 루트로 풀리도록 프로젝트의 .claude/settings.json에 둔다(~/.claude/settings.json에 두면 .이 ~/.claude로 풀려 프로젝트 파일이 막힌다). Claude Code 샌드박스

json
{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "denyRead": ["~/"],
      "allowRead": ["."]
    }
  }
}

경로 규칙 대신 홈 디렉터리와 마운트된 볼륨 읽기를 한 번에 막으려면 permissions.blockReadsOutsideWorkingDirectories를 켠다. Claude Code 샌드박스

네트워크 도메인. 허용 도메인은 빈 목록에서 시작한다. 목록 밖 호스트에 연결하면 명령은 샌드박스 안에서 결정을 기다리고, 대화형 터미널에서는 권한 모드에 따라 갈린다. Manual·acceptEdits 모드(그리고 bypass를 쓸 수 없는 plan 모드)에서는 Claude Code가 묻는다("Yes"는 이 세션만, "Yes, and don't ask again"은 local 설정에 WebFetch(domain:...) allow 규칙을 저장). bypassPermissions 모드(그리고 bypass를 쓸 수 있는 plan 모드)에서는 묻지 않고 허용하고, dontAsk 모드에서는 거부한다. strictAllowlist나 allowManagedDomainsOnly가 켜져 있거나 호스트가 deniedDomains에 있으면 모든 권한 모드에서 거부한다. 자동 모드에서는 Claude가 명령에 필요한 호스트를 명령에 적어 분류기가 함께 검토하고(v2.1.271 이상), 승인된 목록은 그 명령 하나에만 열린다. 미리 열어 두려면 network.allowedDomains를 쓴다. Claude Code 샌드박스

  • 목록 밖 호스트를 묻지 않고 거부하려면 network.strictAllowlist: true(user·managed·--settings에서만 효과, 저장소 파일에서는 효과 없음, v2.1.219 이상). 샌드박스 명령에만 적용되고 WebFetch는 권한 규칙을 따른다. Claude Code 샌드박스
  • network.deniedDomains는 넓은 allowedDomains 와일드카드가 허용하는 도메인도 막고, 어느 권한 모드에서든 거부한다. Claude Code 샌드박스
  • 사내 프록시를 거쳐야 하면 HTTPS_PROXY·HTTP_PROXY·NO_PROXY를 settings의 env 블록이나 Claude Code를 띄우는 환경에 둔다. 허용 목록을 먼저 적용한 뒤 허용된 연결을 상위 프록시로 보낸다. Claude Code 샌드박스
  • 내 기기에서 도는 사용자 프록시로 바꾸려면 network.httpProxyPort·socksProxyPort를 둔다. 주의: 포트가 적용되면 그 프록시가 보내진 모든 트래픽의 필터링을 맡고, allowedDomains·deniedDomains·strictAllowlist·확인 창·로컬 주소 검사 같은 Claude Code 자신의 네트워크 통제는 그 트래픽에 더는 적용되지 않는다. 샌드박스 명령은 두 프록시 어느 쪽에도 연결할 수 있으므로, 포트를 하나만 두면 다른 쪽 프록시의 Claude Code 도메인 목록이 사용자 프록시를 거쳐 닿는 곳을 제한하지 못한다. 포트를 정할 수 있는 파일은 v2.1.285부터 조건에 따라 다르다: allowManagedDomainsOnly가 켜지면 managed만, 샌드박스가 관리자 필수이거나 더 좁은 네트워크 잠금이 걸리면 managed·--settings·user만, 그 밖에는 모든 설정 파일(v2.1.285 전에는 모든 설정 파일). Claude Code 샌드박스
  • IPv6 주소는 대괄호로 쓴다: "[::1]"(모든 포트), "[::1]:443"(443만). 모호한 항목은 claude doctor가 경고한다. Claude Code 샌드박스

파일 격리만 끄기(네트워크 격리는 유지). 어디에 쓰는지보다 어디로 연결하는지를 통제하려고 샌드박스를 쓸 때의 원본 예다. v2.1.216 이상. user·managed·--settings에서만 받고 프로젝트 파일에서는 받지 않는다. Claude Code 샌드박스

json
{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "disabled": true
    },
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org"]
    }
  }
}

5. 자격 증명 보호#

기본 읽기 정책은 자격 증명 파일도 읽게 두고, 환경 변수도 물려준다. 내장 차단 목록이 없으므로 직접 적는다. Claude Code 샌드박스

막기(deny): 파일은 샌드박스 안 읽기가 막히고(filesystem.denyRead와 같은 제한), 환경 변수는 샌드박스 명령 전마다 지워진다. 모든 설정 범위의 deny를 합치며, 어느 범위도 다른 범위가 더한 deny를 지우지 못한다. 파일 보호는 파일 층의 일부라 파일 격리를 끄면 적용되지 않는다. Claude Code 샌드박스

json
{
  "sandbox": {
    "enabled": true,
    "credentials": {
      "files": [
        { "path": "~/.aws/credentials", "mode": "deny" },
        { "path": "~/.ssh", "mode": "deny" }
      ],
      "envVars": [
        { "name": "GITHUB_TOKEN", "mode": "deny" },
        { "name": "NPM_TOKEN", "mode": "deny" }
      ]
    }
  }
}

가리기(mask): 명령에는 세션별 가짜 값(sentinel)을 보여 주고, 샌드박스 프록시가 허용된 호스트로 나가는 요청에서 실제 값으로 바꾼다. 명령과 그 로그는 실제 값을 갖지 않지만 요청은 인증된다. 조건 셋: network.tlsTerminate(실험 기능)로 프록시가 TLS를 풀어야 하고, 실제 값이 갈 injectHosts가 allowedDomains로도 닿아야 하며, mask·tlsTerminate 등은 user·managed·--settings에서만 받는다(저장소 파일은 무시). TLS 종료가 없으면 실제 값이 새지는 않지만 sentinel이 그대로 서버에 가서 인증이 실패한다(claude doctor의 TLS termination is unavailable 경고). 같은 변수가 어느 범위에서든 deny로도 있으면 deny가 이긴다. Claude Code 샌드박스

json
{
  "sandbox": {
    "enabled": true,
    "network": {
      "tlsTerminate": {},
      "allowedDomains": ["*.github.com", "registry.npmjs.org"]
    },
    "credentials": {
      "envVars": [
        { "name": "GH_TOKEN", "mode": "mask", "injectHosts": ["api.github.com"] },
        { "name": "NPM_TOKEN", "mode": "mask" }
      ]
    }
  }
}

위 예에서 GH_TOKEN은 api.github.com 요청에서만, injectHosts가 없는 NPM_TOKEN은 allowedDomains의 모든 호스트 요청에서 바뀐다. AWS 키는 AWS_ACCESS_KEY_ID와 AWS_SECRET_ACCESS_KEY를 함께 가려야 프록시가 SigV4로 다시 서명한다(v2.1.221 이상). Claude Code 샌드박스

파일 가리기(v2.1.221 이상)는 OS마다 다르다. Linux·WSL2는 sentinel 사본을 읽히고, macOS는 파일을 아예 읽지 못하게 막아 그 파일로 인증하는 도구가 샌드박스 안에서 동작하지 않는다(deny와 같은 효과). 원본 예(GitHub CLI 토큰): Claude Code 샌드박스

json
{
  "sandbox": {
    "enabled": true,
    "network": {
      "tlsTerminate": {},
      "allowedDomains": ["*.github.com"]
    },
    "credentials": {
      "files": [
        {
          "path": "~/.config/gh/hosts.yml",
          "mode": "mask",
          "extract": "oauth_token:\\s*(\\S+)",
          "injectHosts": ["api.github.com"]
        }
      ]
    }
  }
}
  • 확인: Claude에게 샌드박스 명령으로 cat ~/.config/gh/hosts.yml을 돌리게 한다. Linux·WSL2는 토큰 자리에 sentinel이 보이고, macOS는 읽기가 실패한다. Claude Code 샌드박스
  • 주의: 패턴이 아무것도 못 찾으면 기본값 onExtractNoMatch: warn은 그 항목을 건너뛰어 샌드박스 명령이 실제 파일을 읽을 수 있다. macOS에서는 파일 격리가 켜져 있는 동안 mask를 패턴보다 먼저 deny로 적용하므로, 이 결과는 파일 격리를 끈 경우에만 생긴다. 비밀이 있을 수 있는데 패턴이 놓칠 수 있다면 deny를 쓴다. 디렉터리·glob·8 MiB 초과·UTF-8이 아닌 파일은 mask를 할 수 없어 deny로 처리된다. Claude Code 샌드박스
  • sandbox.credentials는 샌드박스 Bash 명령에만 적용된다. 샌드박스 여부와 상관없이 모든 하위 프로세스에서 자격 증명을 지우려면 CLAUDE_CODE_SUBPROCESS_ENV_SCRUB을 쓴다. Claude Code 샌드박스

6. 꼭 필요할 때만 샌드박스 밖으로: excludedCommands#

샌드박스 안에서 동작할 수 없고 전체 권한을 맡길 만큼 신뢰하는 도구에만 쓴다. 디렉터리 하나나 호스트 하나가 더 필요한 정도면 allowWrite나 allowedDomains로 샌드박스 안에 둔다. 원본 예(docker compose를 모든 프로젝트에서 샌드박스 밖으로, ~/.claude/settings.json에 둠): Claude Code 샌드박스

json
{
  "sandbox": {
    "enabled": true,
    "excludedCommands": ["docker compose *"]
  }
}

맞추는 규칙: Claude Code 샌드박스

  • 패턴은 *로 끝낸다. Bash(...) 권한 규칙과 같은 문법이라 와일드카드가 없으면 정확히 일치만 맞는다(docker는 인자 없는 docker만).
  • 호출 안의 모든 명령이 맞아야 한다. npm ci && docker compose build는 npm ci를 덮는 항목이 없으면 샌드박스에 남는다.
  • 명령 줄 텍스트를 맞춘다. docker를 안에서 부르는 스크립트나 make 대상, /usr/local/bin/docker는 맞지 않는다.
  • 파일 리디렉션, cd, $(...)가 있으면 호출 전체가 샌드박스에 남는다.
  • 관리자 필수 샌드박스에서는 .claude/settings.json·.claude/settings.local.json의 항목을 무시한다(v2.1.285 이상. v2.1.282~v2.1.284에서도 같은 설정이 저장소의 excludedCommands를 무시하게 했다).
  • 제외된 명령은 일반 권한 흐름을 탄다. 읽기 전용 명령과 allow 규칙이 덮는 명령은 묻지 않고, 자동 모드에서는 분류기가 검토하며, bypassPermissions에서는 ask 규칙이 없으면 묻지 않는다. 항목이 맞는지 보려면 Manual 모드에서 docker compose up -d 같은 명령을 돌려 확인 창 제목이 "Bash command (unsandboxed)"인지 본다.

프록시를 쓰지 않는 데이터베이스 클라이언트용 원본 예. 스크립트 하나만 빼고, 실행마다 직접 승인하도록 ask 규칙을 붙인다. 스크립트는 전체 권한으로 돌고 Claude가 작업 디렉터리 안 스크립트를 고칠 수 있으므로 확인 창이 뜰 때 스크립트를 검토한다. Claude Code 샌드박스

json
{
  "sandbox": {
    "excludedCommands": ["python scripts/load_orders.py *"]
  },
  "permissions": {
    "ask": ["Bash(python scripts/load_orders.py *)"]
  }
}

7. 재시도 닫기와 조직 배포#

strict sandbox mode. "allowUnsandboxedCommands": false면 Claude Code가 dangerouslyDisableSandbox를 무시해, 샌드박스가 도는 동안 Claude가 돌리는 명령은 excludedCommands에 맞지 않는 한 샌드박스 안에서 돈다. 샌드박스가 못 뜰 때도 막으려면 failIfUnavailable을 함께 둔다. user·--settings·managed의 false는 프로젝트의 true보다 앞선다(v2.1.285 이상). user false만으로는 관리자 필수가 되지 않는다. Claude Code 샌드박스

조직 전체 강제(managed settings). MDM이 관리하는 파일이나 claude.ai 서버 관리 설정으로 배포한다. 원본 예는 샌드박스를 켜고, 플랫폼이 지원되지 않거나 의존성이 없으면 시작을 거부하고, 샌드박스 밖 재시도를 막는다: Claude Code 샌드박스 → managed settings, Claude Code managed settings 배포·점검

json
{
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "allowUnsandboxedCommands": false
  }
}

원본이 함께 고려하라는 것과 남는 구멍: Claude Code 샌드박스

  • 이 구성은 샌드박스를 관리자 필수로 만들어 저장소 파일이 명령을 샌드박스 밖으로 빼지 못한다(v2.1.285 이상. v2.1.282~v2.1.284는 저장소의 excludedCommands만 무시). 조직이 승인한 도구의 excludedCommands·allowWrite·소켓 항목은 managed에 넣는다.
  • ~/.aws, ~/.ssh 같은 자격 증명 디렉터리와 비밀 환경 변수의 sandbox.credentials 항목을 더한다. 기본 읽기 정책이 그것들을 읽게 두기 때문이다.
  • 개발자는 여전히 ! 셸 모드에 명령을 쳐서 샌드박스 밖에서 돌릴 수 있다(Claude Code 밖 터미널과 같은 권한). 대부분의 세션이 그렇고, 백그라운드 세션과 CLAUDE_CODE_SUBPROCESS_ENV_SCRUB을 설정한 Linux 세션은 예외다(샌드박스).
  • 개발자 자신의 ~/.claude/settings.json·--settings에 둔 느슨한 설정(excludedCommands, filesystem.allowWrite 등)은 managed 전용 잠금이 없는 한 계속 적용된다. 대부분은 managed 전용 잠금이 없다.
  • Windows 네이티브 기기는 failIfUnavailable 때문에 시작 때 종료한다. macOS·Linux 기기에만 MDM이나 관리 파일로 배포하거나(서버 관리 설정은 조직 전체에 적용), Windows 사용자를 WSL2나 컨테이너로 옮긴다.

개발자가 정책을 넓히지 못하게. managed가 enabled·failIfUnavailable 같은 Boolean을 두면 managed 값을 쓴다. 배열 키는 범위끼리 합쳐 개발자가 항목을 더할 수 있으므로 잠금을 건다. Claude Code 샌드박스

  • enableWeakerNestedSandbox, enableWeakerNetworkIsolation, network.allowAllUnixSockets, network.allowLocalBinding, allowAppleEvents는 managed가 두지 않으면 개발자가 켤 수 있고 각각 샌드박스를 약하게 한다. 원치 않으면 managed에 false로 둔다.
  • allowManagedReadPathsOnly: true는 managed의 allowRead만 인정한다. allowManagedDomainsOnly는 도메인을 managed 값으로 잠그고, 그때 프록시 포트도 managed만 정한다.
  • managed가 sandbox.filesystem을 두거나 credentials.files에 deny가 있으면 filesystem.disabled는 managed만 정한다.

조직 관점의 근거 표는 Claude Code 관리자 권한 통제, 키별 Scope는 Claude Code 설정 키 레퍼런스에 있다.

8. 문제 해결#

관리자 필수 샌드박스에서는(v2.1.285 이상) 아래 해결책이 프로젝트 설정 파일에서 무시되므로 ~/.claude/settings.json에 둔다. 그래도 효과가 없으면 managed가 그 키를 정했을 수 있다. 해결책이 excludedCommands를 더하는 것이면 그 명령은 샌드박스를 벗어난다는 점을 기억한다. Claude Code 샌드박스

증상원인고치는 법
host-not-allowed 오류허용 도메인에 없음확인 창에서 승인하거나 allowedDomains에 더함. allowManagedDomainsOnly면 확인 창이 없으니 관리자에게 요청
jest가 멈추거나 실패watchman이 샌드박스와 맞지 않음jest --no-watchman
macOS에서 gh·gcloud·terraform TLS 검증 실패Seatbelt 아래 Go 기반 CLI도구마다 gh * 같은 제외 패턴(전체 권한과 저장된 자격 증명으로 돎). MITM 프록시와 사설 CA로 httpProxyPort를 쓰면 대신 enableWeakerNetworkIsolation: true
macOS open·osascript·브라우저 인증 오류 -600Apple Events 기본 차단user·managed·CLI 설정에 allowAppleEvents: true(코드 실행 격리가 사라짐), 또는 open * 제외(Claude가 쓴 파일도 열 수 있음)
docker 실패docker가 샌드박스와 맞지 않음docker compose *처럼 필요한 만큼만 제외
pbcopy·xclip·wl-copy가 클립보드를 못 바꿈샌드박스 안에서 시스템 클립보드에 못 닿음Claude에게 응답에 출력하게 한 뒤 /copy. 제외 목록에 넣는 것만으로는 파이프 호출이 빠지지 않음
git이 unable to unlink old로 실패보호 경로·denyWrite·쓰기 허용 밖 파일을 바꾸려 함샌드박스 밖 재시도를 승인하거나 다른 터미널에서 직접 실행(allowUnsandboxedCommands: false면 직접 실행)
컨테이너 안에서 bwrap 오류 Can't mount proc비특권 컨테이너에서 새 /proc 마운트 불가enableWeakerNestedSandbox: true. 바깥 컨테이너가 필요한 격리를 줄 때만(프로세스 정보 노출)
.claude 설정 경로에 0바이트 읽기 전용 파일, "don't ask again"이 저장 안 됨Linux·WSL2에서 강제 종료된 세션이 남긴 자리 표시자claude doctor로 목록 확인, 다른 세션이 없을 때 rm
SSH로 git 실패macOS 터널이 프록시에 인증 못 함macOS는 HTTPS remote로 바꾸거나 제외. Linux·WSL2는 22번 포트 허용, 사내 프록시 22번, 키 파일 읽기 가능 여부 확인
DB 클라이언트 등 비HTTP 도구가 허용 호스트에 못 닿음프록시 변수를 무시하는 도구그 명령만 제외(위 6단계 예)
localhost 서버에 못 닿음직접 연결이 막힘macOS는 allowLocalBinding: true(localhost의 모든 서비스가 열림), Linux·WSL2는 제외 명령
허용한 호스트가 resolved to a loopback address로 거부로컬 주소로 풀리는 이름호스트 이름과 IP를 포트와 함께 allowedDomains에
/sandbox가 overridden by a higher-priority configurationmanaged나 --settings가 핵심 키를 정함/status의 Setting sources로 출처 확인. managed면 관리자에게
/sandbox가 Sandbox settings not changedlocal 파일에 못 씀EACCES·EPERM·EROFS면 쓸 수 있는 폴더에서 시작, JSON 오류면 파일 수정

근거: Claude Code 샌드박스

SSH remote를 유지해야 할 때의 원본 예(이 항목은 git push origin main에 맞고, cd·git -C·명령 치환이 붙은 호출은 샌드박스에 남으며, 제외된 git 명령은 allowedDomains와 상관없이 어느 호스트에나 닿는다): Claude Code 샌드박스

json
{
  "sandbox": {
    "excludedCommands": ["git fetch *", "git pull *", "git push *"]
  }
}

macOS에서 localhost 서버에 붙게 하는 원본 예(샌드박스 명령이 포트를 열고 localhost의 모든 포트에 연결할 수 있게 되므로, 인증 없는 localhost 서비스가 명령 대신 샌드박스 밖에서 행동할 수 있다): Claude Code 샌드박스

json
{
  "sandbox": {
    "network": {
      "allowLocalBinding": true
    }
  }
}

127.0.0.1을 가리키는 개발용 이름을 허용하는 원본 예(포트 없는 IP 항목은 그 주소의 모든 서비스를 연다): Claude Code 샌드박스

json
{
  "sandbox": {
    "network": {
      "allowedDomains": ["myapp.test:3000", "127.0.0.1:3000"]
    }
  }
}

언제 쓰고 언제 쓰지 않는가#

쓴다

  • 분류기 없이 확인 창을 줄이며 로컬에서 반복 작업할 때: Manual로 시작하고 /sandbox에서 auto-allow. Claude Code 권한 모드 고르기
  • 권한 규칙만으로는 막을 수 없는 것(경로 호출 /usr/bin/curl, sh -c, grep -r, 임의 스크립트의 파일 접근)을 OS 수준에서 막아야 할 때. Claude Code 권한 설정 → Claude Code 권한 규칙 문법
  • 조직이 "에이전트가 실행한 명령이 어디까지 닿는가"를 정책으로 강제해야 할 때: managed + failIfUnavailable + allowUnsandboxedCommands: false. Claude Code 관리자 권한 통제
  • 토큰을 쓰는 명령이 토큰 값 자체를 보지 못하게 하면서 요청은 인증되게 하고 싶을 때(mask. 파일 mask는 macOS에서 deny처럼 동작해 그 파일을 쓰는 도구가 샌드박스 안에서 동작하지 않는다). Claude Code 샌드박스

쓰지 않거나, 다른 것과 함께 쓴다

  • 파일 도구·MCP 서버·훅·LSP까지 한 경계 안에 넣어야 할 때: 샌드박스는 셸 명령만 감싼다. Claude Code 프로세스 전체를 sandbox runtime, dev container, 컨테이너, VM에서 돌리라고 원본은 말한다. Claude Code 샌드박스
  • 암호화된 트래픽 내용을 검사해야 하는 위협 모델: 내장 프록시는 TLS를 풀어 보지 않는다. TLS를 풀어 검사하는 사용자 프록시를 두라고 원본은 말한다. 샌드박스
  • Windows 네이티브 기기: 샌드박스가 돌지 않는다. WSL2나 컨테이너로 옮긴다.
  • docker, watchman, SSH remote의 git(macOS) 같은 도구가 작업의 중심이고 제외 목록이 계속 늘어난다면: 편집자 해석으로, 제외 항목마다 그 명령이 전체 권한으로 돈다는 원본 경고를 보면, 이때는 프로세스 전체를 감싸는 격리를 검토하는 편이 맞을 수 있다고 볼 수 있다. Claude Code 샌드박스

관련#