AI 코딩 · 2026년 7월 11일 · 약 8분

Claude Code 샌드박싱 설정법: 초보자를 위한 안전한 AI 코딩 체크리스트

Claude Code의 /sandbox, Bash 샌드박스, dev container, VM을 언제 골라야 하는지 초보자 기준으로 정리한 안내서입니다. 파일 접근, 네트워크 허용, credential 보호, --dangerously-skip-permissions 실행 전 체크리스트까지 한 번에 볼 수 있어요.

• Claude Code
• Claude Code 샌드박싱
• AI 코딩 보안
• Bash sandbox
• dev container
• AI 코딩 체크리스트

출처: Anthropic Engineering, Claude Code Docs

Claude Code로 테스트를 돌리거나 파일을 고치다 보면 “이 명령까지 자동으로 실행해도 괜찮을까?” 하고 멈칫할 때가 있죠. 그럴 때는 먼저 /sandbox를 열어 현재 경계를 확인하세요. 샌드박스가 모든 도구를 같은 범위로 묶어 주지는 않습니다. 그래서 파일 접근, 네트워크 허용, 토큰 범위를 함께 줄이는 쪽이 현실적입니다.

핵심 키워드

• Claude Code 샌드박싱 설정법
• Claude Code /sandbox 사용법
• Claude Code Bash sandbox
• Claude Code dev container 보안
• AI 코딩 에이전트 안전 체크리스트
• --dangerously-skip-permissions 주의점

공식 출처로 확인한 내용

• Anthropic Engineering은 Claude Code sandboxing이 파일시스템 격리와 네트워크 격리를 함께 다룬다고 설명합니다.
• Claude Code 문서는 /sandbox가 Claude Code 세션 안에서 Bash 샌드박스 설정 패널을 여는 기능이라고 안내합니다.
• Claude Code 문서 기준으로 macOS는 Seatbelt, Linux와 WSL2는 bubblewrap 기반으로 Bash 명령과 자식 프로세스 경계를 적용합니다.
• Claude Code 문서는 native Windows에서 Bash sandbox를 지원하지 않으며, Windows 사용자는 WSL2, container, VM을 고려해야 한다고 안내합니다.
• Bash sandbox는 Bash와 그 자식 프로세스에 적용됩니다. built-in file tools, MCP servers, hooks 전체를 같은 경계 안에 넣으려면 sandbox runtime, dev container, container, VM 같은 선택지를 따로 봐야 합니다.
• Claude Code 문서는 @anthropic-ai/sandbox-runtime을 beta research preview로 소개합니다. built-in sandboxed Bash tool 자체를 beta라고 단정하면 안 됩니다.

Claude Code 샌드박싱이 하는 일

Anthropic은 Claude Code 샌드박싱을 파일시스템 격리와 네트워크 격리의 조합으로 설명합니다. 파일시스템 격리는 Claude가 읽거나 쓸 수 있는 위치를 제한하고, 네트워크 격리는 명령이 접속할 수 있는 서버를 제한합니다. 둘 중 하나만 있으면 위험이 남습니다. 네트워크가 너무 넓으면 읽을 수 있는 비밀 파일을 외부로 보낼 수 있고, 파일 쓰기가 너무 넓으면 시스템 설정이나 실행 파일을 바꿔 다른 경로를 만들 수 있습니다.

Claude Code의 Bash sandbox는 명령 실행을 더 자주 자동화하고 싶을 때 쓰는 경량 보호 장치입니다. 기본적으로 작업 폴더와 세션 임시 폴더에는 쓸 수 있지만, 그 밖의 위치를 수정하려면 제한을 받습니다. 새 네트워크 도메인이 필요하면 처음에 승인을 요구하거나, 설정에 따라 미리 허용한 도메인만 접근하게 만들 수 있습니다.

/sandbox로 먼저 확인할 것

Claude Code 세션에서 /sandbox를 실행하면 샌드박스 패널이 열립니다. 여기서 모드, 우회 실행 허용 여부, 실제 적용된 설정을 볼 수 있습니다. Linux나 WSL2에서 필요한 패키지가 빠져 있으면 Dependencies 탭만 보일 수 있으니, 그 화면부터 확인하면 됩니다.

초보자용 설정 순서

• 1. 프로젝트 폴더에서 Claude Code를 시작합니다. 홈 디렉터리 전체가 아니라 실제 작업 저장소 안에서 시작하는 편이 안전합니다.
• 2. /sandbox를 실행해 현재 OS에서 샌드박스가 가능한지 확인합니다.
• 3. macOS라면 별도 패키지 없이 Seatbelt 기반 샌드박스를 사용할 수 있습니다.
• 4. Linux 또는 WSL2라면 bubblewrap과 socat 설치 여부를 확인합니다.
• 5. 처음에는 auto-allow보다 regular permissions로 시작해 어떤 명령이 제한되는지 봅니다.
• 6. 자주 쓰는 테스트와 빌드 명령이 안정적으로 동작하면 auto-allow를 검토합니다.
• 7. credential 파일과 환경변수는 sandbox.credentials 설정으로 막거나 mask 처리합니다.
• 8. 네트워크 도메인은 필요한 서비스만 좁게 허용합니다. 넓은 wildcard는 마지막 선택지로 남겨두세요.

환경별 선택 기준

Bash sandbox가 덮지 않는 부분

중요한 오해가 하나 있습니다. Claude Code의 Bash sandbox는 Bash 명령과 그 자식 프로세스에 적용됩니다. built-in Read, Edit, Write 같은 파일 도구는 권한 시스템으로 제어되고, MCP 서버와 hooks는 별도 프로세스로 호스트에서 움직일 수 있습니다. 그래서 “Bash sandbox를 켰으니 세션 전체가 격리됐다”고 보면 안 됩니다.

세션 전체를 더 넓게 감싸고 싶다면 Claude Code 문서가 비교하는 다른 선택지를 봐야 합니다. sandbox runtime은 Claude Code 프로세스 전체를 감싸는 방향이고, dev container, custom container, VM은 개발 환경 자체를 별도 경계 안에 둡니다. Claude Code on the web은 Anthropic이 관리하는 격리 환경에서 실행되는 선택지로 설명됩니다.

읽기 권한도 따로 줄인다

쓰기 권한이 제한된다고 해서 읽기 위험까지 사라지는 것은 아닙니다. Claude Code 문서는 sandboxed Bash의 기본 읽기 범위가 넓을 수 있고, credential 위치도 설정하지 않으면 노출될 수 있다고 설명합니다. 초보자라면 ~/.ssh, ~/.aws, cloud config, npm token, GitHub token처럼 민감한 파일과 환경변수를 먼저 목록으로 만들고, sandbox.credentials, denyRead, 또는 더 강한 격리 환경으로 막아야 합니다.

파일 접근 설정에서 피할 실수

파일시스템 체크리스트

• 작업 폴더 밖에 있는 ~/.ssh, ~/.aws, cloud config, shell history를 샌드박스가 읽을 수 있는지 확인합니다.
• sandbox.credentials.files로 민감한 파일 경로를 deny 처리합니다.
• 도구가 특정 폴더에 써야 한다면 allowWrite를 최소 경로로만 추가합니다.
• ~/ 전체, /tmp 전체, 시스템 설정 폴더, 실행 파일이 있는 PATH 폴더를 넓게 쓰기 허용하지 않습니다.
• linked git worktree를 쓰는 경우 .git 관련 동작이 어떤 범위에서 허용되는지 확인합니다.
• Claude Code 설정 파일은 샌드박스가 자체 정책을 바꾸지 못하도록 보호된다는 점을 이해하되, 로컬 정책 관리 자체는 사람이 확인합니다.

네트워크와 토큰은 좁게 잡기

네트워크 허용은 “인터넷을 켜느냐 끄느냐”보다 더 세밀하게 봐야 합니다. Claude Code 문서는 sandbox의 네트워크 접근이 외부 proxy를 통해 도메인 기준으로 제어된다고 설명합니다. 기본적으로 새 도메인은 승인 흐름을 거치며, allowedDomains로 미리 허용할 수 있습니다.

주의할 점은 도메인을 넓게 열면 데이터 유출 경로도 넓어진다는 것입니다. 공식 문서도 broad domain 허용이 위험을 만들 수 있고, 기본 proxy가 TLS 내용을 검사하지 않는다고 설명합니다. 초보자는 github.com 전체처럼 크게 여는 대신, 실제 필요한 API host를 좁게 적는 습관을 들이는 편이 좋습니다.

--dangerously-skip-permissions를 쓰기 전 기준

--dangerously-skip-permissions는 이름 그대로 권한 프롬프트를 크게 건너뛰는 선택지입니다. Claude Code 문서는 이 모드에서 per-action review가 사라지므로, container, VM, sandbox runtime, Claude Code on the web처럼 파일 도구, MCP 서버, hooks까지 함께 묶는 외부 경계를 두라고 설명합니다. Bash sandbox만으로 완전한 무인 실행 경계가 된다고 보면 위험합니다.

사용 전 확인 체크리스트

• Claude Code가 root 또는 sudo로 실행되지 않는지 확인합니다.
• 프로젝트 폴더만 쓰기 가능하게 마운트했는지 확인합니다.
• 운영 DB, 결제, 배포, cloud admin token이 컨테이너 안에 없는지 확인합니다.
• 네트워크 egress가 필요한 도메인으로만 제한되어 있는지 확인합니다.
• MCP 서버와 hooks가 같은 격리 경계 안에 들어가는지 확인합니다.
• 세션 로그, credential 폴더, shell history 같은 민감 경로가 노출되지 않는지 확인합니다.
• 처음에는 unattended run이 아니라 짧은 테스트 작업으로 실패 동작을 확인합니다.

복사해서 쓰는 안전 프롬프트

아래 템플릿은 Claude Code에게 작업 범위와 샌드박스 기준을 분명히 알려줄 때 쓸 수 있습니다. 단, 프롬프트는 보조 장치입니다. 실제 보호는 /sandbox, 권한 설정, credential 제한, 네트워크 allowlist로 만들어야 합니다.

오늘 바로 해볼 한 가지

가장 작은 시작은 /sandbox를 켠 뒤 테스트 명령 하나만 돌려보는 것입니다. 예를 들어 npm test, pytest, go test처럼 되돌리기 쉬운 명령을 실행해 보고, 어떤 파일에 쓰려고 하는지와 어떤 도메인에 접속하려는지를 확인하세요. 그다음 credential deny, 좁은 domain allowlist, dev container 필요 여부를 차례로 정하면 됩니다.