GitHub Copilot CLI 로컬 샌드박스 설정: 파일·네트워크·자격 증명 접근 제한하기

GitHub Copilot CLI에 셸 명령 실행을 맡기고 있는데, 에이전트가 홈 디렉터리의 다른 프로젝트를 읽거나 임의 호스트로 요청을 보내지 않을까 걱정되는 개발자를 위한 글이다. 2026년 10월 7일 GitHub는 Copilot의 로컬 샌드박스를 정식 기능으로 전환했다(GitHub Changelog). 이 글을 따라가면 CLI에서 샌드박스를 켜고, 파일·네트워크·자격 증명 범위를 프로젝트 성격에 맞게 조정하고, 막힌 명령을 진단하는 방법까지 익힐 수 있다.

샌드박스는 Copilot CLI, GitHub Copilot 앱, Agent Host를 쓰는 VS Code 세션에서 지원되며 추가 비용은 없다. 가상 머신이나 컨테이너가 아니라 운영체제 기능을 이용한 프로세스·파일시스템 격리라는 점을 먼저 알아 둔다(공식 개념 문서).

운영체제별 요구 사항부터 확인하기

# Ubuntu/Debian 예시: 요구 패키지 설치 후 버전 확인
sudo apt-get install -y bubblewrap slirp4netns
bwrap --version
slirp4netns --version

Linux 개념 문서는 이 밖에 util-linux 2.35 이상, iptables, /dev/net/tun 접근도 요구 사항으로 적고 있다. 컨테이너 안에서 CLI를 돌리는 경우 /dev/net/tun이 막혀 있는 경우가 많으므로 먼저 확인한다.

CLI에서 샌드박스를 켜고 상태 확인하기

1. 대화형 세션에서 켠다 — /sandbox enable을 입력하면 현재 세션부터 바로 적용되고, 끌 때까지 이후 세션에도 유지된다.
2. 적용 여부를 확인한다 — /sandbox status로 켜졌는지 보고, /sandbox policy로 실제 적용되는 경로·네트워크·권한 목록을 본다.
3. 특정 명령이 무엇에 접근하는지 미리 본다 — /sandbox policy npm install처럼 명령을 붙이면 실행하지 않고 적용될 정책만 보여 준다.
4. 세부 설정 화면을 연다 — /sandbox 또는 /sandbox config를 입력하면 General, Credentials, Filesystem, Network 탭이 있는 설정 화면이 열린다.

/sandbox enable
/sandbox status
/sandbox policy npm install
/sandbox config

스크립트나 CI처럼 설정을 저장하지 않고 한 번만 켜고 싶다면 실행 옵션을 쓴다. 사용 가이드에 따르면 --sandbox는 그 세션에만 적용되고, 정책이 허용하는 경우 --no-sandbox로 한 세션만 끌 수도 있다.

copilot --sandbox -p "테스트를 실행하고 실패한 케이스를 요약해 줘"

Copilot 앱에서는 명령 이름이 달라 /sandbox on, /sandbox off를 쓰며, 프로젝트 기본값은 Settings → Projects → 프로젝트 선택 → Sandbox에서 정한다.

기본값으로 열려 있는 것과 막힌 것

설정을 바꾸기 전에 기본 정책을 알아야 무엇을 더 열고 닫을지 판단할 수 있다. 아래는 사용 가이드와 설정 가이드에 나온 기본값이다.

로컬 네트워크가 기본으로 막혀 있다는 점을 놓치기 쉽다. 에이전트에게 개발 서버를 띄운 뒤 curl localhost:3000으로 확인시키는 흐름이라면 Allow local network를 켜거나, 호스트 허용 규칙을 하나 이상 추가해야 한다. 설정 가이드에 따르면 Allow 규칙이 하나라도 있으면 localhost, 127.0.0.1, ::1은 자동으로 허용된다.

프로젝트 성격별로 범위 조정하기

네트워크를 의존성 레지스트리로만 좁히기

외부 인터넷 기본 허용이 부담스러운 프로젝트라면 Network 탭의 Host rules에 필요한 호스트만 Allow로 넣는다. 규칙은 다음처럼 동작한다. Allow는 정확히 그 호스트만 맞으므로 하위 도메인까지 허용하려면 *.example.com을 써야 한다. 반대로 Deny는 하위 도메인까지 막는다. 둘이 겹치면 Deny가 우선한다. 기업 정책 규칙은 허용 범위를 좁힐 수만 있고 넓힐 수는 없다.

위 호스트 목록은 일반적인 예시이며, 실제로 필요한 호스트는 프로젝트의 의존성과 스크립트에 따라 다르다. 처음에는 기본값으로 작업하면서 차단 메시지에 나온 호스트를 모은 뒤 목록을 확정하는 순서가 덜 번거롭다.

API 키를 명령에 직접 넘기지 않기

테스트가 외부 API를 호출해야 하는데 키 원문을 에이전트 명령 환경에 노출하고 싶지 않다면 Masked environment variables를 쓴다. 설정 가이드에 따르면 샌드박스 안 명령에는 자리표시 값이 보이고, 지정한 호스트로 나가는 HTTPS 요청의 헤더(Authorization, X-Api-Key, HTTP Basic)에서만 실제 값으로 바뀐다.

// Copilot CLI 설정 디렉터리의 settings.json (저장소 설정 파일은 지원하지 않음)
{
  "sandbox": {
    "enabled": true,
    "credentials": {
      "envVars": {
        "PAYMENT_SANDBOX_KEY": {
          "injectHosts": ["api.sandbox.example.com"]
        }
      }
    }
  }
}

주의할 점이 두 가지 있다. 마스킹할 변수를 --secret-env-vars에 함께 넣으면 그 옵션이 변수를 아예 제거해 버리므로 둘 중 하나만 쓴다. Windows에서는 마스킹이 동작하려면 Network 탭의 Allow local network를 켜야 한다. 어떤 파일을 애초에 AI 도구가 읽지 못하게 할지는 시크릿·.env가 AI 코딩 도구 컨텍스트에 들어가지 않게 막는 설정에서 도구별로 다뤘다.

읽기 금지 경로 추가하기

작업 디렉터리 안에 고객 데이터 덤프 같은 폴더가 있다면 Filesystem → User-configured paths에서 절대 경로를 추가하고 Denied를 고른다. 반대로 모노레포의 공용 패키지처럼 작업 디렉터리 밖이지만 읽어야 하는 경로는 Read-Only로 추가한다. 존재하지 않는 경로를 차단 목록에 넣으면 CLI가 샌드박스 명령 실행 전에 그 위치에 디렉터리를 만든다. 파일을 막으려던 것이라면 샌드박스 밖에서 파일을 먼저 만들어 둔다.

명령이 막혔을 때 진단 순서

1. /sandbox status로 샌드박스가 실제로 켜져 있는지 확인한다.
2. /sandbox policy <명령>으로 그 명령에 적용되는 경로·호스트 목록을 본다.
3. 필요한 경로나 호스트가 빠졌다면 /sandbox config에서 규칙을 추가한다. 한 번만 필요한 작업이라면 우회 승인 프롬프트에서 해당 명령만 허용한다. 우회 승인된 명령은 전체 자격 증명으로 실행되므로 명령 내용을 읽고 승인한다.
4. HTTPS 인증서 오류가 난다면 /sandbox ca create, /sandbox ca trust로 프록시 인증서를 신뢰시킨다. 시스템 전체 신뢰 저장소가 바뀌며 Windows에서는 관리자 승인이 필요하다.

공식 문서는 HTTP/2만 쓰는 도구, 특정 서버 인증서만 받는 도구, 클라이언트 인증서나 요청 서명을 쓰는 도구는 이 방법으로도 실패할 수 있다고 적고 있다. 이런 도구는 샌드박스 밖에서 직접 실행하는 편이 낫다.

샌드박스가 막아 주지 않는 범위

Copilot CLI의 내장 파일 도구(파일 읽기·편집)는 CLI 프로세스 안에서 실행되므로 OS 수준 샌드박스의 제약을 받지 않는다. 개념 문서에 따르면 이 도구들은 정책을 최선 노력 수준으로만 확인한다. 즉 샌드박스는 셸 명령과 로컬 MCP·LSP 서버를 가두는 장치이고, 에이전트가 파일을 고치는 동작 자체를 막지는 않는다. 원격 MCP 서버도 샌드박스 대상이 아니다. 또한 모델 선택·추론과 도구 격리는 별개라서, 샌드박스를 켜도 프롬프트와 코드 문맥이 모델 제공자로 전송되는 경로는 바뀌지 않는다.

그래서 샌드박스는 권한 승인 설정과 함께 써야 한다. Claude Code의 자동 승인 범위를 점검하는 방법은 Claude Code Auto Mode 보안 점검에서, MCP 서버의 허용 경로를 좁히는 방법은 파일시스템·브라우저 자동화 MCP 안전 설정에서 다뤘다. 회사가 관리 정책으로 샌드박스를 강제하면 설정 화면에 (managed) 표시가 붙고, 정책이 우회를 허용하지 않으면 /sandbox disable도 거부된다.