SpyBara
Go Premium

sandboxing.md 2026-06-09 06:34 UTC to 2026-06-10 23:57 UTC

262 added, 161 removed.

2026
Tue 30 23:02 Mon 29 23:02 Sat 27 01:01 Fri 26 23:00 Thu 25 23:58 Wed 24 22:02 Tue 23 22:00 Mon 22 23:59 Fri 19 22:58 Thu 18 22:00 Wed 17 17:02 Tue 16 21:57 Mon 15 23:02 Sat 13 21:59 Fri 12 22:00 Thu 11 23:01 Wed 10 23:57 Tue 9 06:34 Mon 8 06:52 Sat 6 06:24 Fri 5 06:45 Thu 4 06:52 Wed 3 06:53 Tue 2 06:51

샌드박싱된 Bash 도구 구성

Claude Code의 샌드박싱된 Bash 도구가 파음시슀템 및 넀튞워크 격늬륌 제공하여 더 안전하고 자윚적읞 에읎전튞 싀행을 가능하게 하는 방법을 알아뎅니닀.

Bash 샌드박슀륌 사용하멎 Claude가 대부분의 ì…ž 명령을 권한을 요청하지 않고 싀행할 수 있습니닀. 각 명령을 승읞하는 대신 명령읎 접귌할 수 있는 파음곌 넀튞워크 도메읞을 정의하멎 욎영 첎제가 몚든 Bash 명령곌 ê·ž 자식 프로섞슀에 대핮 핎당 겜계륌 적용합니닀.

읎 페읎지에서는 닀음을 닀룹니닀:

시작하Ʞ

샌드박슀는 Claude Code에 낎장되얎 있윌며 macOS, Linux 및 WSL2에서 싀행됩니닀. Ʞ볞 Windows는 지원되지 않습니닀. Windows에서는 WSL2 배포판 낎에서 Claude Code륌 싀행하섞요.

macOS에서는 섀치할 것읎 없습니닀: 샌드박싱은 Ʞ볞 제공 Seatbelt 프레임워크륌 사용합니닀. Linux 및 WSL2에서 샌드박슀는 두 개의 팚킀지에 의졎하며, Linux 및 WSL2 섀정에서 닀룹니닀. 아직 섀치하지 않았더띌도 /sandbox로 시작할 수 있습니닀. 핎당 팚널은 누띜된 것읎 있는지 볎여쀍니닀.

1

/sandbox 싀행

Claude Code 섞션을 시작하고 /sandbox 명령을 싀행합니닀:

/sandbox

읎는 ì„ž 개의 탭읎 있는 샌드박슀 팚널을 엜니닀:

  • Mode: 샌드박싱된 명령읎 승읞되는 방식을 선택합니닀. 닀음 닚계에서 닀룹니닀
  • Overrides: 샌드박슀에서 싀팚한 명령읎 샌드박싱되지 않은 상태로 싀행되도록 폎백할 수 있는지 선택합니닀. 읎는 allowUnsandboxedCommands 섀정입니닀
  • Config: 핎석된 샌드박슀 섀정을 뎅니닀

팚널에 Dependencies 탭만 표시되멎 필수 팚킀지가 누띜된 것입니닀. Linux 및 WSL2 섀정에 섀명된 대로 섀치하고 Claude Code륌 닀시 시작한 후 /sandbox륌 닀시 싀행합니닀.

2

몚드 선택

Mode 탭에서 자동 허용 또는 음반 권한을 선택합니닀. 자동 허용은 샌드박싱된 명령을 프롬프튞 없읎 싀행하고, 음반 권한은 명령읎 샌드박싱되었을 때도 음반 권한 프롬프튞륌 유지합니닀. 자동 허용 몚드에서 여전히 프롬프튞되는 명령은 샌드박슀 몚드륌 찞조하섞요.

3

Bash 명령 싀행

Claude에게 빌드 또는 테슀튞 슀위튞와 같은 명령을 싀행하도록 요청합니닀. Ʞ볞적윌로 샌드박슀 낎의 명령은 작업 디렉토늬에만 ì“ž 수 있습니닀. 명령읎 새 넀튞워크 도메읞에 처음 액섞슀핎알 할 때 Claude Code가 승읞을 요청합니닀.

샌드박싱할 수 없는 명령은 음반 권한 흐늄윌로 폎백합니닀. 읎러한 겜계륌 확대하거나 축소하렀멎 샌드박싱 구성을 찞조하섞요.

팚널에서 몚드륌 선택하멎 현재 프로젝튞에 적용되고 git에 첎크읞되지 않는 프로젝튞의 로컬 섀정 .claude/settings.local.json에 Ʞ록됩니닀. 몚든 프로젝튞에서 샌드박슀륌 활성화하렀멎 사용자 섀정 ~/.claude/settings.json에서 sandbox.enabled륌 true로 섀정합니닀. 조직의 몚든 개발자에게 샌드박싱을 적용하렀멎 ꎀ늬 섀정을 사용합니닀.

Linux 및 WSL2 섀정

Linux 및 WSL2에서 샌드박슀는 두 개의 팚킀지에 의졎합니닀:

  • bubblewrap: 파음시슀템 격늬륌 적용하는 권한 없는 샌드박싱 도구
  • socat: 샌드박슀 프록시륌 통핎 넀튞워크 튞래픜을 띌우팅하는 데 사용되는 늎레읎

배포판의 팚킀지 ꎀ늬자로 섀치합니닀:

sudo apt-get install bubblewrap socat

섀치 후 /sandbox의 Dependencies 탭은 ripgrep, bubblewrap, socat 및 seccomp 필터가 플랫폌에서 사용 가능한지 볎여쀍니닀. Ripgrep은 Ʞ볞 Claude Code 바읎너늬와 핚께 번듀됩니닀. seccomp 필터는 선택 사항읎며 Unix 도메읞 소쌓 찚닚을 추가합니닀. 누띜된 겜우 npm install -g @anthropic-ai/sandbox-runtime윌로 섀치합니닀.

필수 종속성읎 누띜되멎 섀치할 때까지 Dependencies 탭만 표시됩니닀. 종속성 확읞은 시작 시 싀행되므로 팚킀지 섀치 후 Claude Code륌 닀시 시작하여 /sandbox가 읎륌 감지하도록 합니닀.

Ubuntu 24.04 읎상에서 Ʞ볞 AppArmor 정책은 bubblewrap읎 격늬에 필요한 사용자 넀임슀페읎슀륌 생성하는 것을 방지합니닀. 
WSL2 낎부륌 포핚하여 환겜읎 읎 제한을 적용하는지 확읞하렀멎 `sysctl kernel.apparmor_restrict_unprivileged_userns`륌 싀행합니닀. 킀가 졎재하지 않거나 `0`을 반환하멎 읎 닚계륌 걎너뜁니닀. `1`을 반환하멎 `bwrap`에 읎 Ʞ능을 부여하는 AppArmor 프로필을 추가합니닀:

```bash theme={null}
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
```

프로필은 `bwrap` 자첎에만 적용되며 샌드박슀 낎에서 싀행되는 명령에는 적용되지 않습니닀. AppArmor륌 닀시 로드하여 적용합니닀:

```bash theme={null}
sudo systemctl reload apparmor
```
WSL2 ì°žê³  사항

PowerShell에서 wsl -l -v로 WSL 버전을 확읞합니닀. Sandboxing requires WSL2가 표시되멎 배포판읎 WSL1을 싀행 쀑입니닀. WSL2로 업귞레읎드하거나 샌드박싱 없읎 Claude Code륌 싀행합니닀.

WSL2에서 샌드박싱된 명령은 cmd.exe, powershell.exe 또는 /mnt/c/ 아래의 몚든 항목곌 같은 Windows 바읎너늬륌 시작할 수 없습니닀. WSL은 읎륌 Unix 소쌓을 통핎 Windows 혞슀튞로 전달하며, 샌드박슀가 읎륌 찚닚합니닀. 명령읎 Windows 바읎너늬륌 혞출핎알 하멎 excludedCommands에 추가하여 샌드박슀 왞부에서 싀행되도록 합니닀.

샌드박슀 몚드

Claude Code는 두 가지 샌드박슀 몚드륌 제공합니닀:

자동 허용 몚드: Bash 명령은 샌드박슀 낎에서 싀행을 시도하며 권한 없읎 자동윌로 허용됩니닀. 허용되지 않은 혞슀튞에 대한 넀튞워크 액섞슀가 필요한 겜우 등 샌드박싱할 수 없는 명령은 음반 권한 흐늄윌로 폎백합니닀. 여Ʞ서 Claude Code는 권한 규칙을 확읞하고 핎당 규칙읎 읎믞 허용하지 않는 몚든 명령에 대핮 프롬프튞합니닀.

자동 허용 몚드에서도 닀음읎 적용됩니닀:

  • 명시적 거부 규칙은 항상 졎쀑됩니닀
  • /, 홈 디렉토늬 또는 Ʞ타 쀑요한 시슀템 겜로륌 대상윌로 하는 rm 또는 rmdir 명령은 여전히 권한 프롬프튞륌 튞늬거합니닀
  • Ask 규칙은 음반 권한 흐늄윌로 폎백되는 명령에 적용됩니닀

음반 권한 몚드: 몚든 Bash 명령은 샌드박싱되었더띌도 음반 권한 흐늄을 거칩니닀. 읎는 더 많은 제얎륌 제공하지만 더 많은 승읞읎 필요합니닀.

두 몚드 몚두에서 샌드박슀는 동음한 파음시슀템 및 넀튞워크 제한을 적용합니닀. 찚읎점은 샌드박싱된 명령읎 자동 승읞되는지 또는 명시적 권한읎 필요한지 여부뿐입니닀.

음부 명령은 샌드박슀 낎에서 전혀 싀행할 수 없습니닀. 예륌 듀얎 혞환되지 않는 도구나 허용하지 않은 혞슀튞가 필요한 도구입니닀. 작업을 싀팚하거나 샌드박싱을 끄도록 요구하는 대신 Claude Code는 탈출 핎치륌 포핚합니닀: 명령읎 샌드박슀 제한윌로 읞핎 싀팚하멎 Claude는 싀팚륌 분석하고 dangerouslyDisableSandbox 맀개변수로 명령을 닀시 시도할 수 있습니닀. 닀시 시도된 명령은 샌드박슀 왞부에서 싀행되므로 음반 권한 흐늄을 거치고 승읞읎 필요합니닀.

샌드박슀 섀정에서 "allowUnsandboxedCommands": false륌 섀정하여 읎 탈출 핎치륌 비활성화할 수 있습니닀. 비활성화되멎 /sandbox Overrides 탭에 Strict sandbox mode로 표시되며, dangerouslyDisableSandbox 맀개변수는 완전히 묎시되고 몚든 명령은 샌드박싱되거나 excludedCommands에 명시적윌로 나엎되얎알 합니닀.

샌드박싱 구성

settings.json 파음을 통핎 샌드박슀 동작을 사용자 정의합니닀. 전첎 구성 찞조는 섀정을 찞조하섞요.

Ʞ볞적윌로 샌드박싱된 명령은 현재 작업 디렉토늬에만 ì“ž 수 있습니닀. kubectl, terraform 또는 npm곌 같은 하위 프로섞슀 명령읎 프로젝튞 디렉토늬 왞부에 ì“°êž°í•Žì•Œ 하멎 sandbox.filesystem.allowWrite륌 사용하여 특정 겜로에 대한 액섞슀륌 부여합니닀:

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": ["~/.kube", "/tmp/build"]
    }
  }
}

읎러한 겜로는 OS 수쀀에서 적용되므로 샌드박슀 낎에서 싀행되는 몚든 명령(자식 프로섞슀 포핚)읎 읎륌 졎쀑합니닀. 읎는 도구륌 excludedCommands로 샌드박슀에서 완전히 제왞하는 것볎닀 도구가 특정 위치에 ì“°êž° 액섞슀가 필요할 때 권장되는 방법입니닀.

동음한 파음시슀템 배엎읎 여러 섀정 범위에서 정의되멎 배엎읎 병합됩니닀: 몚든 범위의 겜로가 결합되며 대첎되지 않습니닀.

겜로 접두사는 겜로가 핎석되는 방식을 제얎합니닀:

접두사 의믞 예시
/ 파음시슀템 룚튞의 절대 겜로 /tmp/build는 /tmp/build로 유지됩니닀
~/ 홈 디렉토늬에 상대적 ~/.kube는 $HOME/.kube가 됩니닀
./ 또는 접두사 없음 프로젝튞 섀정의 겜우 프로젝튞 룚튞에 상대적읎거나, 사용자 섀정의 겜우 ~/.claude에 상대적 .claude/settings.json의 ./output은 <project-root>/output윌로 핎석됩니닀

읎 구묞은 절대 겜로에 //path륌 사용하고 프로젝튞 상대에 /path륌 사용하는 Read 및 Edit 권한 규칙곌 닀늅니닀. 샌드박슀 파음시슀템 겜로는 표쀀 규칙을 사용합니닀: /tmp/build는 절대 겜로입니닀.

sandbox.filesystem.denyWrite 및 sandbox.filesystem.denyRead륌 사용하여 ì“°êž° 또는 읜Ʞ 액섞슀륌 거부할 수도 있윌며, sandbox.filesystem.allowRead륌 사용하여 거부된 영역 낎에서 특정 겜로 읜Ʞ륌 닀시 허용할 수 있습니닀.

아래 예제는 홈 디렉토늬 전첎에서의 읜Ʞ륌 찚닚하멎서도 현재 프로젝튞에서의 읜Ʞ륌 허용합니닀. 상대 겜로 .읎 프로젝튞 섀정에 있을 때만 프로젝튞 룚튞로 핎석되므로 프로젝튞의 .claude/settings.json에 배치합니닀:

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

.의 allowRead는 읎 구성읎 프로젝튞 섀정에 있윌므로 프로젝튞 룚튞로 핎석됩니닀. 동음한 구성을 ~/.claude/settings.json에 배치했닀멎 .은 ~/.claude로 핎석되고 프로젝튞 파음은 denyRead 규칙에 의핎 찚닚된 상태로 유지됩니닀.

샌드박싱 작동 방식

파음시슀템 격늬

샌드박싱된 Bash 도구는 파음 시슀템 액섞슀륌 특정 디렉토늬로 제한합니닀:

  • Ʞ볞 ì“°êž° 동작: 현재 작업 디렉토늬 및 ê·ž 하위 디렉토늬에 대한 읜Ʞ 및 ì“°êž° 액섞슀
  • Ʞ볞 읜Ʞ 동작: 특정 거부된 디렉토늬륌 제왞한 전첎 컎퓚터에 대한 읜Ʞ 액섞슀. 읎 Ʞ볞값은 여전히 ~/.aws/credentials 및 ~/.ssh/와 같은 자격 슝명 파음 읜Ʞ륌 허용합니닀. 읎륌 찚닚하렀멎 denyRead에 추가합니닀.
  • 찚닚된 액섞슀: 명시적 권한 없읎 현재 작업 디렉토늬 왞부의 파음을 수정할 수 없습니닀. ~/.bashrc와 같은 ì…ž 구성 파음 및 /bin/의 시슀템 바읎너늬 포핚
  • Git worktrees: 작업 디렉토늬가 연결된 git worktree음 때, 샌드박슀는 또한 메읞 저장소의 공유 .git 디렉토늬에 대한 쓰Ʞ륌 허용하므로 git commit곌 같은 명령읎 refs 및 읞덱슀륌 업데읎튞할 수 있습니닀. 핎당 디렉토늬 낎의 hooks/ 및 config에 대한 쓰Ʞ는 계속 거부됩니닀.
  • 구성 가능: 섀정을 통핎 사용자 정의 허용 및 거부 겜로륌 정의합니닀

sandbox.filesystem.allowWrite륌 사용하여 추가 겜로에 대한 ì“°êž° 액섞슀륌 부여할 수 있습니닀. 읎러한 제한은 OS 수쀀에서 적용되므로 Claude의 파음 도구뿐만 아니띌 kubectl, terraform, npm곌 같은 도구륌 포핚한 몚든 하위 프로섞슀 명령에 적용됩니닀.

넀튞워크 격늬

넀튞워크 액섞슀는 샌드박슀 왞부에서 싀행되는 프록시 서버륌 통핎 제얎됩니닀:

  • 도메읞 제한: 사전 허용된 도메읞읎 없습니닀. 명령읎 새 도메읞에 처음 액섞슀핎알 할 때 Claude Code가 승읞을 요청합니닀. allowedDomains로 도메읞을 사전 허용하여 프롬프튞륌 플합니닀.
  • ꎀ늬 잠ꞈ: allowManagedDomainsOnly가 ꎀ늬 섀정에서 섀정되멎 허용되지 않은 도메읞읎 프롬프튞 대신 자동윌로 찚닚되며 ꎀ늬 섀정의 allowedDomains만 졎쀑됩니닀.
  • 사용자 정의 프록시 지원: 고꞉ 사용자는 나가는 튞래픜에 대한 사용자 정의 규칙을 구현할 수 있습니닀
  • 포ꎄ적 범위: 제한은 명령윌로 생성된 몚든 슀크늜튞, 프로귞랚 및 하위 프로섞슀에 적용됩니닀

OS 수쀀 적용

샌드박싱된 Bash 도구는 욎영 첎제 볎안 Ʞ볞 요소륌 활용합니닀:

  • macOS: 샌드박슀 적용을 위핎 Seatbelt륌 사용합니닀
  • Linux: 격늬륌 위핎 bubblewrap을 사용합니닀
  • WSL2: Linux와 동음하게 bubblewrap을 사용합니닀

WSL1은 bubblewrap읎 WSL2에서만 사용 가능한 컀널 Ʞ능을 필요로 하Ʞ 때묞에 지원되지 않습니닀. 읎러한 OS 수쀀의 제한은 Claude Code의 명령윌로 생성된 몚든 자식 프로섞슀가 동음한 볎안 겜계륌 상속하도록 볎장합니닀.

읎러한 동음한 Ʞ볞 요소는 독늜 싀행형 @anthropic-ai/sandbox-runtime 팚킀지로 사용 가능하며, 샌드박슀 환겜 페읎지에서 전첎 Claude Code 프로섞슀륌 래핑하Ʞ 위한 별도의 방식윌로 닀룹니닀.

샌드박싱읎 권한 및 권한 몚드와 얎떻게 ꎀ렚되는지

샌드박싱, 권한 규칙 및 권한 몚드는 상혞 볎완적읞 계잵입니닀. 아래 섹션에서는 샌드박슀가 각각곌 얎떻게 상혞 작용하는지 닀룹니닀.

권한 규칙

권한 규칙곌 샌드박싱은 닀륞 것을 제얎합니닀:

  • 권한 규칙은 Claude Code가 사용할 수 있는 도구륌 제얎하며 도구가 싀행되Ʞ 전에 평가됩니닀. 몚든 도구에 적용됩니닀: Bash, Read, Edit, WebFetch, MCP 등.
  • 샌드박싱은 Bash 명령읎 파음시슀템 및 넀튞워크 수쀀에서 액섞슀할 수 있는 것을 제한하는 OS 수쀀의 적용을 제공합니닀. Bash 명령 및 ê·ž 자식 프로섞슀에만 적용됩니닀.

두 계잵은 또한 적용 방식읎 닀늅니닀. Claude Code는 명령 묞자엎을 Ʞ반윌로 명령읎 싀행되Ʞ 전에 권한 결정을 평가하고, 자동 몚드에서는 명령읎 안전한지 여부에 대한 별도 분류Ʞ의 판닚을 평가합니닀. 욎영 첎제는 싀행 쀑읞 프로섞슀에 샌드박슀 겜계륌 적용하므로 몚덞읎 싀행하도록 선택한 것곌 ꎀ계없읎 귞늬고 허용된 명령읎 읎늄읎 나타낮는 것볎닀 더 많읎 하더띌도 유지됩니닀.

파음시슀템 및 넀튞워크 제한은 샌드박슀 섀정 및 권한 규칙을 통핎 몚두 구성됩니닀:

섀정 또는 규칙 수행 작업
sandbox.filesystem.allowWrite 작업 디렉토늬 왞부의 겜로에 대한 하위 프로섞슀 ì“°êž° 액섞슀륌 부여합니닀
sandbox.filesystem.denyWrite 및 sandbox.filesystem.denyRead 특정 겜로에 대한 하위 프로섞슀 액섞슀륌 찚닚합니닀
sandbox.filesystem.allowRead denyRead 영역 낎의 특정 겜로 읜Ʞ륌 닀시 허용합니닀
Edit 허용 규칙 특정 겜로에 대한 ì“°êž° 액섞슀륌 부여합니닀. sandbox.filesystem.allowWrite와 동음한 방식
Read 및 Edit 거부 규칙 특정 파음 또는 디렉토늬에 대한 액섞슀륌 찚닚합니닀
WebFetch 허용 및 거부 규칙 도메읞 액섞슀륌 제얎합니닀
샌드박슀 allowedDomains Bash 명령읎 도달할 수 있는 도메읞을 제얎합니닀
샌드박슀 deniedDomains 더 ꎑ범위한 allowedDomains 와음드칎드가 허용할 수 있는 겜우에도 특정 도메읞을 찚닚합니닀

sandbox.filesystem 섀정 및 권한 규칙의 겜로는 최종 샌드박슀 구성윌로 병합됩니닀.

claude-code 저장소의 예제 디렉토늬에는 샌드박슀 ꎀ렚 예제륌 포핚한 음반적읞 배포 시나늬였에 대한 시작 섀정 구성읎 포핚되얎 있습니닀. 읎륌 시작점윌로 사용하고 필요에 맞게 조정합니닀.

권한 몚드

/sandbox는 권한 몚드가 아닙니닀. 권한 몚드는 도구 혞출읎 싀행되는지 여부와 뚌저 프롬프튞되는지 여부륌 결정하는 반멎, 샌드박슀는 Bash 명령읎 싀행되멎 액섞슀할 수 있는 것을 제한합니닀. 제얎하는 것곌 작업별 프롬프튞륌 대첎하는 것읎 닀늅니닀:

제얎하는 것 프롬프튞륌 대첎하는 것
/sandbox Bash 명령읎 싀행되멎 액섞슀할 수 있는 것 자동 허용 몚드의 샌드박슀 겜계 자첎
자동 몚드 각 도구 혞출읎 싀행되는지 여부 작업을 검토하는 분류Ʞ
--dangerously-skip-permissions 각 도구 혞출읎 싀행되는지 여부 없음. 볎혞된 겜로 확읞도 걎너뜁니닀. / 또는 홈 디렉토늬 제거만 여전히 프롬프튞합니닀

샌드박슀의 자동 허용 몚드는 자동 몚드와 별개입니닀: 자동 허용은 샌드박슀 겜계가 읎륌 포핚하Ʞ 때묞에 Bash 명령을 승읞하는 반멎, 자동 몚드는 분류Ʞ륌 사용하여 작업을 검토합니닀. 두 가지는 독늜적윌로 작동하며 결합할 수 있습니닀. 묎읞 싀행을 위한 격늬 겜계륌 선택하렀멎 샌드박슀 환겜을 찞조하섞요.

조직을 위핎 샌드박슀 구성

ꎀ늬자는 몚든 사용자에게 샌드박싱을 요구하고, 개발자가 정책을 확대하는 것을 방지하고, 샌드박슀 튞래픜을 회사 프록시륌 통핎 띌우팅할 수 있습니닀.

ꎀ늬 섀정윌로 샌드박싱 적용

몚든 개발자에게 샌드박슀륌 요구하렀멎 ꎀ늬 섀정을 통핎 sandbox 킀륌 제공합니닀. MDM윌로 ꎀ늬되는 파음 또는 Claude.ai의 서버 ꎀ늬 섀정을 통핎 제공합니닀.

닀음 ꎀ늬 섀정 구성은 샌드박슀륌 활성화하고, 샌드박슀륌 쎈Ʞ화할 수 없윌멎 Claude Code 시작을 거부하고, 몚덞읎 샌드박슀 왞부에서 명령을 닀시 시도하는 것을 방지합니닀:

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

enabled 읎상의 두 킀는 샌드박슀가 명령을 싀행할 수 없을 때 발생하는 음을 제얎합니닀:

  • failIfUnavailable: Linux의 bubblewrap곌 같은 누띜된 종속성읎 겜고륌 표시하고 샌드박싱 없는 싀행윌로 폎백하는 대신 Claude Code가 시작되는 것을 찚닚합니닀
  • allowUnsandboxedCommands: false: dangerouslyDisableSandbox 탈출 핎치가 묎시되므로 샌드박슀에서 싀팚한 명령을 샌드박슀 왞부에서 닀시 시도할 수 없습니닀

핚께 고렀할 가치가 있는 두 가지 추가 사항읎 있습니닀. 격늬 없읎 싀행핎알 하는 조직 승읞 도구에 대핮 excludedCommands륌 추가합니닀. ~/.aws 및 ~/.ssh와 같은 자격 슝명 디렉토늬에 대핮 denyRead 항목을 추가합니닀. Ʞ볞 읜Ʞ 정책은 여전히 읎륌 허용합니닀.

샌드박슀는 Ʞ볞 Windows에서 싀행되지 않윌므로 플늿에 Windows 혞슀튞가 포핚되멎 읎 구성을 macOS 및 Linux로 범위륌 지정하거나 핎당 사용자가 WSL2 또는 컚테읎너 낎에서 Claude Code륌 싀행하도록 합니닀.

개발자가 정책을 확대하는 것을 방지

enabled 및 failIfUnavailable곌 같은 부욞 킀의 겜우 Claude Code는 ꎀ늬 값을 사용하고 개발자가 로컬로 섀정한 몚든 것을 묎시합니닀. excludedCommands 및 allowRead와 같은 ë°°ì—Ž 킀의 겜우 Claude Code는 몚든 범위의 항목을 병합하므로 개발자는 정책을 확대하는 항목을 추가할 수 있습니닀.

ꎀ늬 섀정에서 allowManagedReadPathsOnly륌 true로 섀정하여 ꎀ늬 섀정의 allowRead 항목만 졎쀑되도록 합니닀. 사용자, 프로젝튞 및 로컬 allowRead 항목은 묎시됩니닀. 읎는 개발자가 조직 승읞 겜로 읎상윌로 읜Ʞ 액섞슀륌 확대하는 것을 방지합니닀. 넀튞워크 도메읞을 동음한 방식윌로 ꎀ늬 값윌로 잠귞렀멎 allowManagedDomainsOnly륌 섀정합니닀.

excludedCommands는 동등한 ꎀ늬 전용 잠ꞈ읎 없윌므로 개발자는 항상 샌드박슀 왞부에서 싀행되는 추가 명령을 추가하는 항목을 추가할 수 있습니닀. ꎀ늬 목록을 좁게 유지합니닀.

사용자 정의 프록시 구성

고꞉ 넀튞워크 볎안읎 필요한 조직의 겜우 사용자 정의 프록시륌 구현하여 닀음을 수행할 수 있습니닀:

  • HTTPS 튞래픜 복혞화 및 검사
  • 사용자 정의 필터링 규칙 적용
  • 몚든 넀튞워크 요청 로깅
  • êž°ì¡Ž 볎안 읞프띌와 통합

Claude Code륌 프록시로 지정하렀멎 샌드박슀 섀정에서 프록시 포튞륌 섀정합니닀:

{
  "sandbox": {
    "network": {
      "httpProxyPort": 8080,
      "socksProxyPort": 8081
    }
  }
}

묞제 í•Žê²°

음부 명령은 샌드박슀 낎에서 싀팚하지만 왞부에서는 작동합니닀. 아래 수정 사항은 가장 음반적읞 겜우륌 닀룹니닀.

  • 명령읎 host-not-allowed 였류로 싀팚: 많은 CLI 도구는 특정 혞슀튞에 도달핎알 합니닀. 프롬프튞될 때 권한을 부여하멎 혞슀튞가 허용 목록에 추가되므로 도구가 향후 샌드박슀 낎에서 싀행됩니닀.
  • jest가 쀑닚되거나 싀팚: watchman은 샌드박슀와 혞환되지 않습니닀. 대신 jest --no-watchman을 싀행합니닀.
  • Go êž°ë°˜ CLI가 macOS에서 TLS 검슝 싀팚: gh, gcloud, terraform곌 같은 도구는 Seatbelt에서 TLS 검슝에 싀팚할 수 있습니닀. 읎러한 도구륌 excludedCommands에 나엎하여 샌드박슀 왞부에서 싀행합니닀. MITM 프록시 및 사용자 정의 CA와 핚께 httpProxyPort륌 사용하는 겜우 대신 enableWeakerNetworkIsolation을 true로 섀정합니닀.
  • docker 명령 싀팚: docker는 샌드박슀와 혞환되지 않습니닀. docker *륌 excludedCommands에 추가하여 샌드박슀 왞부에서 싀행합니닀.
  • 컚테읎너 낎에서 Bubblewrap 시작 싀팚: 권한 없는 컚테읎너에서 bubblewrap은 새로욎 /proc 파음시슀템을 마욎튞할 수 없습니닀. enableWeakerNestedSandbox륌 true로 섀정하여 낎부 샌드박슀가 컚테읎너의 êž°ì¡Ž /proc을 바읞드 마욎튞하도록 합니닀. 왞부 컚테읎너가 읎믞 필요한 격늬 겜계륌 제공할 때만 읎 섀정을 사용합니닀. 새로욎 /proc 마욎튞가 숚Ꞟ 프로섞슀 정볎륌 샌드박싱된 명령에 녞출하Ʞ 때묞입니닀.
  • Linux의 Seccomp 필터: seccomp 필터는 Unix 도메읞 소쌓을 찚닚하는 데 필요합니닀. /sandbox의 Dependencies 탭은 사용 가능한지 볎여쀍니닀. 누띜된 겜우 npm install -g @anthropic-ai/sandbox-runtime을 싀행하여 도우믞륌 섀치합니닀.
  • --dangerously-skip-permissions읎 root로 싀팚: 읎 플래귞는 Linux 및 macOS에서 root로 또는 sudo륌 통핎 싀행할 때 찚닚됩니닀. root 액섞슀와 권한 프롬프튞 없음읎 결합되멎 시슀템의 몚든 파음 또는 서비슀륌 수정할 수 있Ʞ 때묞입니닀. 확읞은 읞식된 샌드박슀 낎에서 자동윌로 걎너뜁니닀. 컚테읎너에서 자윚적윌로 싀행하렀멎 dev 컚테읎너 구성을 사용합니닀. 읎는 Claude Code륌 비 root 사용자로 싀행합니닀.

제한 사항

샌드박싱은 위험을 쀄읎지만 완전한 격늬 겜계는 아닙니닀. 읎륌 하드 볎안 제얎로 사용하Ʞ 전에 아래 제한 사항을 검토합니닀.

볎안 제한 사항

  • 넀튞워크 필터링: 넀튞워크 필터링 시슀템은 프로섞슀가 연결할 수 있는 도메읞을 제한하여 작동합니닀. Ʞ볞 제공 프록시는 아웃바욎드 튞래픜을 종료하거나 TLS 검사륌 수행하지 않윌므로 암혞화된 연결의 낎용은 검사되지 않습니닀. 정책에서 신뢰할 수 있는 도메읞만 허용하도록 볎장하는 것은 사용자의 책임입니닀.
  • Unix 소쌓을 통한 권한 상승: allowUnixSockets 구성은 싀수로 샌드박슀 우회로 읎얎질 수 있는 강력한 시슀템 서비슀에 대한 액섞슀륌 부여할 수 있습니닀. 예륌 듀얎 /var/run/docker.sock에 대한 액섞슀륌 허용하멎 Docker 소쌓을 통핎 혞슀튞 시슀템에 대한 액섞슀륌 횚곌적윌로 부여합니닀. 샌드박슀륌 통핎 허용하는 몚든 Unix 소쌓을 신쀑하게 고렀합니닀.
  • 파음시슀템 권한 상승: 곌도하게 ꎑ범위한 파음시슀템 ì“°êž° 권한은 권한 상승 공격을 가능하게 할 수 있습니닀. $PATH의 싀행 파음을 포핚하는 디렉토늬, 시슀템 구성 디렉토늬 또는 .bashrc 또는 .zshrc와 같은 사용자 ì…ž 구성 파음에 대한 쓰Ʞ륌 허용하멎 닀륞 사용자 또는 시슀템 프로섞슀가 읎러한 파음에 액섞슀할 때 닀륞 볎안 컚텍슀튞에서 윔드 싀행윌로 읎얎질 수 있습니닀.
  • Linux 샌드박슀 강도: Linux 구현은 강력한 파음시슀템 및 넀튞워크 격늬륌 제공하지만 권한 있는 넀임슀페읎슀 없읎 Docker 환겜 낎에서 작동할 수 있도록 하는 enableWeakerNestedSandbox 몚드륌 포핚합니닀. 또는 권한 없는 사용자 넀임슀페읎슀가 sysctl에 의핎 비활성화된 Linux 혞슀튞에서. 읎 옵션은 볎안을 상당히 앜화시킀며 추가 격늬가 닀륞 방식윌로 적용되는 겜우에만 사용핎알 합니닀.
  • 섀정 파음 볎혞: 샌드박슀는 몚든 범위의 Claude Code settings.json 파음 및 ꎀ늬 섀정 디렉토늬에 대한 ì“°êž° 액섞슀륌 자동윌로 거부하므로 샌드박싱된 명령은 자신의 정책을 수정할 수 없습니닀.

플랫폌 및 도구 혞환성

  • 플랫폌 지원: macOS, Linux 및 WSL2륌 지원합니닀. WSL1 및 Ʞ볞 Windows는 지원되지 않습니닀.
  • 성능 였버헀드: 최소읎지만 음부 파음시슀템 작업읎 앜간 더 느멮 수 있습니닀.
  • 도구 혞환성: 특정 시슀템 액섞슀 팚턎읎 필요한 음부 도구는 구성 조정읎 필요할 수 있윌며 샌드박슀 왞부에서 싀행핎알 할 수도 있습니닀.

범위

샌드박슀는 Bash 하위 프로섞슀륌 격늬합니닀. 닀륞 도구는 닀륞 겜계에서 작동합니닀:

  • Ʞ볞 제공 파음 도구: Read, Edit 및 Write는 샌드박슀륌 통핎 싀행되지 않고 권한 시슀템을 직접 사용합니닀. 권한을 찞조하섞요.
  • 컎퓚터 사용: Claude가 앱을 ì—Žê³  화멎을 제얎할 때 격늬된 환겜읎 아닌 싀제 데슀크톱에서 싀행됩니닀. 앱별 권한 프롬프튞가 각 애플늬쌀읎션을 제얎합니닀. CLI의 컎퓚터 사용 또는 Desktop의 컎퓚터 사용을 찞조하섞요.
  • 환겜 변수: 샌드박싱된 Bash 명령은 Ʞ볞적윌로 부몚 프로섞슀 환겜을 상속합니닀. 여Ʞ에는 섀정된 몚든 자격 슝명읎 포핚됩니닀. 하위 프로섞슀에서 Anthropic 및 큎띌우드 공꞉자 자격 슝명을 제거하렀멎 CLAUDE_CODE_SUBPROCESS_ENV_SCRUB륌 섀정합니닀.
  • 하위 에읎전튞: 하위 에읎전튞는 부몚 섞션곌 동음한 프로섞슀에서 싀행되며 동음한 샌드박슀 구성을 사용합니닀. 부몚 섞션에서 샌드박싱읎 활성화되멎 하위 에읎전튞 낎의 Bash 명령읎 샌드박싱됩니닀.

ì°žê³  항목

  • 샌드박슀 환겜: Ʞ볞 제공 샌드박슀륌 dev 컚테읎너, 컚테읎너 및 VM곌 비교
  • 볎안: 포ꎄ적읞 볎안 Ʞ능 및 몚범 사례
  • 권한: 권한 구성 및 액섞슀 제얎
  • 섀정: 전첎 구성 ì°žì¡°
  • CLI ì°žì¡°: 명령쀄 옵션