GitHub Copilot App 로컬 샌드박스 설정 및 검증 가이드

샌드박스를 켰는데도 기존 세션이 이전 권한으로 계속 동작하거나, 에이전트가 패키지 설치·로컬 서버 연결·브랜치 push 때마다 추가 접근을 요구할 수 있습니다. 이런 문제는 단순한 켜기/끄기보다 프로젝트 기본값, 세션 재정의, 파일·네트워크·자격 증명이라는 세 경계의 조합에서 생깁니다.

이 글을 읽고 나면 로컬 저장소나 작업 트리에 맞는 시작 정책을 고르고, 변경 사항을 올바른 세션에 적용하며, 더미 데이터로 각 제한이 실제로 동작하는지 확인할 수 있습니다. 가장 짧은 순서는 세션 유형 확인 → Sandbox new sessions 활성화 → 세 권한 범위 축소 → 새 세션 또는 재시작 → 안전한 검증입니다.

GitHub는 2026년 9월 23일 이 기능을 발표했으며 현재 공개 미리 보기 단계라 화면과 동작이 바뀔 수 있습니다. 기본적으로 꺼져 있고, 프로젝트별로 설정하며, 호스트가 요청 정책을 강제할 수 없으면 보호 없이 계속 실행하지 않고 샌드박스 셸이 실패한다는 세 가지 경계를 기억하십시오.

먼저 현재 세션이 정책 대상인지 확인하기

이 프로젝트 정책은 로컬 저장소와 로컬 작업 트리 세션에만 적용됩니다. 클라우드 샌드박스, 원격 호스트, GitHub Copilot CLI는 다른 격리나 설정을 사용하므로 먼저 표에서 범위를 확인하십시오.

세션 유형	적용 여부	기억해야 할 경계
로컬 저장소 세션	적용	현재 프로젝트의 샌드박스 설정을 사용함
로컬 작업 트리 세션	적용	작업 트리는 브랜치와 파일을 분리하지만 컴퓨터의 다른 위치에 대한 접근을 제한하지 않으며, 그 권한 경계는 샌드박스가 제공함
클라우드 샌드박스 세션	미적용	클라우드 세션 자체의 격리를 사용함
원격 호스트에서 실행되는 세션	미적용	로컬 프로젝트 정책이 원격 호스트에는 적용되지 않음
GitHub Copilot CLI	별도 설정	Copilot app과 Copilot CLI의 샌드박스 설정은 서로를 대체하지 않음

기업에서 관리하는 설정에 따라 실제 적용 정책이 프로젝트 설정에서 요청한 정책보다 더 엄격할 수 있습니다. 따라서 프로젝트 화면은 app이 요청하는 권한을 보여 주며, 조직이 허용할 최대 접근 범위와 반드시 같지는 않습니다.

새 세션에 샌드박스를 적용하는 방법

이후 로컬 세션에 프로젝트 정책을 적용하려면 Sandbox new sessions를 켠 뒤 새 세션을 시작해야 합니다. 스위치만 바꿔서는 이미 실행 중인 세션이 갱신되지 않습니다. 다음 순서로 진행하십시오.

1. GitHub Copilot app 설정을 엽니다.
2. 설정할 프로젝트를 선택합니다.
3. Sandbox 섹션을 찾습니다.
4. Sandbox new sessions를 켭니다.
5. 새 로컬 세션을 시작합니다.

이 스위치는 이후에 생성되는 세션에만 영향을 줍니다. 이미 실행 중인 세션은 바뀌지 않습니다. 파일, 네트워크, 자격 증명 정책을 나중에 수정해도 새 세션을 시작하거나 현재 세션을 재시작해야 변경 사항이 적용됩니다.

대화 기록을 유지하면서 정책을 다시 불러오려면 기존 세션에서 /restart-session을 입력합니다.

GitHub는 대부분의 프로젝트에서 기본 정책으로 시작할 것을 권장합니다. 기본 정책은 종속성 설치, 로컬 개발 서버 연결, 브랜치 push, pull request 생성 같은 일반적인 개발 작업을 지원합니다. 프로젝트 주변에 민감한 폴더가 있거나 네트워크가 필요하지 않거나 자신의 자격 증명을 사용하게 하면 안 되는 경우에는 필요한 수준까지 더 좁히면 됩니다.

파일·네트워크·자격 증명을 따로 제한하는 방법

세 영역은 서로 독립적입니다. 파일 제한은 자격 증명을 끄지 않으며, 자격 증명을 꺼도 읽을 수 있는 민감 폴더가 보호되지는 않습니다. 모든 기능을 한 번에 끄지 말고 작업에 맞춰 각각 좁히십시오.

1. 파일 시스템: 읽고 변경할 수 있는 위치 정하기

파일 권한은 최소 범위에서 시작하십시오. 워크스페이스 읽기·쓰기는 유지하고, 작업에 꼭 필요한 경우에만 다른 경로를 추가합니다. 기본적으로 워크스페이스와 현재 작업 디렉터리를 읽고 쓸 수 있으며, 설정에는 세 목록이 있습니다.

• Additional read/write: 에이전트가 실행한 도구가 추가로 읽고 수정할 수 있는 폴더.
• Additional read-only: 읽을 수 있지만 수정할 수는 없는 추가 폴더.
• Denied: 접근할 수 없는 폴더.

더 구체적인 하위 폴더를 거부하면 상위 폴더에 더 넓은 읽기 또는 쓰기 권한이 있어도 그 하위 폴더는 계속 거부됩니다. 홈 디렉터리 전체를 연 뒤 많은 예외에 의존하기보다 실제로 필요한 최소 경로만 허용하는 편이 안전합니다.

Windows에는 중요한 강제 적용 경계가 있습니다. 프로젝트 설정에 거부 경로를 저장할 수는 있지만 현재 Windows 샌드박스 기능이 해당 거부를 보장하지 못하면 명령이 unsupported-policy 메시지와 함께 실패합니다. 경로를 노출한 채 계속 실행하거나 샌드박스를 자동으로 끄지 않습니다.

2. 네트워크: 인터넷과 로컬 네트워크를 분리해서 제어하기

의존성 설치나 로컬 개발 서버가 필요하다면 두 네트워크를 한꺼번에 끄지 말고 외부 인터넷과 로컬 네트워크 필요성을 따로 판단하십시오. 기본적으로 둘 다 접근할 수 있으며 다음을 제어할 수 있습니다.

• Outbound internet: GitHub, 패키지 레지스트리 및 기타 인터넷 서비스에 대한 접근.
• Local network: 루프백과 로컬 네트워크 연결. 로컬 개발 서버도 포함합니다.

네트워크 제한은 종속성 설치, API 호출, 미리 보기 서버 및 연결이 필요한 다른 도구에 영향을 줄 수 있습니다. 네트워크 차단을 비용 없는 스위치로 보지 말고 작업 기능과의 절충으로 다뤄야 합니다.

Linux에는 특정 제한이 있습니다. 샌드박스는 셸 명령, 로컬 MCP 서버, LSP 서버처럼 생성된 프로세스의 로컬 네트워크 접근만 독립적으로 제어할 수 없습니다. 다만 프로세스 내부의 웹 요청과 원격 MCP 연결에는 설정이 계속 적용됩니다. Linux에서는 한 경로만 시험하지 말고 프로세스 내부 동작과 생성 프로세스 동작을 모두 검증해야 합니다.

3. 자격 증명: Git과 GitHub CLI를 따로 제어하기

코드 검토나 오프라인 분석이라면 Git과 GitHub CLI 자격 증명을 먼저 끄고, 브랜치 push나 pull request 생성이 필요할 때만 여십시오. 기본적으로 인증 작업을 사용할 수 있으며 다음을 끌 수 있습니다.

• Git credentials: 인증된 HTTPS Git 작업에 쓰이는 자격 증명.
• GitHub CLI credentials: GitHub CLI가 사용하는 인증 정보.

이를 끄면 브랜치 push나 pull request 생성 같은 작업이 막힐 수 있습니다. 파일 시스템 정책과 자격 증명 정책은 서로 다른 경계입니다. 자격 증명을 비활성화해도 키, 설정 또는 다른 민감한 자료가 있는 디렉터리는 파일 시스템 규칙으로 보호해야 합니다.

프로젝트, 현재 세션, 한 번의 작업을 언제 바꿀까

이후 세션이 규칙을 상속해야 하면 프로젝트 설정을 바꾸고, 현재 세션만 조정할 때는 /sandbox on 또는 /sandbox off를 사용합니다. 프로젝트 변경을 현재 세션에 적용하려면 /restart-session을 실행하십시오.

작업	적용 시점	다른 세션에 미치는 영향
프로젝트의 Sandbox 설정 변경	새 세션 또는 재시작한 세션	해당 프로젝트의 이후 세션이 상속할 기본값을 변경함
활성 로컬 세션에서 /sandbox on 입력	즉시 적용되며 해당 세션의 지속적인 재정의가 됨	다른 세션의 프로젝트 기본값은 바뀌지 않음
활성 로컬 세션에서 /sandbox off 입력	해당 세션의 샌드박스를 즉시 비활성화함	다른 세션은 바뀌지 않으며, 이후 명령은 사용자 계정과 같은 파일·네트워크·자격 증명 접근 권한을 가짐
세션 시작 전에 /sandbox on 또는 /sandbox off 입력	새 세션이 상속할 프로젝트 기본값을 변경함	이후 그 기본값으로 시작되는 세션에 영향을 줌
/restart-session 입력	현재 세션을 재시작하고 기록을 유지하며 정책을 다시 불러옴	그 자체로 프로젝트 정책을 수정하지는 않음

도구가 정책에서 허용하지 않은 접근을 필요로 하면 app에 Run outside the sandbox?가 표시될 수 있습니다. 실제 적용 정책에 따라 취소하거나, 해당 작업만 한 번 샌드박스 밖에서 실행하거나, 현재 세션의 나머지 기간 동안 샌드박스를 끌 수 있습니다. 기업 소유자는 사용자가 도구를 샌드박스 밖에서 실행하지 못하게 막을 수 있습니다.

이 프롬프트를 통해 비활성화하더라도 프로젝트 기본값이나 기존 세션 재정의는 다시 쓰지 않습니다. 임시 상태는 세션을 재시작하거나 다시 연결할 때 끝납니다. Sandbox off for this session이 표시된 뒤에는 Re-enable sandbox로 다시 활성화할 수 있습니다.

더 안전한 판단 순서는 먼저 취소하고 명령에 추가 접근이 필요한 이유를 이해하는 것입니다. 반복해서 필요한 접근이라면 프로젝트 정책을 필요한 범위로만 수정하고 재시작합니다. 명령, 인수, 영향을 검토한 뒤에만 한 번의 샌드박스 외 실행을 선택해야 합니다. 낯선 저장소나 프롬프트에서 동적으로 구성된 명령이라면 편의성만을 이유로 전체 세션의 샌드박스를 끄지 않는 편이 좋습니다.

호스트가 정책을 강제하지 못하면 명령이 중단된다

운영체제가 요청 규칙을 강제할 수 없다면 안전한 결과는 명령 실패이며, 샌드박스 없이 자동으로 계속 실행되는 것이 아닙니다.

GitHub Copilot app은 운영체제가 모든 설정을 강제할 수 있는지 확인하기 전에도 샌드박스 설정을 저장합니다. 실제 지원 여부는 첫 번째 샌드박스 셸이 시작될 때 검사합니다.

호스트가 요청한 정책을 강제할 수 없으면 다음과 같이 동작합니다.

• 셸에 unsupported-platform 또는 unsupported-policy 메시지가 표시됩니다.
• 명령은 샌드박스 없이 계속 실행되지 않습니다.
• app에 Sandbox unavailable이 표시되면 보고된 문제를 해결하고 Retry sandbox를 선택합니다.

이는 가능한 범위에서만 실행하는 방식이 아니라 안전하게 닫히는 실패 동작입니다. 따라서 설정 저장에 성공했다는 사실만으로 현재 컴퓨터에서 정책이 활성화되었다고 볼 수 없습니다. 샌드박스 셸을 적어도 한 번 시작하고 지원되지 않음 메시지가 없는지 확인한 뒤 최소 검증을 수행해야 합니다.

더미 데이터로 정책을 확인하는 방법

GitHub 문서는 예상 동작을 설명하지만, 현재 운영체제와 정책 조합이 실제로 작동하는지는 자신의 컴퓨터에서 확인해야 합니다. 아래 절차는 폐기 가능한 폴더와 더미 파일만 사용하므로 실제 키나 운영 설정을 건드릴 필요가 없습니다.

워크스페이스 밖에 폐기 가능한 테스트 폴더를 만들고 더미 파일만 넣으십시오. 실제 SSH 키, 클라우드 자격 증명 또는 운영 환경 설정으로 시험하지 마십시오.

검증 항목	안전한 절차	예상되는 정책 동작
새 세션 상속	Sandbox new sessions를 켠 다음 새 로컬 세션을 생성함	새 세션은 프로젝트 정책을 사용하고 기존 세션은 자동으로 바뀌지 않아야 함
정책 수정 적용	규칙 하나를 바꾸고 /restart-session을 입력함	세션이 기록을 유지한 채 재시작되고 정책을 다시 불러와야 함
읽기 전용 폴더	폐기 가능한 폴더를 Additional read-only에 추가하고 더미 파일을 읽은 뒤 테스트 파일 생성을 시도함	읽기는 가능하고 수정은 차단되어야 함
거부 폴더	다른 폐기 가능한 폴더를 Denied에 추가하고 목록 조회 또는 더미 파일 읽기를 시도함	더 넓은 상위 경로가 허용되어도 접근이 차단되어야 함
인터넷 접근	Outbound internet을 끄고 무해한 연결 확인을 수행함	외부 연결이 실패해야 하며, 다시 켠 뒤 결과를 비교함
로컬 네트워크	Local network를 끄고 폐기 가능한 로컬 테스트 서비스에 연결함	플랫폼 기능에 따른 결과가 나와야 하며 Linux 생성 프로세스 제한을 고려함
Git 자격 증명	Git credentials를 끄고 테스트 저장소에서 변경 없는 인증 확인을 수행함	인증된 HTTPS Git 작업을 사용할 수 없을 수 있음
GitHub CLI 자격 증명	GitHub CLI credentials를 끄고 gh auth status 같은 변경 없는 확인을 수행함	GitHub CLI가 이전 인증 기능을 받지 않아야 하며 구체적인 오류는 환경에 따라 달라질 수 있음
안전 실패	unsupported-platform 또는 unsupported-policy가 나오면 목표 더미 파일이 생성되지 않았는지 확인함	명령이 샌드박스 없이 계속 실행되거나 의도한 부작용을 만들지 않아야 함

검증 후에는 테스트 폴더를 삭제하고 프로젝트에 실제로 필요한 최소 권한만 복원합니다. 실제 민감한 디렉터리에 접근해 거부 규칙을 증명하려고 하지 마십시오.

작업별로 어떤 시작 정책을 선택할까

일상 개발, 낯선 저장소, 오프라인 분석에 같은 정책을 적용하면 안 됩니다. 일반 작업에는 필요한 기능을 남기고, 낯선 코드는 더 엄격하게 시작하며, 오프라인 작업은 네트워크와 자격 증명을 먼저 끄십시오.

일상적인 개발

샌드박스를 활성화하고 기본 네트워크 및 자격 증명 기능을 유지하되 필요한 외부 폴더만 추가하고 주변의 민감한 디렉터리는 명시적으로 거부합니다. 종속성 설치, 로컬 서비스 실행, 브랜치 push, pull request 생성이 필요한 일반 개발에 적합합니다.

낯선 저장소 검토

워크스페이스에만 읽기·쓰기를 허용하고 추가 참고 자료는 읽기 전용으로 둡니다. Git 및 GitHub CLI 자격 증명을 기본적으로 끄고 종속성 출처를 이해할 때까지 외부 인터넷도 차단합니다. 임시 접근이 필요하면 곧바로 /sandbox off를 쓰지 말고 특정 기능 하나만 여십시오.

로컬 오프라인 분석

외부 인터넷과 불필요한 자격 증명을 끄고 필요한 파일 접근만 유지합니다. 로컬 네트워크 격리도 중요하다면 하나의 UI 스위치가 모든 프로세스를 똑같이 제어한다고 가정하지 말고 Linux에서 생성 프로세스 동작을 별도로 확인하십시오.

이 세 가지는 GitHub가 이름 붙인 프리셋이 아닙니다. GitHub가 제공하는 권한 차원을 조합한 시작 예시입니다. 최종 정책은 저장소, 운영체제, 기업 규칙 및 실제 작업에 맞게 조정해야 합니다.

정책을 무력화하거나 권한을 넓히는 실수

가장 흔한 실수는 “설정 저장”을 “정책 강제”로 이해하거나 첫 접근 거부 뒤 전체 샌드박스를 끄는 것입니다. 아래 일곱 가지는 검증을 왜곡하거나 작업에 불필요한 권한을 줍니다.

1. 작업 트리를 보안 경계로 간주합니다. 작업 트리는 동시에 사용하는 브랜치와 파일을 분리하지만 명령이 컴퓨터의 다른 위치에 도달하는 것을 막지는 않습니다.
2. 정책을 수정한 뒤 기존 세션에서 계속 검증합니다. 프로젝트 변경은 소급 적용되지 않으므로 새 세션을 시작하거나 /restart-session을 사용해야 합니다.
3. app과 CLI가 하나의 샌드박스를 공유한다고 가정합니다. 두 기능은 별도로 설정합니다.
4. 설정 저장 성공을 호스트 지원의 증거로 봅니다. 강제 적용 지원 여부는 첫 샌드박스 셸이 시작될 때 확인합니다.
5. /sandbox off의 의미를 간과합니다. 이후 에이전트 명령은 사용자 계정과 같은 접근 범위를 갖습니다.
6. 모든 플랫폼에서 네트워크 동작이 같다고 가정합니다. Linux에는 생성 프로세스의 로컬 네트워크 제어에 대한 문서화된 제한이 있습니다.
7. 접근이 거부될 때마다 광범위한 우회를 사용합니다. 대개는 필요성을 확인하고 최소한의 정책 변경을 한 다음 세션을 재시작하는 편이 더 안전합니다.

지금 해야 할 일

먼저 로컬 저장소 또는 로컬 작업 트리 세션인지 확인하고 Sandbox new sessions를 켜십시오. 일상 개발은 기본 정책에서 시작해 필요한 폴더, 네트워크, 자격 증명만 남기고, 낯선 코드나 오프라인 분석은 더 엄격한 정책에서 한 가지 권한씩 추가하십시오.

프로젝트 정책을 바꾼 뒤 새 세션을 만들거나 /restart-session을 실행하고, 폐기 가능한 데이터로 읽기 전용·거부·네트워크·자격 증명 경계를 검증하십시오. unsupported-platform, unsupported-policy, Sandbox unavailable이 표시되면 호환성 문제를 해결하고, /sandbox off 결과를 샌드박스 검증 성공으로 간주하지 마십시오.

공식 자료

설정 전후에 아래 GitHub 공식 페이지에서 현재 화면, 적용 범위, 실패 동작을 확인할 수 있습니다.

• GitHub Copilot app에서 로컬 샌드박스 구성하기
• Local sandboxing in the GitHub Copilot app — GitHub Changelog, 2026년 9월 23일