Claude Code 샌드박스에서 특정 도메인 차단하기 | Playbook Tip

에이전트가 코드 실행 중 외부 네트워크로 나가는 걸 완전히 막기는 애매할 때가 있어요. allowedDomains에 *.internal.company.com 같은 와일드카드를 열어두면 내부 서비스는 잘 되는데, 그러다 예상 못한 도메인까지 허용되는 경우가 생겨요. 서드파티 SDK가 몰래 텔레메트리 서버에 핑 보내는 상황이라면 진짜 곤란해요. v2.1.113부터 sandbox.network.deniedDomains가 생겨서, 허용 목록을 건드리지 않고 특정 도메인만 잘라낼 수 있어요.

준비물

Claude Code v2.1.113 이상
sandbox.enabled: true 상태 (기본값은 false. macOS·Linux·WSL2에서만 동작)
settings.json 접근 권한 (프로젝트 루트 또는 홈 디렉토리)

스텝

1. 샌드박스 활성화 확인

deniedDomains는 샌드박스가 켜져 있어야 동작해요. 먼저 settings.json을 열어서 sandbox.enabled가 true인지 확인해요. 파일이 없거나 샌드박스 설정 자체가 없으면 아래처럼 새로 적어줘요.

프로젝트 범위 (팀 전체에 적용하고 싶을 때):

mkdir -p .claude && open .claude/settings.json

개인 전역 (모든 프로젝트에 적용):

mkdir -p ~/.claude && open ~/.claude/settings.json

2. deniedDomains 추가

sandbox.network.deniedDomains는 문자열 배열이에요. 와일드카드(*.example.com)도 허용돼요. allowedDomains와 동시에 매칭되는 경우 deniedDomains가 우선하기 때문에, 넓게 열어둔 상태에서 예외를 만들기에 딱 맞아요.

{
  "sandbox": {
    "enabled": true,
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org", "*.internal.company.com"],
      "deniedDomains": ["uploads.github.com", "telemetry.thirdparty.io"]
    }
  }
}

이 예시는 GitHub·npm·사내 도메인을 허용하면서도 GitHub의 업로드 엔드포인트와 특정 텔레메트리 서버만 차단해요.

3. 적용

settings.json에 deniedDomains를 추가해도 지금 열려 있는 Claude Code 세션에는 바로 반영이 안 돼요. 세션을 종료하고 다시 시작해야 해요.

exit
claude

확인 방법

차단된 도메인에 접속을 시도하면 프록시 레벨에서 요청이 거부돼요. curl로 직접 테스트해볼 수 있어요.

curl -v https://telemetry.thirdparty.io/ping

연결이 끊기거나 프록시 거부 에러가 나오면 차단이 제대로 걸린 거예요. 샌드박스 설정이 반영됐는지 다시 확인하려면 /sandbox 커맨드로 샌드박스 상태 화면을 열어보거나, /config의 Config 탭에서 sandbox.network.deniedDomains 값을 직접 확인해요.

응용

여러 설정 레벨에서 merge

기본적으로 deniedDomains는 관리형 설정(managed)·사용자·프로젝트·로컬 전부에서 merge돼요. 다만 관리자가 allowManagedDomainsOnly: true를 걸어두면 사용자·프로젝트·로컬의 도메인 관련 설정은 무시되고 관리형 목록만 유효하게 돼요. 개인 설정으로 위험 도메인을 추가 차단하려면 이 관리 플래그가 꺼져 있어야 해요.

와일드카드로 한 단계 위에서 차단

특정 서비스 전체를 덮어버리고 싶으면 와일드카드를 써요.

{
  "sandbox": {
    "network": {
      "deniedDomains": ["*.tracking.example.com", "*.ads.network"]
    }
  }
}

트러블슈팅

설정 변경이 반영 안 되는 것처럼 보이면 세션 재시작을 잊은 경우가 대부분이에요. 그래도 안 먹으면 sandbox.enabled가 true인지부터 다시 확인해요. 기본값이 false라서, 다른 설정만 채워두고 enabled를 빼먹으면 네트워크 제한 자체가 안 걸려요.

JSON 문법 오류도 흔한 원인이에요. 아래 명령으로 파싱 에러를 빠르게 잡을 수 있어요.

cat .claude/settings.json | python3 -m json.tool

deniedDomains에 적은 도메인이 와일드카드 매칭에 포함되지 않으면 당연히 차단 안 돼요. 예를 들어 uploads.github.com을 적어두고 github.com으로 요청을 보내면 기본은 허용이에요. 정확한 호스트명 또는 와일드카드 패턴을 써야 해요.

허용과 차단 두 축으로 접근 범위를 다듬어두면, 넓게 열어둔 개발 환경에서도 민감한 엔드포인트만 조용히 막아둘 수 있어요.

준비물

스텝