샌드박스

확인 날짜 안내

이 페이지의 Claude Code 내용은 공식 문서 Claude Code 샌드박스(본문 날짜 없음, 서버 Last-Modified 2026-10-20, 수집 2026-10-21) 기준이다. 설정 키·버전 조건은 몇 주 단위로 바뀌므로 고객사 적용 전에 공식 문서를 다시 확인한다. 따라 하는 절차와 설정 예시는 Claude Code 샌드박스 설정하기에 있다.

정의#

Claude Code의 샌드박스(Bash 샌드박스)는 Claude가 내 기기에서 돌리는 셸(용어 사전) 명령 둘레에 운영체제가 강제하는 경계다. 사용자가 그 명령이 닿을 수 있는 파일과 네트워크 도메인을 정하고, 제한은 Bash, PowerShell, Monitor 명령과 그 명령이 시작한 프로세스에 적용된다. 운영체제가 명령 실행 중에 제한을 적용하므로, auto-allow 모드에서는 명령마다 승인을 받지 않고 샌드박스 안 명령을 돌릴 수 있다. 기본으로 꺼져 있고, /sandbox나 sandbox.enabled: true로 켠다. 내부는 오픈소스 @anthropic-ai/sandbox-runtime 패키지로 만든다. Claude Code 샌드박스

원본은 샌드박스가 "위험을 줄이지만 완전한 격리 경계가 아니다"(reduces risk but is not a complete isolation boundary)라고 적고, 단단한 보안 통제로 의존하기 전에 한계를 검토하라고 한다(아래 "한계" 절). Claude Code 샌드박스

권한 규칙·권한 모드와 무엇이 다른가#

샌드박스, 권한 규칙, 권한 모드는 서로 보완하는 층이다. Claude Code 샌드박스

• /sandbox는 권한 모드가 아니다. 샌드박스의 auto-allow 모드는 샌드박스 경계가 명령을 가두기 때문에 Bash 명령을 승인하고, 자동 모드는 분류기가 동작을 검토한다. 둘은 독립적으로 돌고 함께 쓸 수 있다(예외는 아래 "샌드박스 모드" 절). Claude Code 샌드박스
• 권한 규칙의 경로·도메인과 샌드박스 설정의 경로·도메인은 최종 샌드박스 구성으로 합쳐진다. 예를 들어 Edit allow 규칙은 sandbox.filesystem.allowWrite처럼 쓰기 권한을 주고, WebFetch(domain:...) allow 규칙은 샌드박스 허용 도메인에 들어간다. Claude Code 샌드박스 → Claude Code 권한 규칙 문법
• 공식 권한 문서는 Bash 규칙이 명령 텍스트를 맞출 뿐이라 Bash(curl *) deny가 /usr/bin/curl이나 sh -c 'curl …'을 막지 않고, Read·Edit deny가 grep -r이나 임의 하위 프로세스에 닿지 않으므로, 모든 프로세스를 OS 수준에서 막으려면 샌드박스를 켜라고 한다. 프롬프트 인젝션이 Claude의 판단을 우회해도 샌드박스 제한은 남으므로 둘을 함께 쓰라고 한다. Claude Code 권한 설정

무엇을 제한하나: 기본값#

근거: Claude Code 샌드박스

• 내장 자격 증명 차단 목록은 없다. 적은 파일과 변수만 막힌다. Claude Code 샌드박스
• 연결된 git worktree에서는 커밋이 ref·index를 고칠 수 있도록 메인 저장소의 공유 .git에도 쓰기를 허용한다. 그 안의 hooks/와 config는 여전히 거부된다. Claude Code 샌드박스
• permissions.blockReadsOutsideWorkingDirectories를 켜면 샌드박스 명령도 홈 디렉터리와 사용자 파일 디렉터리 읽기를 잃는다(예외 경로와 적용되지 않는 경우는 settings reference에 있다). Claude Code 샌드박스

두 층: 파일 격리와 네트워크 격리#

샌드박스는 독립된 두 층으로 이뤄진다. 파일 격리는 읽고 쓸 경로를, 네트워크 격리는 닿을 도메인을 정한다. 원본 경고: 네트워크 격리가 없으면 장악된 에이전트가 SSH 키 같은 민감한 파일을 빼낼 수 있고, 파일 격리가 없으면(느슨한 정책이든 파일 층을 끈 경우든) 시스템 자원에 백도어를 심어 네트워크 접근을 얻을 수 있다. 그래서 기본값을 넓힐 때는 allowWrite 경로, 넓은 allowedDomains 항목, excludedCommands 예외가 다른 쪽 제한을 무르지 않는지 확인하라고 한다. Claude Code 샌드박스

네트워크 격리가 실제로 하는 일. Linux·WSL2에서는 명령이 네트워크와 연결되지 않은 별도 네트워크 namespace에서 돌고, macOS에서는 Seatbelt가 샌드박스 프록시로 가는 연결 외에는 막는다. 프록시는 샌드박스 밖 내 기기에서 돌고 HTTP_PROXY·HTTPS_PROXY·ALL_PROXY 등으로 명령을 그쪽으로 보낸다. 그래서 결과가 도구마다 다르다. Claude Code 샌드박스

• 프록시 변수를 읽는 도구(curl, npm, HTTPS git 등): 호스트가 허용되면 연결된다. 포트 없이 적은 allowedDomains 항목은 그 호스트의 모든 포트를 연다.
• 프록시 변수를 무시하는 도구(그냥 ssh, 대부분의 데이터베이스 드라이버 등): 허용된 호스트에도 연결하지 못한다.
• TCP가 아닌 것(UDP, QUIC 위의 HTTP/3, ping 같은 ICMP): 샌드박스를 나가지 못한다.
• 허용 목록을 통과한 호스트 이름이 로컬 주소(루프백, 169.254.169.254 클라우드 메타데이터 같은 link-local, 내 기기 주소)로만 풀리면 프록시가 연결을 거부한다. localhost·*.localhost는 루프백으로 풀려도 된다. 이 검사는 호스트 이름에만 적용되고, IP 주소 연결과 사내 상위 프록시로 보내는 연결에는 적용되지 않는다(v2.1.284 전에는 이 검사가 없었다).

보호 경로: 쓸 수 있는 디렉터리 안에서도 막히는 파일#

쓰기가 허용된 디렉터리 안에서도 Claude Code가 설정과 코드를 읽어 들이는 파일은 쓰기가 거부된다. 그런 파일을 고칠 수 있는 명령은 자기에게 권한을 주거나, 샌드박스 밖에서 도는 훅·MCP 서버를 더할 수 있기 때문이다. 이 목록은 이미 돌고 있는 명령에 적용되고, 권한 시스템의 보호 경로(도구가 돌기 전 승인 판단)와는 별개다. Claude Code 샌드박스

• 작업 디렉터리와 그 위 디렉터리: .claude 설정 파일, .claude/skills·agents·commands·hooks, .mcp.json, .claude/workflows·.claude/scheduled_tasks.json 같이 Claude Code가 스스로 돌리는 파일
• 작업 디렉터리에서만: .bashrc·.zshrc 같은 셸 시작 파일, .gitconfig, .vscode·.idea, .git 안의 hooks·config
• 작업 디렉터리를 bare git 저장소로 바꿀 파일: 최상위 HEAD·objects·refs 등. Linux·WSL2에서는 샌드박스 명령이 도는 동안 생긴 최상위 HEAD 파일이나 objects·refs 디렉터리를 지운다
• ~/.claude(또는 CLAUDE_CONFIG_DIR)의 대부분, ~/.claude.json, .credentials.json

예외를 줄 방법은 없다. 이 경로를 덮는 allowWrite나 Edit allow 규칙도 보호를 풀지 못하고, 끄는 유일한 방법은 모든 경로의 파일 격리를 끄는 filesystem.disabled다. Claude Code 샌드박스

운영체제별 차이#

근거: Claude Code 샌드박스

• WSL1에서는 Sandboxing requires WSL2가 뜬다. WSL2로 올리거나 샌드박스 없이 돌린다. Claude Code 샌드박스
• Ubuntu 24.04 이상은 기본 AppArmor 정책이 bubblewrap의 user namespace 생성을 막을 수 있어 bwrap 전용 프로필이 필요하다(절차는 Claude Code 샌드박스 설정하기). Claude Code 샌드박스
• WSL2에서 Windows 실행 파일(cmd.exe, powershell.exe, /mnt/c/ 아래 파일)을 띄우는 것은 Unix 소켓을 거치므로 소켓 설정을 따른다. 그 소켓을 막으려면 선택 사항인 seccomp 필터가 설치돼 있어야 한다. Claude Code 샌드박스

샌드박스 모드: 묻는가, 묻지 않는가#

두 모드 모두 같은 파일·네트워크 제한을 강제하고, 다른 것은 샌드박스 안 명령을 자동 승인하느냐뿐이다. Claude Code 샌드박스

• auto-allow: 샌드박스 안에서 도는 명령은 묻지 않고 승인한다. 그래도 다음은 남는다: Bash deny 규칙에 맞는 형태의 명령은 막힌다, 치명 경로를 겨냥한 것으로 인식된 rm·rmdir은 일반 권한 흐름을 탄다, Bash(git push *) 같은 내용 지정 ask 규칙은 묻는다, Monitor 명령은 자동 승인되지 않는다. 맨 Bash(또는 Bash(*)) ask 규칙은 샌드박스 명령에서 건너뛰지만 plan 모드에서는 건너뛰지 않는다. FOO=bar npm test, make CC=clang, eval "ls"처럼 실제 실행 프로그램이 바뀔 수 있는 명령은 샌드박스 안에서 돌되 일반 권한 흐름을 탄다. Claude Code 샌드박스
• auto-allow는 권한 모드와 독립적이라, Manual 모드에서도 샌드박스 경계 안의 파일을 고치는 Bash 명령은 묻지 않고 돈다(파일 편집 도구는 물을 때도). 예외는 셋이다: plan 모드, 명령별 허용 도메인을 단 자동 모드 명령, 자동 모드의 서버 측 분류기 검토. Claude Code 샌드박스
• regular permissions: 샌드박스 안이라도 모든 Bash 명령이 일반 권한 흐름을 탄다. 통제는 더 많고 승인도 더 많다. Claude Code 샌드박스
• 설정 키는 sandbox.autoAllowBashIfSandboxed(기본 true)다. Claude Code 설정 키 전체 레퍼런스 → Claude Code 설정 키 레퍼런스

무엇이 샌드박스 밖에서 도나#

도구와 프로세스(항상 밖):

• 내장 파일·웹 도구(Read, Edit, Write, WebFetch, WebSearch)는 권한 규칙을 따른다. denyRead 항목은 Read 도구를 막지 않고, allowedDomains는 WebFetch를 제한하지 않는다. Claude Code 샌드박스 → Claude Code 권한 규칙 문법
• Claude Code가 시작하는 다른 프로세스: 명령 훅, 로컬 MCP 서버, 플러그인 monitor, LSP 서버, 상태 줄 명령, apiKeyHelper는 사용자의 전체 권한으로 돈다. 플러그인 중 자기 코드를 Claude Code 안에서 돌리는 mod(플러그인)가 시작한 프로세스도 샌드박스 밖에서 돈다. Claude Code 샌드박스
• 컴퓨터 사용(computer use)은 격리된 환경이 아니라 실제 데스크톱에서 돌고, 앱마다 권한 확인 창이 막는다. Claude Code 샌드박스

셸 명령인데 밖에서 도는 경우(설정에 따라):

1. 사용자가 직접 친 명령: ! 셸 모드에 친 명령은 대부분의 세션에서 샌드박스 밖에서 돈다. 예외는 백그라운드 세션(strict sandbox mode가 셸 모드 명령도 덮음)과 CLAUDE_CODE_SUBPROCESS_ENV_SCRUB을 설정한 Linux 세션(모든 명령이 샌드박스 안)이다. v2.1.260 전에는 strict sandbox mode가 모든 세션의 셸 모드 명령을 샌드박스에 넣었다. 그래서 샌드박스가 도는지 확인할 때 !로 직접 치면 시험이 되지 않는다. Claude Code 샌드박스
2. 제외 명령(excludedCommands): 맞는 명령은 파일 제한도 네트워크 프록시도 없이 사용자의 전체 권한으로 돈다. 맞추는 기준은 Claude가 보내는 명령 줄의 텍스트이고, 호출 안의 모든 명령이 맞아야 하며, 리디렉션·cd·$(...)가 있으면 호출 전체가 샌드박스에 남는다. 인터프리터나 작업 디렉터리 안의 스크립트를 덮는 패턴을 쓰면 Claude가 그 파일을 고친 뒤 샌드박스 밖에서 돌릴 수 있다. settings reference는 이것을 "a convenience, not a security boundary"라고 적는다. Claude Code 샌드박스, Claude Code 설정 키 전체 레퍼런스
3. 샌드박스 밖 재시도: 샌드박스 안에서 실패한 명령을 Claude가 분석해 dangerouslyDisableSandbox 파라미터로 다시 돌리자고 할 수 있다. 대화형 터미널 세션에서 승인 주체는 권한 모드가 정한다. Claude Code 샌드박스

근거: Claude Code 샌드박스

• 명령에 맞는 allow 규칙(예: Bash(curl *))은 재시도도 승인해, 명령이 묻지 않고 샌드박스 밖에서 돈다. Bash(dangerouslyDisableSandbox:true) ask 규칙을 두면 자동 모드와 bypassPermissions에서도 재시도마다 묻고, 이 규칙은 맞는 allow 규칙보다 앞선다. Claude Code 샌드박스
• allowUnsandboxedCommands: false(strict sandbox mode)는 dangerouslyDisableSandbox를 무시하게 해 재시도를 닫는다. 그래도 excludedCommands에 맞는 명령은 밖에서 돌고, 샌드박스가 아예 못 뜨는 경우는 failIfUnavailable을 따로 켜야 막힌다. Claude Code 샌드박스

샌드박스가 못 뜰 때#

기본값에서는 의존성이 없거나 플랫폼이 지원되지 않아 샌드박스가 못 뜨면 Claude Code가 샌드박스 없이 명령을 돌린다. sandbox.failIfUnavailable: true로 두면 시작 때 종료한다. 원본은 샌드박스를 보안 관문으로 요구하는 관리 배포가 이 설정을 쓸 수 있다고 하고, Windows 네이티브 기기에서는 이 설정 때문에 Claude Code가 시작 때 종료한다고 적는다. Claude Code 샌드박스 → Claude Code 관리자 권한 통제

서브에이전트·백그라운드 세션#

• Claude Code 서브에이전트는 부모 세션과 같은 프로세스에서 같은 샌드박스 구성으로 돈다. 부모 세션에서 샌드박스가 켜져 있으면 서브에이전트의 Bash 명령도 샌드박스 안에서 돈다. Claude Code 샌드박스
• 백그라운드 세션은 자기 프로세스에서 돌고, 그 세션의 설정이 샌드박스를 켤 때 Bash 명령이 샌드박스에 들어간다. Claude Code 샌드박스

조직 강제: 관리자 필수 샌드박스#

managed settings(또는 --settings)의 allowUnsandboxedCommands: false나 managed의 allowManagedDomainsOnly: true가 적용되는 동안 샌드박스는 관리자 필수가 된다. 이 설정들은 샌드박스를 켜지 않으므로 enabled도 함께 둔다. 관리자 필수일 때 Claude Code는 샌드박스를 느슨하게 하는 설정을 managed·--settings·개발자의 ~/.claude/settings.json에서만 받고, 저장소의 .claude/settings.json·.claude/settings.local.json에 든 excludedCommands·allowedDomains·allowWrite 같은 설정은 무시한다(v2.1.285 이상. v2.1.282~v2.1.284는 저장소의 excludedCommands만 무시). 개발자 자신의 user·--settings 설정은 managed 전용 잠금이 없는 한 계속 적용되고, 대부분은 그런 잠금이 없다. 무시되는 설정 전체 표와 배포 예는 Claude Code 샌드박스 설정하기, 조직 관점은 Claude Code 관리자 권한 통제에 있다. Claude Code 샌드박스

한계#

원본이 "Security limitations"로 든 것: Claude Code 샌드박스

• 네트워크 필터링: 허용 여부는 도메인 단위다. 내장 프록시는 기본으로 TLS를 풀어 보지 않아 암호화된 내용은 검사하지 않는다. 실험 기능 network.tlsTerminate는 자격 증명 mask 치환을 위해 TLS를 풀지만 내용 필터링을 더하지 않는다. 허용 목록에 신뢰할 도메인만 두는 것은 사용자의 책임이다. github.com 같은 넓은 도메인 허용은 데이터 유출 경로가 될 수 있고, 프록시가 클라이언트가 대는 호스트 이름으로 판단하므로 domain fronting 같은 기법으로 허용 목록 밖에 닿을 가능성이 있다. 더 강한 보장이 필요하면 TLS를 풀어 검사하는 사용자 프록시를 두라고 한다.
• Unix 소켓을 통한 권한 상승: allowUnixSockets가 시스템 서비스 접근을 열 수 있다. 예: /var/run/docker.sock 허용은 사실상 호스트 시스템 접근이다.
• 파일 쓰기 권한 상승: $PATH의 실행 파일 디렉터리, 시스템 설정 디렉터리, .bashrc·.zshrc 같은 셸 설정 파일에 쓰기를 허용하면 다른 보안 맥락에서 코드 실행으로 이어질 수 있다.
• Linux 샌드박스 강도: enableWeakerNestedSandbox는 권한 있는 namespace 없이 Docker 안에서 돌게 해 주지만 보안을 상당히 약하게 하므로 다른 격리가 있을 때만 쓴다.
• macOS Apple Events: allowAppleEvents는 코드 실행 격리를 없앤다. 샌드박스 명령이 다른 앱을 샌드박스 없이 묻지 않고 띄우고, 실행 중인 앱에 AppleScript를 보낼 수 있다(앱별 macOS 자동화 동의 창은 남는다). user·managed·CLI 설정에서만 받고 프로젝트 설정은 켤 수 없다.

같은 원본의 사용자 프록시 절(Custom proxy configuration)도 경고한다: network.httpProxyPort·socksProxyPort로 내 기기의 사용자 프록시를 쓰면, 포트가 적용되는 순간 그 프록시가 보내진 모든 트래픽의 필터링을 맡고 allowedDomains·deniedDomains·strictAllowlist·확인 창·로컬 주소 검사는 그 트래픽에 적용되지 않는다. 포트를 하나만 두면 다른 쪽 프록시의 도메인 목록이 사용자 프록시를 거친 연결을 제한하지 못한다. v2.1.285부터는 관리자 필수 샌드박스나 네트워크 잠금이 있을 때 저장소 파일이 포트를 정하지 못한다(세부는 Claude Code 샌드박스 설정하기). Claude Code 샌드박스

다른 도구에서#

• Antigravity CLI (2026-10-21 기준): 서브에이전트는 부모의 허용된 터미널 명령 접두사, 파일 읽기·쓰기 범위, 샌드박스 설정을 물려받는다. frontmatter commandExecutionPolicy와 물려받은 샌드박스 설정이 다를 때 어느 쪽이 이기는지는 원본에 없다. Antigravity 서브에이전트 문서 → 서브에이전트
• Codex: 승인·샌드박스 문서는 이 사이트에서 아직 다루지 않는다. Codex

같은 말, 다른 뜻#

• 이 페이지는 "에이전트가 돌리는 명령 둘레의 OS 수준 경계"를 다룬다. Anthropic의 2024년 에이전트 설계 글이 권하는 "샌드박스 환경에서의 폭넓은 시험"(extensive testing in sandboxed environments)은 실제 운영 전에 격리된 환경에서 시험하라는 권고로, 특정 제품 기능을 가리키지 않는다. 효과적인 에이전트 만들기 → 에이전트 시스템 패턴 고르기, 워크플로와 에이전트
• 컨테이너·dev container·VM처럼 Claude Code 프로세스 전체를 감싸는 격리는 원본이 "Sandbox environments" 문서로 넘긴다. 원본은 샌드박스 밖에서 도는 도구·프로세스까지 한 경계에 넣으려면 Claude Code(로컬 모드)를 sandbox runtime이나 dev container 안에서 돌리라고 한다. Claude Code 샌드박스

관련#

• 설정 절차와 원문 예시: Claude Code 샌드박스 설정하기
• 키별 타입·기본값·Scope: Claude Code 설정 키 레퍼런스
• 명령 텍스트 규칙과의 분담: Claude Code 권한 규칙 문법
• 모드와 함께 고르기: 권한 모드, Claude Code 권한 모드 고르기
• 조직 강제: Claude Code 관리자 권한 통제, managed settings
• 도구: Claude Code