Claude Code 상세 사용법 65: Bash 샌드박스로 명령 경계 좁히기 | DAKER 커뮤니티

Claude Code 상세 사용법 65: Bash 샌드박스로 명령 경계 좁히기

Claude Code에서 테스트와 빌드를 자주 돌리면 Bash 승인 prompt가 많아집니다. 공식 문서의 Bash sandbox는 각 명령과 자식 프로세스를 파일 시스템, 네트워크 경계 안에서 실행해 승인 피로를 줄이는 기능입니다. 권한을 없애는 기능이 아니라, 클로드 코드가 만질 수 있는 경계를 운영체제 수준으로 좁히는 장치입니다.

Mermaid 흐름으로 보는 실행 구조

Mermaid source:
flowchart TD
  A[Claude가 Bash 명령 제안] --> B{/sandbox 설정 확인}
  B --> C{샌드박스에서 실행 가능}
  C -->|예| D[파일과 네트워크 경계 안에서 실행]
  C -->|아니오| E[일반 권한 흐름으로 fallback]
  D --> F{새 네트워크 도메인}
  F -->|예| G[도메인 승인 요청]
  F -->|아니오| H[결과와 로그 검토]

`/sandbox`부터 연다

세션에서 아래 slash command를 실행하면 Mode, Overrides, Config 탭을 볼 수 있습니다. Linux나 WSL2에서 필수 패키지가 없으면 Dependencies 탭만 보일 수 있습니다.

/sandbox

Mode에서 auto-allow를 고르면 샌드박스 안에서 실행 가능한 Bash 명령은 prompt 없이 실행됩니다. regular permissions를 고르면 sandbox 경계는 유지하되 기존 승인 흐름을 유지합니다. 처음에는 regular로 시작하고, 테스트 루프가 안정되면 auto-allow로 올리는 편이 안전합니다.

플랫폼별 준비가 다르다

macOS는 내장 Seatbelt framework를 사용하므로 별도 설치가 없습니다. Linux와 WSL2는 bubblewrap과 socat가 필요합니다.

sudo apt-get install bubblewrap socat
sudo dnf install bubblewrap socat

문서 기준 seccomp filter는 선택 항목이며 Unix domain socket 차단을 보강합니다. 필요하면 아래 runtime을 설치합니다.

npm install -g @anthropic-ai/sandbox-runtime

기본 경계를 이해한다

기본적으로 sandboxed command는 작업 디렉터리와 session temp directory에만 쓸 수 있습니다. 새 network domain에 접근하면 처음에는 승인 prompt가 뜹니다. 즉 npm test, pytest, rg, git status 같은 로컬

루프에는 잘 맞지만, 임의의 외부 API 호출이나 parent directory 쓰기는 의도적으로 막힐 수 있습니다.

user settings에서 모든 프로젝트에 켤 수 있고, project local settings는 현재 프로젝트에만 적용됩니다.

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

failIfUnavailable은 sandbox가 없으면 hard fail하게 만드는 옵션입니다. 개인 실험에서는 경고만 보고 넘어가도 되지만, 조직 표준이면 hard fail이 맞습니다.

permissions와 같이 설계한다

샌드박스는 Bash 실행 환경을 좁힙니다. permissions는 도구 사용 여부를 결정합니다. 예를 들어 Bash(curl *)을 deny하면 sandbox 여부와 상관없이 막힙니다. 반대로 sandbox가 켜져 있어도 민감한 command는 ask rule로 남겨둘 수 있습니다.

{
  "permissions": {
    "ask": ["Bash(git push *)"],
    "deny": ["Bash(curl * | bash *)"]
  }
}

이 조합이 실무에서 중요합니다. 샌드박스만 켜고 모든 명령을 믿는 것이 아니라, 위험 명령은 permission rule로 별도 경계를 둡니다.

실패 모드

첫째, Dependencies 탭만 보이면 Linux/WSL2 의존성이 빠진 것입니다. 둘째, 테스트가 네트워크를 쓰면 새 domain 승인 때문에 멈출 수 있습니다. 셋째, command가 sandbox와 호환되지 않으면 일반 permission flow로 fallback될 수 있습니다. 넷째, native Windows는 지원하지 않으므로 WSL2 안에서 실행해야 합니다.

선임 엔지니어 takeaways

Claude Code의 Bash sandbox는 개발 생산성을 위해 보안을 포기하는 기능이 아닙니다. 반복되는 테스트 자동화와 AI 코딩 루프를 더 오래 돌리기 위해 명령의 피해 반경을 줄이는 기능입니다. 클로드 코드, agentic coding, MCP 도구, CLI 자

동화를 함께 운영한다면 세 층을 분리하세요. permission mode는 승인 빈도, sandbox는 실행 경계, settings는 팀 표준입니다. 이 세 층을 나눠야 바이브코딩이 운영 가능한 개발 워크플로우가 됩니다.

참고: Anthropic Claude Code llms.txt, Bash sandbox, permissions, security 문서를 2026-06-16 Asia/Seoul 기준으로 확인했습니다.