샌드박스 — 울타리 치고 맡기기

클로드에게 일을 맡길수록 “이 명령어를 실행해도 될까요?”라는 허락 질문이 늘어납니다. 매번 다 허용하자니 불안하고, 매번 확인하자니 번거롭습니다. 샌드박스는 이 딜레마를 푸는 기능입니다. 명령어가 닿을 수 있는 범위를 미리 울타리로 막아 두고, 그 안에서는 묻지 않고 실행하게 합니다. 울타리를 먼저 치는 것은 AI가 어떤 명령이 위험한지 스스로 가리지 못하기 때문입니다. 이 약점이 왜 생기는지는 「AI는 자기가 한 일을 스스로 판단하지 못합니다」 페이지에서 설명합니다.

샌드박스란

샌드박스(sandbox)는 아이가 마당의 모래놀이 상자 안에서만 놀게 하는 것과 같습니다. 클로드가 어떤 명령어를 실행하든, 울타리 밖의 파일에 쓰거나 허락하지 않은 인터넷 주소에 연결하지는 못합니다. 울타리는 두 가지입니다.

• 파일 울타리 — 어떤 폴더에 쓰고 읽을 수 있는지 정합니다. 기본값으로는 지금 작업 중인 폴더와 임시 폴더에만 쓸 수 있고, 읽기는 따로 막아 두기 전까지 열려 있습니다.
• 네트워크 울타리 — 어떤 인터넷 주소에 연결할 수 있는지 제한합니다. 수동 모드에서는 처음 보는 주소마다 허락을 묻습니다. 권한 모드가 자동 모드일 때는 묻지 않습니다. 클로드가 명령을 실행하려 할 때 필요한 주소를 함께 적고, 또 하나의 AI가 명령과 주소를 한꺼번에 심사합니다. 승인된 주소는 그 명령 하나가 실행되는 동안에만 열리고, 적지 않은 주소는 막힙니다.

이 울타리는 클로드가 아니라 운영체제(컴퓨터의 기본 관리자)가 직접 지킵니다. 명령어가 이름에서 짐작되는 것과 다른 일을 하더라도 울타리를 넘지 못합니다. 그래서 허락 질문을 줄여도 안전합니다. 일상 작업의 속도를 높이고 싶을 때, 사람이 지켜보지 않는 자동 실행을 걸어 둘 때, 믿을 수 없는 남의 코드를 다룰 때 특히 쓸모가 큽니다.

권한과의 관계 — 문 앞과 방 안

권한은 “이 사람을 방에 들여보낼까”를 문 앞에서 결정하는 일입니다. 샌드박스는 “일단 들어온 사람이 방 안에서 어디까지 손댈 수 있나”를 방 자체가 미리 정해 두는 일입니다. 권한 규칙은 도구가 실행되기 전에 판단하고 모든 도구에 적용됩니다. 샌드박스는 실행된 명령어가 닿는 범위를 운영체제 수준에서 제한합니다. 둘은 다른 층이라 두 겹으로 함께 작동합니다.

켜기 — /sandbox

클로드 코드 입력창에 아래 명령어를 치면 설정 화면이 열립니다.

/sandbox

기본 화면에는 탭이 세 개 있습니다. Mode는 샌드박스 안 명령어를 어떻게 승인할지 정하고, Overrides는 울타리 밖 실행을 허용할지 정하고, Config는 지금 적용된 설정을 보여 줍니다. 컴퓨터별로 되고 안 되는 것은 다음과 같습니다. 표에 나오는 WSL2는 윈도우 안에서 리눅스를 돌리는 기능입니다.

맥은 바로 됩니다. 리눅스·WSL2에서는 우선 /sandbox를 실행해 봅니다. 준비물이 빠져 있으면 화면에 Dependencies(준비물) 탭이 떠서 무엇이 빠졌는지 알려 줍니다. 안내대로 설치했으면 클로드 코드를 다시 켠 뒤 /sandbox를 다시 실행합니다. 윈도우를 쓴다면 WSL2에서 클로드 코드를 실행합니다. 그 준비 절차와 bubblewrap·socat 설치 명령 한 줄은 「윈도우에서 쓰기」 페이지에 단계별로 적었습니다.

Mode 탭의 선택지는 둘입니다. 자동 허용(auto-allow)은 샌드박스 안 명령어를 묻지 않고 바로 실행하고, 일반 권한(regular permissions)은 울타리 안이라도 평소처럼 매번 묻습니다. 어느 쪽이든 파일·네트워크 울타리는 똑같이 지켜집니다. 자동 허용이어도 못 쓰게 막아 둔 명령어는 늘 거부되고, 중요한 경로를 지우는 rm 명령어는 반드시 허락을 묻습니다.

울타리 조정 — 넓히기와 비밀 지키기

기본 울타리로 부족하면 조정합니다. 설정 항목 이름을 외울 필요 없이, 클로드에게 “샌드박스에서 ~/.kube 폴더에도 쓸 수 있게 열어 줘”처럼 말로 시키는 방법이 먼저입니다. 여기 나온 ~/.kube는 어떤 도구가 자기 설정을 넣어 두는 폴더로, 예시일 뿐입니다. 그 자리에 내가 열어 주려는 폴더 이름을 넣으십시오. 아래 설정 파일은 원리만 알아 두면 됩니다.

# settings.json — 두 폴더에 쓰기를 추가로 허용하는 예
{
  "sandbox": {
    "enabled": true,
    "filesystem": { "allowWrite": ["~/.kube", "/tmp/build"] }
  }
}

이렇게 필요한 경로만 콕 집어 여는 방식이, 도구를 통째로 울타리 밖으로 빼는 것보다 안전합니다. 반대로 좁히는 쪽도 중요합니다. 울타리 안에서 실행되는 명령어는 기본적으로 컴퓨터 전체를 읽을 수 있어서, 클라우드 접속 열쇠 같은 비밀 파일도 그냥 두면 읽힙니다. 두 가지 보호 방법이 있습니다.

• 차단(deny) — 지정한 비밀 파일을 읽지 못하게 막고, 비밀 환경 변수(프로그램이 켜질 때 참고하는 짧은 설정값)는 실행 전에 아예 지웁니다. 확실하지만, 그 값이 있어야 작동하는 도구는 함께 멈춥니다.
• 가리기(mask) — 명령어에게는 가짜 값만 보여 주고, 승인된 주소로 실제 나갈 때만 진짜 값으로 바꿔치기합니다. 로그에 진짜 비밀이 남지 않으면서도 인증은 제대로 됩니다.

막힌 명령어의 비상구

샌드박스와 맞지 않는 명령어, 허용하지 않은 주소에 연결해야 하는 명령어는 울타리 안에서 아예 실행되지 않습니다. 이때 샌드박스를 꺼 버릴 필요는 없습니다. 명령어가 울타리 때문에 실패하면 클로드가 원인을 살펴본 뒤, dangerouslyDisableSandbox(이 명령만 울타리 밖에서 실행하겠다는 표시)를 붙여 한 번만 다시 실행할 수 있습니다.

울타리 밖에서 실행되는 명령어는 자동 허용을 건너뛰고 평소의 허락 절차를 그대로 거칩니다.

알아 둘 한계

샌드박스는 위험을 크게 줄이지만 완벽한 차단벽은 아닙니다.

• 가두는 범위는 터미널 명령어(Bash)뿐입니다 — 파일 읽기·편집 도구, 외부 연결(MCP) 서버, 훅은 울타리 밖에서 평소대로 작동합니다. 파일 도구는 권한 시스템이 따로 지킵니다.
• 내가 직접 친 명령은 대개 울타리 밖에서 실행됩니다 — 입력창 맨 앞에 !를 붙여 직접 친 명령은 클로드 코드 밖의 터미널에서 친 명령과 똑같이 다뤄져, 대개 울타리 밖에서 실행됩니다. allowUnsandboxedCommands를 false로 두어 울타리 밖 실행을 막아 둔 경우에도 마찬가지입니다. 그래서 울타리가 제대로 서 있는지 시험할 때는 직접 치지 말고 클로드에게 실행을 시킵니다.
• 네트워크 내용은 검사하지 않습니다 — 어느 주소에 연결하는지만 봅니다. 넓은 주소를 통째로 허용하면 그 틈으로 정보가 빠져나갈 수 있으니, 꼭 필요한 주소만 좁게 허용합니다.
• 넓게 열수록 위험이 커집니다 — 시스템 폴더나, 터미널을 켤 때 자동으로 읽는 설정 파일에 쓰기를 허용하면 울타리를 빠져나가는 통로가 될 수 있습니다.
• 모델에 보내는 내용은 그대로입니다 — 샌드박스를 켜도 내가 적어 넣은 지시(프롬프트)와 클로드가 읽은 파일은 평소처럼 전송됩니다. 샌드박스는 명령어가 닿는 범위를 제한하는 기능이지 데이터 전송을 막는 기능이 아닙니다.

사람 없이 완전 자동으로 돌리거나 믿을 수 없는 코드를 다룰 때는, 클로드 코드 전체를 컨테이너·가상 머신(지금 쓰는 컴퓨터와 따로 떼어 둔 공간) 같은 더 두꺼운 울타리로 감싸는 방식이 따로 있습니다. 이 방식은 전문가 영역이라 이 가이드에서는 있다는 사실만 알아 두면 됩니다.

이 페이지는 Claude Code v2.1.216을 기준으로 썼습니다. 최신 사항은 공식 안내에서 확인하십시오.