GitHub Copilot 앱 로컬 샌드박스 설정과 안전한 사용법

9월 29, 2026

AI 코딩 에이전트가 파일을 고치고, 패키지를 설치하고, 테스트를 실행하는 범위가 넓어질수록 “어떤 명령을 승인할까”만으로는 안전을 관리하기 어렵습니다. 사람이 승인 창을 놓치거나 저장소 안의 악성 지시를 에이전트가 읽을 수도 있기 때문입니다. GitHub가 2026년 9월 23일 Copilot 앱에 추가한 로컬 샌드박스는 이 문제를 운영체제 수준의 실행 경계로 줄이는 기능입니다.

English: Read this guide in English

이 글에서는 로컬 샌드박스가 실제로 제한하는 대상, 프로젝트별 설정 순서, 파일·네트워크·자격증명을 나누는 방법, 정상 적용 확인, 작업이 막힐 때의 복구 순서를 설명합니다. 기능은 현재 공개 미리보기이며 기본값은 꺼짐입니다. 직접 테스트 결과를 주장하지 않고 GitHub 공식 문서에서 확인된 동작과 제약만 다룹니다.

핵심 요약: 승인보다 먼저 실행 범위를 줄인다

적용 대상: GitHub Copilot 앱의 로컬 저장소 및 working tree 세션
제어 영역: 파일 시스템, 외부 인터넷·로컬 네트워크, Git·GitHub CLI 자격증명
기본 상태: 프로젝트마다 별도 설정하며 기본적으로 비활성화
적용 시점: 새 세션 또는 기존 세션 재시작 이후
실패 방식: 운영체제가 정책을 강제하지 못하면 샌드박스 없이 조용히 실행하지 않고 오류로 중단
비용: 로컬 샌드박스는 Copilot 좌석에 추가 비용 없이 포함된다고 공식 문서가 안내

AI 코딩 에이전트 작업 공간을 파일, 네트워크, 자격증명 경계로 제한하는 로컬 샌드박스 개념도 — 로컬 샌드박스는 작업 공간 바깥의 파일, 네트워크, 자격증명 접근을 각각 별도의 정책으로 제한합니다.

로컬 샌드박스와 working tree는 역할이 다르다

working tree는 여러 세션이 서로 다른 브랜치와 파일을 사용하도록 분리하는 장치입니다. 그러나 에이전트가 홈 폴더의 다른 파일을 읽거나, 로컬 네트워크 서비스에 접속하거나, 저장된 자격증명을 사용하는 것까지 막아 주지는 않습니다. 로컬 샌드박스는 바로 이 “저장소 밖 접근”에 경계를 추가합니다.

다만 가상 머신이나 완전한 컨테이너와 같은 강한 격리는 아닙니다. GitHub 문서에 따르면 Microsoft eXecution Container(MXC)가 운영체제별 격리 기능을 사용해 프로세스의 파일·네트워크 접근을 제한하는 비교적 가벼운 방식입니다. 따라서 민감한 고객 데이터나 검증되지 않은 바이너리를 다루는 고위험 작업이라면 샌드박스 하나만 믿기보다 별도 테스트 계정, 비밀정보 분리, Dev Container 또는 격리된 실행 환경을 함께 검토해야 합니다.

시작 전 준비사항

GitHub Copilot 앱과 Copilot 사용 권한을 준비합니다. 공식 문서는 Copilot 앱이 모든 Copilot 플랜에서 제공된다고 안내합니다.
대상 저장소에서 현재 변경사항을 커밋하거나 별도 브랜치로 분리합니다. 샌드박스는 잘못된 코드 변경 자체를 되돌리는 도구가 아닙니다.
저장소 주변에 에이전트가 읽으면 안 되는 폴더를 목록으로 적습니다. 예: 다른 고객 프로젝트, 개인 문서, 인증서, 백업 폴더.
작업에 필요한 네트워크를 구분합니다. 패키지 레지스트리 같은 외부 인터넷, localhost 개발 서버, 사내 LAN은 서로 다른 필요입니다.
Git push와 gh pr create가 정말 필요한지 결정합니다. 필요하지 않다면 Git 및 GitHub CLI 자격증명을 꺼 두는 편이 안전합니다.

프로젝트에서 로컬 샌드박스 켜는 순서

GitHub 공식 설정 경로는 간단하지만, 이미 실행 중인 세션에는 자동으로 적용되지 않는다는 점이 중요합니다.

GitHub Copilot 앱에서 Settings를 엽니다.
설정할 프로젝트를 선택합니다.
Sandbox 영역에서 Sandbox new sessions를 켭니다.
파일 시스템, 네트워크, 자격증명 정책을 검토합니다.
새 세션을 시작하거나 기존 세션에서 /restart-session을 입력해 기록을 유지한 채 다시 시작합니다.

GitHub Docs의 Copilot 앱 로컬 샌드박스 활성화 절차 안내 화면 — GitHub Docs가 안내하는 프로젝트별 활성화 절차. Settings에서 프로젝트를 고른 뒤 Sandbox new sessions를 켭니다. 출처: GitHub Docs, 2026년 9월 29일 확인.

현재 세션에 즉시 적용하려면 대화 입력창에서 /sandbox on을 사용할 수 있습니다. 반대로 /sandbox off는 그 세션의 샌드박스를 끕니다. 세션이 시작된 뒤 입력한 명령은 프로젝트 기본값을 바꾸지 않는 세션별 재정의입니다. 세션이 시작되기 전에 입력하면 새 세션이 물려받을 프로젝트 기본값에 영향을 줄 수 있으므로 적용 범위를 확인해야 합니다.

정책 1: 파일 접근은 최소 범위부터 시작한다

기본적으로 샌드박스 세션은 workspace와 현재 작업 디렉터리에 읽기·쓰기 권한을 가집니다. 그 밖의 폴더는 세 가지 목록으로 추가합니다.

설정	의미	권장 사례
Additional read/write	읽고 수정 가능	빌드 산출물 공유 폴더처럼 수정이 꼭 필요한 위치
Additional read-only	읽기만 가능	공통 문서, API 스키마, 디자인 토큰
Denied	접근 차단	다른 고객 저장소, 개인 키, 백업·내보내기 폴더

넓은 상위 폴더를 허용하고 그 안의 민감한 하위 폴더를 Denied로 지정할 수도 있습니다. 공식 문서는 더 구체적인 거부 규칙이 넓은 허용 규칙보다 우선한다고 설명합니다. 하지만 구조가 복잡해질수록 사람이 정책을 오해하기 쉬우므로, 가능하면 상위 폴더 전체를 열지 말고 필요한 폴더만 직접 허용하는 편이 낫습니다.

정책 2: 외부 인터넷과 로컬 네트워크를 따로 판단한다

기본 정책은 외부 인터넷과 로컬 네트워크 연결을 허용합니다. 두 설정을 무조건 함께 켤 필요는 없습니다.

Outbound internet: GitHub, npm·PyPI 같은 패키지 레지스트리, 외부 API에 필요합니다.
Local network: localhost 개발 서버, 데이터베이스, LAN 장비나 사내 서비스에 필요합니다.

문서 정리, 정적 분석, 이미 설치된 의존성으로 테스트 실행처럼 네트워크가 필요 없는 작업은 두 항목을 꺼서 시작할 수 있습니다. 패키지 설치가 실패하면 외부 인터넷만 켜고, 로컬 미리보기 확인이 필요할 때 로컬 네트워크를 추가하는 식으로 단계적으로 넓히는 방식이 이해하기 쉽습니다.

Linux에서는 생성된 프로세스의 로컬 네트워크 접근을 독립적으로 제어하는 데 제약이 있습니다. 공식 문서는 shell 명령과 로컬 MCP·LSP 서버에는 로컬 네트워크 설정을 별도로 강제하지 못할 수 있으며, 앱 내부 웹 요청이나 원격 MCP 연결에는 설정이 적용된다고 설명합니다. 운영체제별 차이를 동일한 보안 수준으로 가정하면 안 됩니다.

정책 3: Git과 GitHub CLI 자격증명은 작업 단위로 연다

기본값에서는 인증된 HTTPS Git 작업과 GitHub CLI 작업을 사용할 수 있습니다. 즉 에이전트가 브랜치를 push하거나 PR을 만들 수 있는 흐름을 유지합니다. 편리하지만, 코드 분석이나 로컬 수정만 맡길 때는 필요 이상의 권한입니다.

리뷰용 수정안만 만들기: Git credentials와 GitHub CLI credentials를 모두 끕니다.
브랜치 push까지 허용: Git credentials만 켜고 PR 생성은 사람이 처리합니다.
PR 생성까지 자동화: 두 자격증명을 켜되 보호 브랜치, 필수 리뷰, CI 검사를 저장소 정책으로 유지합니다.

샌드박스는 자격증명의 사용 가능 여부를 줄여 주지만, 저장소 권한이나 브랜치 보호를 대체하지 않습니다. 플러그인·MCP 도구의 공급망 위험을 함께 점검하려면 기존 Plugin4Shell 대응 가이드의 설치 출처와 권한 검토 절차도 참고할 수 있습니다.

세 가지 실용 설정 예시

1. 외부 오픈소스 저장소 분석

목적: 낯선 저장소의 구조와 테스트 실패 원인을 조사합니다. workspace만 읽기·쓰기로 두고, 홈 폴더의 다른 프로젝트와 자격증명 폴더는 Denied로 지정합니다. 네트워크는 처음에 끄고, 공식 패키지 설치가 필요할 때 외부 인터넷만 엽니다. Git·GitHub CLI 자격증명은 끕니다. 산출물은 변경 파일, 테스트 명령, 남은 위험 목록으로 제한해 검토합니다.

2. 사내 프로젝트의 로컬 개발 서버 수정

목적: 앱 코드를 수정하고 localhost에서 동작을 확인합니다. workspace는 읽기·쓰기, 공통 API 스키마는 읽기 전용으로 추가합니다. 외부 인터넷은 의존성 설치가 필요할 때만 허용하고 로컬 네트워크는 켭니다. push가 필요하면 Git 자격증명만 허용합니다. 완료 기준은 테스트 통과, 변경 파일 범위, localhost 접속 경로, 비밀정보 미포함 여부입니다.

3. PR 생성까지 맡기는 반복 유지보수

목적: 의존성 업데이트나 문서 수정처럼 범위가 명확한 작업을 자동화합니다. workspace 외 쓰기 권한을 주지 않고, 필요한 레지스트리 접근과 두 자격증명을 허용합니다. 대신 작업 지시에는 수정 대상, 금지 파일, 실행할 테스트, PR 본문에 적을 검증 결과를 명시합니다. Unity Codex·Claude Code 플러그인 가이드에서 설명한 것처럼 에이전트의 산출물을 테스트·로그·diff로 검증하는 단계는 그대로 필요합니다.

정상 적용을 확인하는 방법

설정 변경 후 새 세션을 시작하거나 /restart-session을 실행합니다.
허용한 workspace 안에서 파일 읽기·수정이 되는지 확인합니다.
Denied로 지정한 테스트 폴더 접근이 차단되는지 확인합니다. 실제 비밀 키를 시험 대상으로 쓰지 말고 빈 테스트 폴더를 사용합니다.
네트워크를 끈 경우 외부 패키지 조회와 localhost 접속이 의도대로 제한되는지 구분해 확인합니다.
자격증명을 끈 경우 push나 gh 인증 작업이 성공하지 않는지 확인합니다.
정책이 막은 명령에서 Run outside the sandbox? 요청이 나오면 명령·목적·대상 경로를 읽고, 가능하면 정책을 넓히기보다 작업 방법을 바꿉니다.

운영체제가 요청한 정책을 지원하지 않으면 Copilot 앱은 첫 샌드박스 shell 실행 시 unsupported-platform 또는 unsupported-policy 오류를 표시하고 명령을 실행하지 않습니다. “Sandbox unavailable”이 표시되면 문제를 해결한 뒤 Retry sandbox를 눌러야 합니다. 오류가 났다는 이유로 샌드박스가 자동 해제됐다고 가정하지 마세요.

자주 막히는 상황과 해결 순서

패키지 설치가 실패한다

먼저 Outbound internet이 꺼져 있는지 확인합니다. 켜져 있다면 프록시, 패키지 레지스트리 주소, 인증 파일 접근이 필요한지 구분합니다. 전체 홈 폴더를 읽기 가능하게 열기보다 필요한 캐시나 설정 위치만 추가하는 편이 안전합니다.

localhost 미리보기가 열리지 않는다

Local network 설정을 확인하고, 개발 서버가 실제로 실행 중인지 별도로 확인합니다. Linux에서는 프로세스 유형에 따른 제약이 있으므로 앱 내부 요청과 shell에서 시작한 서버의 동작을 같은 것으로 보지 않습니다.

push 또는 PR 생성이 실패한다

Git credentials와 GitHub CLI credentials는 별도 설정입니다. git push에는 Git 자격증명, gh pr create에는 GitHub CLI 자격증명이 필요할 수 있습니다. 필요한 항목만 켜고 세션을 재시작한 뒤 다시 확인합니다.

정책을 바꿨는데 기존 세션이 그대로다

프로젝트 설정 변경은 실행 중 세션에 즉시 반영되지 않습니다. 기록을 유지하려면 /restart-session을 사용합니다. 특정 세션만 즉시 바꾸려면 /sandbox on 또는 /sandbox off를 사용하되 프로젝트 기본값과 혼동하지 않습니다.

마무리: 가장 좁은 정책에서 필요한 만큼만 넓힌다

Copilot 앱 로컬 샌드박스의 핵심은 에이전트를 “믿을지 말지” 결정하는 것이 아니라, 실수나 잘못된 지시가 생겨도 접근 가능한 범위를 미리 줄이는 데 있습니다. 처음에는 workspace만 허용하고 네트워크와 자격증명을 최소화한 뒤, 막힌 작업의 이유를 확인하면서 한 항목씩 넓히는 방식이 관리하기 쉽습니다.

공개 미리보기 기능이므로 메뉴와 운영체제 지원 범위는 바뀔 수 있습니다. 중요한 프로젝트에서는 샌드박스 외에도 별도 브랜치, 최소 권한 토큰, 보호 브랜치, 필수 리뷰, 테스트 자동화를 함께 사용해야 합니다.

공식 자료

자료 확인일: 2026년 9월 29일

이 블로그 검색

스택핀치