샌드박스 정책 구성

에이전트 실행이 샌드박스로 감싸지는지는 서버가 부팅할 때 결정합니다 (--sandbox). 설정 → 서버 → 진단 및 개인정보 보호 아래의 샌드박싱 활성화 토글과 백엔드 선택기는 기기에 저장되는 기본 설정입니다. 샌드박싱 카드의 호스트 탐지는 서버 호스트가 무엇을 감쌀 수 있는지 알려 줍니다.

실행에 닿는 제어는 두 가지이며 이 가이드에서 둘 다 다룹니다: 에이전트가 무엇을 푸시하고, 열고, 접근할 수 있는지 결정하는 설정 → 워크스페이스 → 에이전트 권한의 작업 규칙과, 서버 자체의 --sandbox 플래그입니다.

에이전트 실행을 제약하는 것

에이전트를 붙잡는 것은 여섯 가지입니다. 첫째는 OS 샌드박스이며 유일하게 조건부인 항목입니다 — 나머지 다섯은 모든 호스트에서 유지됩니다.

경계	수행하는 일
OS 샌드박스	macOS에서는 Seatbelt, Linux와 WSL2에서는 bubblewrap입니다. Claude Code CLI, ACP 어댑터, 하네스 `bash` 도구를 감쌉니다. Windows와, `bwrap`과 `socat`이 없는 Linux에는 없습니다
자체 워크트리	모든 대화는 쓰기 시 복사 체크아웃을 받습니다. 원본 체크아웃은 쓰기 거부 경로로 실행에 합류하며, 이를 강제하는 것은 샌드박스입니다
중개된 자격 증명	자격 증명 브로커가 실행별 환경을 발급하고 정리할 때 폐기합니다. 그 안의 GitHub 토큰은 읽을 수는 있어도 푸시할 수는 없습니다. 푸시는 Control Center를 거치며, Control Center가 먼저 푸시 규칙에 묻습니다
동작 가드레일	모든 변경 도구는 자신의 효과 클래스를 선언하고, 가드가 호출이 실행되기 전에 이를 판정합니다. 승인자가 연결되어 있지 않은 `prompt`는 거부됩니다
환경 정리	ACP와 하네스 `bash` 도구는 걸러진 환경을 받습니다. `NoSandboxAdapter`를 통한 Claude Code는 호스트 환경을 그대로 물려받습니다
모드의 도구 표면	읽기 전용 모드는 워크트리를 변경하는 도구를 아예 제거하고, 그래도 산출물을 낼 수 있도록 모드 자체의 출력 동사를 고정합니다

세 가지는 보기보다 약한 채로 남습니다:

내장 하네스만 도구 게이트, 완료 계약, 구조적 모드 규칙을 강제합니다. Claude Code 어댑터는 그렇지 않습니다. 특히 Claude Code는 --dangerously-skip-permissions와 함께 실행되는데, 그렇지 않으면 비대화형 claude -p가 자체 프롬프트에서 영원히 멈추기 때문입니다 — 따라서 Claude의 읽기, 쓰기, 편집 호출은 Control Center가 보지도, 게이트하지도 않으며, bash 명령은 명령줄을 읽는 훅으로만 확인됩니다. 샌드박스가 켜져 있는 곳에서는 샌드박스가 그 주위의 경계입니다.
하네스의 프로세스 내 파일 도구(read, write, edit, apply patch, search, find, search_files)는 서버 프로세스 안에서 실행되므로 어떤 샌드박스 프로필도 이들을 제약하지 않습니다. 샌드박스가 적용된 명령 실행기를 거치는 것은 bash 도구뿐입니다. 그 도구들은 자체 경로 제한과 동작 가드레일로 범위가 정해집니다.
백엔드가 없는 호스트에서는 첫 번째 행이 아예 적용되지 않습니다. ACP와 하네스 bash 도구는 환경 정리와 명령 정책으로 대체되고, Claude Code는 NoSandboxAdapter를 통해 호스트 환경을 물려받습니다. 서버는 시작 로그에서 이 사실을 알립니다. 아래에서 직접 확인하세요.

에이전트가 푸시할 수 있는 것 정하기

git push, GitHub, 티켓팅, 네트워크에 대한 에이전트별 토글은 없습니다. 각각이 작업 규칙입니다:

규칙	내장 기본값	다루는 범위
리모트에 푸시	먼저 묻기	어댑터와 관계없이 GitHub로의 모든 `git push`
풀 리퀘스트 열기	먼저 묻기	`gh pr create`와 풀 리퀘스트 도구
리뷰 게시 또는 병합	먼저 묻기	`gh pr merge`, `gh pr review`, `gh pr comment`, `gh pr close`
외부 트래커에 쓰기	먼저 묻기	Control Center 도구와 `gh issue`를 통한 티켓 쓰기
네트워크 접근	허용	샌드박스에 네트워크가 있는지 여부, 그리고 하네스의 웹 도구

설정 → 워크스페이스 → 에이전트 권한으로 이동합니다
범위 — 워크스페이스, 에이전트, 스페이스 — 를 고르고 규칙의 행에서 허용, 먼저 묻기, 거부 중 하나를 선택합니다

main으로의 푸시를 거부하는 규칙처럼 브랜치로 한정된 푸시 규칙도 적용됩니다: 가드레일을 참고하세요.

점검: 에이전트에게 브랜치를 푸시하라고 요청합니다. 먼저 묻기이면 저장소와 ref를 명시한 승인 요청을 받고, 거부이면 git이 ! [remote rejected] <ref> (Control Center policy: …)를 출력합니다.

각 규칙이 실행에 닿는 방식:

푸시는 실행이 가진 것으로 강제됩니다. 실행의 GitHub 토큰은 콘텐츠를 읽고 풀 리퀘스트를 다룰 수 있는 읽기 전용 GitHub App 설치 토큰입니다. 실행의 git 구성은 모든 GitHub 푸시를 cc_server의 루프백 게이트웨이로 보내며, 게이트웨이는 규칙에 물은 다음에야 에이전트가 결코 볼 수 없는 쓰기 토큰으로 푸시를 전달합니다. 게이트웨이는 워크트리 자체의 저장소나 워크스페이스에 연결된 GitHub 저장소로만 전달합니다. 이는 모든 어댑터에 적용됩니다.
셸에서의 풀 리퀘스트와 이슈는 하네스의 bash 도구와, 훅을 통한 Claude Code의 Bash 도구에서 명령줄로 인식됩니다. 명령을 숨기는 에이전트(스크립트, eval, 직접 API 호출)는 이 검사를 빠져나가지만, 푸시 게이트웨이는 빠져나가지 못합니다.
티켓팅 키는 샌드박스에 절대 놓이지 않습니다. 에이전트는 Control Center의 MCP 도구로 티켓을 쓰며, 그 도구들이 규칙에 묻습니다.
네트워크는 실행이 시작될 때 한 번 결정됩니다. 거부는 샌드박스의 네트워크를 끄고, 허용과 먼저 묻기는 켜 둡니다. 먼저 묻기일 때 하네스의 web_fetch와 web_search 도구는 호출마다 계속 묻습니다. 네트워크가 켜져 있는 동안 GitHub는 항상 이그레스 허용 목록에 있습니다.

에이전트 실행이 샌드박스로 감싸지는지 확인

이를 결정하는 것은 둘이며 둘 다 서버에 있습니다: 호스트가 백엔드를 제공하는지, 그리고 --sandbox가 켜져 있는지입니다. 이 순서대로 확인하세요.

설정 → 서버 → 진단 및 개인정보 보호로 이동합니다
샌드박싱 카드를 읽습니다. 호스트 항목은 지금 보고 있는 머신이 아니라 cc_server가 실행되는 머신입니다. 백엔드 필드에는 네이티브 샌드박스(macOS의 Seatbelt, Linux와 WSL2의 bubblewrap) 또는 격리 없음이 나열됩니다. 적용 중 항목은 서버가 실제로 사용하는 래핑이 아니라 이 기기의 기본 설정입니다.
서버의 시작 로그를 읽습니다. 다음 세 줄 중 정확히 하나를 출력합니다:
- agent sandbox ON에 백엔드 설명이 붙음 — 실행이 감싸집니다
- no OS-native agent sandbox on this host에 해당하는 경우 설치 안내가 붙음 — 실행이 감싸지지 않습니다
- agent sandbox DISABLED by --sandbox off — 의도적인 옵트아웃

GET /healthz는 샌드박스 상태를 보고하지 않으므로, 시작 로그가 확인 수단입니다.

샌드박스를 의도적으로 끄려면 — 프로필이 오작동하는 호스트야말로 이 옵션이 존재하는 이유입니다 — 서버를 --sandbox off로 시작하거나 CC_SERVER_SANDBOX=off를 설정하세요. 기본값은 on이며 on은 “호스트에 백엔드가 있으면 사용한다”는 뜻이지, 결코 “백엔드를 요구한다”는 뜻이 아닙니다.

두 가지 상황에서는 네이티브 샌드박스 래핑을 결코 받지 못합니다. Windows에서는 네이티브 프로브가 언제나 사용 불가를 보고하고 설치할 것도 없습니다 — 에이전트 디스패치는 none을 사용합니다. microvm 백엔드는 별개이며(대화형 터미널과 리그) 자체 런타임에 대한 프로브로 게이트됩니다. Linux와 WSL2에서는 bwrap과 socat이 모두 PATH에 있어야 합니다. 없으면 프로브가 사용 불가를 보고하고 빠진 패키지를 알려 줍니다.

bubblewrap이 설치된 Linux/WSL2에서는 표준 정책의 시크릿 파일 글롭을 에이전트가 나중에 만드는 파일에 대해서는 강제할 수 없습니다. 이런 네이티브 실행은 이제 규칙을 조용히 무시하는 대신 실패합니다. 따라서 부팅 프로브가 긍정적이어도 Linux 디스패치가 시작될 수 있다는 보장은 아닙니다. --sandbox off는 의도적인 비구속 옵트아웃이지, 대체 보안 경계가 아닙니다.

모드가 이미 금지하는 것 알기

모드는 스페이스별로 저장되며 모드 프리셋 계층으로 가드레일 판정기에 입력됩니다. 네 가지 모드 중 셋은 읽기 전용이며, 읽기 전용 모드는 열한 개의 효과 클래스를 곧바로 거부합니다:

모드	워크트리	프리셋이 거부하는 것
Agent (`chat`)	쓰기 가능	없음 — 내장 기본값이 적용됩니다
플랜	읽기 전용	파일 삭제, 워크트리 밖에 쓰기, 커밋, 푸시, PR 열기, 게시 또는 병합, 외부 트래커에 쓰기, 패키지 설치, 프로세스 실행, 워크스페이스 구조 변경, 인클로저 부팅 또는 조작
리뷰	읽기 전용	같은 열한 개. 사용자가 선택할 수 없습니다 — 작성기는 Agent, 플랜, 오케스트레이트만 제공합니다
오케스트레이트	읽기 전용	같은 열한 개

네트워크 접근과 시크릿 접근은 읽기 전용 모드가 의도적으로 거부하지 않습니다: 조사 연구야말로 읽기 전용 모드의 존재 이유입니다.

작업이 실행되기 전에 승인 요구

승인은 샌드박스 설정이 아니라 가드레일 결정입니다.

설정 → 워크스페이스 → 에이전트 권한으로 이동합니다
워크스페이스, 에이전트 또는 스페이스 범위에서 작업 클래스를 먼저 묻기로 설정합니다

먼저 묻기 결정은 실행을 중단하고 여러분에게 묻습니다. 승인자가 연결되어 있지 않으면 실패 시 거부로 처리되어 그 작업은 거부됩니다. 전체 판정 순서는 가드레일 구성을 참고하세요.

문제 해결

에이전트가 푸시하지 못하는데 거부한 적이 없습니다

git이 출력한 내용을 읽으세요. Control Center policy: …는 규칙이 푸시를 거부했거나 먼저 묻기에 응답이 없었다는 뜻입니다. … is not linked to this workspace는 푸시 대상이 워크트리 자체의 저장소도 아니고 워크스페이스에 연결된 저장소도 아니라는 뜻입니다. Control Center has no GitHub credential that can push …는 그 저장소에 GitHub App이 설치되어 있지 않고 푸시할 수 있는 폴백 자격 증명도 없었다는 뜻입니다: 그 저장소에 앱을 설치하거나 GitHub를 연결하세요.

샌드박싱 카드가 네이티브 샌드박스가 없다고 보고합니다

그러면 그 호스트의 에이전트 실행은 Seatbelt나 bubblewrap으로 감싸지지 않으며, 남은 경계가 여러분이 가진 전부입니다. Linux와 WSL2에서는 빠진 두 도구를 설치하고 — sudo apt-get install bubblewrap socat — 서버를 다시 시작하세요. 그러면 시작 로그에 샌드박스가 켜져 있다고 나와야 합니다. Windows에는 설치할 네이티브 백엔드가 없으므로 대신 가드레일을 강화하세요: 가드레일 구성을 참고하세요.

에이전트가 워크트리 밖의 파일에 닿았습니다

어느 도구가 거기에 닿았는지가 이것이 예상된 일인지 결정합니다.

하네스의 프로세스 내 파일 도구(read, write, edit, apply patch, search, find, search_files)는 서버 프로세스 안에서 실행되므로 어떤 샌드박스 프로필도 이들에게 적용되지 않습니다 — 이들의 범위는 자체 경로 제한과 가드레일입니다. bash 명령이나 Claude Code CLI는 백엔드가 있는 곳에서 감싸지며, 여러분이 등록한 체크아웃은 모든 모드에서 그 래핑 안에서 쓰기 거부입니다. 심볼릭 링크가 해석된 표기까지 포함해서입니다(macOS에서 /tmp나 /var/folders를 거쳐 도달한 경로는 /private 아래로 해석되며, 이제 두 표기 모두 거부됩니다). 백엔드가 없는 호스트에서는 이 중 어느 것도 적용되지 않습니다. 어느 경우든 가드레일은 워크트리 밖에 쓰기를 곧바로 거부할 수 있습니다.