로컬 샌드박싱 사용

로컬 샌드박싱을 사용하도록 설정하여 사용자의 컴퓨터에서 Copilot CLI 또는 Copilot에서 VS Code이(가) 액세스할 수 있는 항목을 제한합니다.

이 기사에서

Introduction

로컬 샌드박싱은 컴퓨터의 파일, 네트워크 리소스 및 자격 증명에 대한 액세스를 제한합니다. 이 문서에서는 Copilot CLI 및 Copilot app에서 로컬 샌드박싱을 활성화 및 비활성화하는 방법을 설명합니다. Copilot의 클라우드 및 로컬 샌드박스에 대한 개념적 개요는 로컬 샌드박싱 정보 GitHub Copilot을 참조하세요. 샌드박스 설정 조정에 대한 자세한 내용은 로컬 샌드박스 설정 구성을 참조하세요.

로컬 샌드박싱 사용에 대한 자세한 내용은 VS Code 문서의 Visual Studio Code샌드박스 에이전트 터미널 명령을 참조하세요.

Prerequisites

  • Windows: Windows에서 로컬 샌드박싱을 사용하려면 ProcessContainer 백 엔드의 BaseContainer 계층을 지원하는 업데이트 KB5124010 이상이 설치된 Windows 11 버전 25H2 또는 업데이트 KB5124006 이상이 설치된 Windows 11 버전 26H1이 필요합니다.
  • Linux: Bubblewrap(bwrap) 버전 0.5.0 이상과 slirp4netns도 설치되어 PATH에서 사용할 수 있어야 합니다.

Copilot CLI에서 로컬 샌드박싱 사용

로컬 샌드박싱을 Copilot CLI 사용하도록 설정하면 운영 체제 샌드박스 내에서 사용자 대신 호출하는 대부분의 명령과 도구를 실행합니다. 로컬 샌드박싱을 사용하도록 설정한 후에는 사용하지 않도록 설정하거나 특정 세션에 대해 해제할 때까지 모든 Copilot CLI 세션에 사용됩니다. 엔터프라이즈 관리 설정에서 샌드박싱이 필요하면 일반적인 구성이나 --no-sandbox 명령줄 옵션으로는 이를 비활성화할 수 없습니다. 그러나 유효 정책이 샌드박스 바이패스를 허용하는 경우 활성 바이패스 권한 프롬프트에서 또는 실행 /sandbox disable하여 현재 세션의 나머지 부분에 대해 샌드박싱을 명시적으로 사용하지 않도록 설정할 수 있습니다. 이 세션 옵트아웃은 저장된 정책을 완화하지 않습니다.

기본적으로 샌드박스 명령 및 도구는 현재 작업 디렉터리 및 임시 폴더 내에서 작성할 수 있습니다. Git 리포지토리에서 리포지토리의 Git 메타데이터도 쓰기 가능하지만 현재 작업 디렉터리 위의 나머지 리포지토리는 읽을 수 있지만 쓰기가 불가능합니다. 선택한 시스템 및 개발자 도구 위치는 읽을 수 있으며 일부 빌드 및 패키지 캐시는 쓰기가 가능합니다. 이렇게 하면 전체 홈 디렉터리에 대한 액세스 권한이 부여되지 않습니다. 액세스 권한을 부여하지 않으면 다른 경로가 차단됩니다.

아웃바운드 인터넷 액세스는 기본적으로 사용 설정되어 있습니다. 로컬 네트워크 액세스가 꺼져 있습니다. 이러한 설정이 명령에 미치는 영향은 운영 체제에 따라 달라집니다. 로컬 샌드박스 설정 구성을(를) 참조하세요.

Git 및 GitHub CLI(gh)에 대한 인증은 기본적으로 사용하도록 설정되어 있지만 gh pr create 및 git push와 같은 작업은 네트워크 설정 및 도구 호환성에 따라 달라집니다. 샌드박스 명령 및 스크립트는 자리 표시자 Git 및 gh 자격 증명을 받습니다. 로컬 프록시는 승인된 HTTPS 대상에 대해서만 이를 실제 자격 증명으로 대체합니다.

Git 자격 증명은 원래 호스트, 포트 및 리포지토리 경로 제한을 유지합니다. gh의 경우 자격 증명은 api.github.com, uploads.github.com 및 github.com에만 사용됩니다. /sandbox config의 자격 증명 탭에서 인증을 끌 수 있습니다.

API 토큰과 같은 추가 환경 변수를 마스킹할 수도 있습니다. 샌드박스 내에서 실행되는 명령, 로컬 MCP 서버 및 언어 서버는 이러한 변수에 대한 자리 표시자를 받습니다. 프록시는 지정한 HTTPS 호스트에만 각 실제 값을 제공합니다. 설치 지침은 로컬 샌드박스 설정 구성을(를) 참조하세요.

Windows에서는 샌드박스에서 컴퓨터의 서비스(호스트 루프백)로의 연결을 지원하는 버전이 필요합니다. 또한 **** 의 /sandbox config 탭에서 로컬 네트워크 허용을 사용하도록 설정해야 합니다. 또한 자격 증명 프록시에 대한 액세스뿐만 아니라 프라이빗 네트워크 액세스를 허용합니다.

샌드박싱 Copilot CLI에 대한 개념적 개요는 로컬 샌드박싱 정보 GitHub Copilot을 참조하세요.

샌드박스 명령

Copilot CLI 세션 내에서 /sandbox 슬래시 명령을 사용하여 로컬 샌드박싱을 관리합니다. 다음과 같은 하위 명령이 있습니다.

Command설명
/sandbox status샌드박싱이 현재 세션에 사용되고 있는지 여부를 표시합니다.
샌드박싱이 사용되고 있는지 여부를 확인하세요.
/sandbox policy [COMMAND]현재 디렉터리에 대한 유효 경로, 네트워크 설정 및 기능을 표시합니다. 필요에 따라 명령을 실행하지 않고 해당 명령이 받게 될 개발자 도구 액세스를 검사하는 명령을 포함합니다. 자세한 내용은 에서 로컬 샌드박싱에 대한 파일 시스템 정책 이해 GitHub Copilot CLI을(를) 참조하세요.
/sandbox config대화형 설정 인터페이스를 엽니다.
/sandbox만 입력해도 같은 결과가 나타납니다. 자세한 내용은 로컬 샌드박스 설정 구성을(를) 참조하세요.
/sandbox enable로컬 샌드박싱을 켜세요.
로컬 샌드박싱 활성화를 참조하세요.
/sandbox disable로컬 샌드박싱을 끕니다. 엔터프라이즈 관리 설정에 샌드박싱이 필요한 경우 유효 정책이 샌드박스 바이패스를 허용하지 않는 한 거부됩니다. 이 경우 현재 세션의 나머지 부분에 대해서만 샌드박싱을 사용하지 않도록 설정합니다.
로컬 샌드박싱 사용 안 함을 참조하세요.

로컬 샌드박스 활성화

로컬 샌드박싱을 사용하도록 설정하려면 대화형 Copilot CLI 세션에서 다음 명령을 입력합니다.

Shell
/sandbox enable

샌드박싱은 현재 세션에 즉시 사용되기 시작합니다.

로컬 샌드박싱을 사용하도록 설정하면 현재 및 향후 대화형 세션 및 프로그래밍 방식 세션에 계속 사용됩니다.

참고

입력 /sandbox enable할 때 다른 세션이 열려 있는 경우 샌드박싱은 해당 세션에서 즉시 사용되지 않습니다. 이미 열려 있는 세션에서 샌드박싱을 사용하려면 해당 세션에서 다음 중 하나를 수행합니다.

  • 세션을 닫고 다시 시작합니다(예: 를 실행하여) copilot --continue.

/sandbox enable를 입력합니다.

로컬 샌드박싱 사용 안 함으로 설정

엔터프라이즈 관리 설정에 샌드박싱 /sandbox disable 이 필요한 경우 유효 정책이 샌드박스 바이패스를 허용하지 않는 한 거부됩니다. 바이패스가 허용되면 활성 바이패스 권한 프롬프트를 실행 /sandbox disable하거나 활성 바이패스 권한 프롬프트에 응답하면 저장된 정책을 풀지 않고 현재 세션의 나머지 세션에 대해서만 샌드박싱을 사용하지 않도록 설정합니다.

로컬 샌드박싱 사용을 중지하려면 대화형 Copilot CLI 세션에서 다음 명령을 입력합니다.

Shell
/sandbox disable

엔터프라이즈 관리 설정에 샌드박싱이 필요하지 않은 경우 이 설정은 현재 세션과 새 세션 및 다시 시작된 세션에서 샌드박싱을 해제합니다. 바이패스를 허용하는 관리형 정책에서는 현재 세션에 대해서만 샌드박싱을 해제합니다.

일반적인 활성화 또는 비활성화 명령은 선택 사항을 개인 설정 파일에 sandbox.enabled로 저장합니다(~/.copilot/settings.json 기본적으로). 관리되는 세션 전용 옵트아웃은 이 파일을 변경하지 않습니다. 해당 세션에서 샌드박싱을 복원하려면 /sandbox enable을 실행하여 합니다.

단일 세션에 샌드박싱 사용

--sandbox 명령줄 옵션을 사용하면 다른 세션에서 샌드박싱을 활성화하지 않고도 단일 세션에만 샌드박싱을 사용할 수 있습니다. 샌드박싱을 이미 사용하도록 설정한 경우 이 옵션을 사용하여 --no-sandbox 단일 세션에 대해 사용하지 않도록 설정할 수 있습니다. 이 --no-sandbox 옵션은 샌드박싱이 필요한 엔터프라이즈 관리 설정을 재정의할 수 없습니다.

이러한 옵션을 -p 명령줄 옵션과 함께 사용하여 CLI를 프로그래밍 방식으로 사용할 때의 샌드박싱을 제어할 수 있습니다. 다음은 그 예입니다.

Shell
copilot --sandbox -p "PROMPT"

샌드박스 외부에서 단일 명령 실행

샌드박스가 명령을 차단하는 경우 Copilot 더 광범위한 액세스 권한으로 다시 시도할 수 있도록 승인을 요청할 수 있습니다. 프롬프트는 명령 및 제안된 재시도를 설명합니다. 이를 승인하거나 차단된 결과를 유지하거나 샌드박싱을 현재 세션의 나머지 동안 사용하지 않도록 설정할 수 있습니다. 세션에 대한 샌드박싱을 사용하지 않도록 설정하는 것은 유효 정책이 샌드박스 바이패스를 허용하는 경우에만 사용할 수 있습니다. 허용되는 경우 언제든지 실행 /sandbox disable하여 이 작업을 수행할 수도 있습니다.

바이패스 요청은 기본적으로 사용하도록 설정되며 샌드박스 설정에서 해제할 수 있습니다.

승인된 바이패스 명령은 자격 증명 마스킹 및 샌드박스 프록시를 건너뜁니다. 이 명령은 실제 비밀 값을 포함할 수 있는 일반적인 환경에서 실행되며. 마스킹된 변수 호스트 제한은 샌드박스 외부에서 실행되는 명령을 보호하지 않습니다.

샌드박스는 명령이 실패할 수 있는 이유 중 하나일 뿐입니다. Copilot 는 샌드박스가 원인일 가능성이 높고 외부에서 실행되는 것이 실제로 도움이 될 수 있는 경우에만 더 광범위한 액세스 권한으로 재시도를 제공합니다. 다른 실패는 바이패스 메시지를 표시하지 않습니다. 플랫폼별 재시도 동작은 로컬 샌드박스 설정 구성을 참조하세요.

샌드박싱 사용 여부 확인

현재 세션에 로컬 샌드박싱이 사용되고 있는지 확인하려면 다음을 입력합니다.

Shell
/sandbox status

Copilot CLI 는 세션에 샌드박싱을 사용할 수 있는지 여부를 보고합니다. 조직의 관리되는 설정에 샌드박싱이 필요한 경우 상태도 이를 적어 줍니다. 상태는 세션이 실제로 적용하는 내용을 반영하기 때문에 명령 Copilot 실행이 샌드박스로 실행되는지 확인하는 신뢰할 수 있는 방법입니다.

샌드박싱이 켜졌는지 여부뿐만 아니라 읽을 수 있거나 쓰기 가능하거나 차단된 경로를 정확히 확인하려면 다음을 입력합니다 /sandbox policy. 자세한 내용은 에서 로컬 샌드박싱에 대한 파일 시스템 정책 이해 GitHub Copilot CLI을(를) 참조하세요.

상태 줄에는 샌드박스가 사용 중일 때 sandbox enabled가 표시되므로, 여기서도 샌드박스 상태를 한눈에 확인할 수 있습니다. 상태 줄의 샌드박스 정보 표시는 기본적으로 설정되어 있습니다. 꺼진 경우 다시 켤 수 있습니다.

  1. /statusline를 입력합니다.
  2. 선택 영역을 샌드박스로 옵션 목록 아래로 이동합니다.
  3. Enter 키를 눌러 확인 표시가 표시되도록 설정을 전환합니다.

Troubleshooting

다음 지침을 사용하여 차단된 명령, Windows PowerShell 및 Git 문제, 그리고 인증 실패 문제를 해결하는 데 사용하세요.

차단된 명령 문제 해결

명령이 파일에 액세스할 수 없거나 도구를 사용하거나 호스트에 연결할 수 없는 경우 더 광범위한 액세스 권한을 부여하기 전에 샌드박스 정책을 확인합니다.

  1. 현재 세션에서 샌드박싱이 켜져 있는지 확인하려면 /sandbox status을 실행합니다.

  2. 실행 /sandbox policy 하여 유효 정책을 검사합니다. 명령에서 사용하는 도구에 사용할 수 있는 추가 경로를 보려면 /sandbox policy 뒤에 명령을 포함하세요. 다음은 그 예입니다.

    Shell
    /sandbox policy npm install

    실행하지 않고 npm install정책을 미리 봅니다. 나열된 경로 및 네트워크 설정을 검토합니다. 적용할 수 없는 설정에 대한 참고 사항을 확인하세요.

  3. 정책이 허용하려는 액세스를 차단하는 경우 /sandbox config를 사용하여 필요한 경로 또는 호스트 규칙을 업데이트하세요. 명령에 필요한 액세스 권한만 부여합니다. 누락된 경로 및 기호 링크는 에서 로컬 샌드박싱에 대한 파일 시스템 정책 이해 GitHub Copilot CLI을 참조하세요. 저장된 샌드박스 설정을 변경하지 않고 현재 세션에 대해서만 디렉터리에 대한 읽기 및 쓰기 권한을 부여하려면 /add-dir PATH를 사용합니다. 이러한 방식으로 부여된 액세스는 여전히 조직에서 관리하는 샌드박스 정책의 적용을 받습니다.

  4. 조직에서 설정을 관리하는 경우 관리자에게 문의하세요. 오류가 누락된 운영 체제 기능 또는 Linux 종속성의 이름을 지정하는 경우 해당 요구 사항을 해결한 다음 Copilot CLI를 다시 시작한 후 다시 시도하십시오.

  5. Copilot에게 명령을 다시 실행하도록 요청합니다. 하나의 명령 바이패스(bypass)가 제공되는 경우 설명된 광범위한 액세스가 괜찮다고 판단되는 경우에만 승인합니다. 전체 세션에 샌드박싱을 사용하지 않도록 설정하면 차단된 명령뿐만 아니라 후속 명령에 더 광범위한 액세스 권한이 부여됩니다.

존재하지 않는 차단 경로 문제 해결

샌드박스 설정은 특정 파일 또는 디렉터리에 대한 액세스를 차단할 수 있습니다. 차단된 경로가 컴퓨터에 없는 경우 Copilot CLI는 샌드박스 명령을 시작하기 전에 해당 위치에 디렉터리를 만듭니다. 또한 누락된 부모 디렉터리를 만듭니다. 이러한 디렉터리들은 나중에 자동으로 제거되지 않습니다.

예를 들어 해당 파일이 존재하기 전에 Copilot CLI에 대한 액세스를 차단하면 .env는 파일이 아니라 .env라는 디렉터리를 만듭니다.

  • 차단된 경로가 파일로 의도된 경우 샌드박스 명령을 실행하기 전에 샌드박스 외부에서 해당 파일을 만듭니다.
  • Failed to prepare denied sandbox path가 표시되면 명령이 시작되지 않았습니다. 구성된 경로가 올바르고 계정에 디렉터리를 만들 수 있는 권한이 있는지 확인합니다. /sandbox config를 사용하여 의도하지 않은 경로를 수정하거나 설정이 관리되는 경우 관리자에게 문의하세요.

/sandbox policy을 실행해도 이러한 디렉터리는 생성되지 않습니다. Linux에서 아직 존재하지 않는 경로는 미리 보기에 표시된 유효 정책에서 생략됩니다. 사용자가 구성한 설정에 그대로 남아 있습니다.

Windows PowerShell 및 Git 문제 해결

필요한 업데이트가 없는 Windows 설치 시 샌드박스가 설치된 PowerShell은 현재 디렉터리로 C:\와 같은 드라이브 루트를 보고할 수 있습니다. Set-Location PowerShell이 시작되더라도 현재 디렉터리를 사용하는 Git 명령이 실패할 수 있습니다.

  1. 지원되는 Windows 버전에 대해 2026년 9월 업데이트 또는 그 이후 버전을 설치합니다. 조직에서 Windows 업데이트를 관리하는 경우 관리자에게 문의하세요.

  2. 즉시 업데이트할 수 없는 경우 Copilot에게 Git 명령에 절대 리포지토리 경로를 사용하도록 요청합니다. 다음은 그 예입니다.

    Shell
    git -C "C:\PATH\TO\REPOSITORY" status

    이렇게 하면 PowerShell의 현재 디렉터리에 의존하지 않습니다. 샌드박스는 여전히 리포지토리에 대한 액세스를 허용해야 합니다. 이 작업은 다른 파일 시스템 또는 인증 관련 실패를 해결하지 않습니다.

인증 문제 해결

자격 증명 마스킹을 사용하도록 설정하면 Copilot CLI는 로컬 프록시를 사용하여 나가는 요청에 실제 자격 증명을 추가합니다. 이러한 자격 증명을 사용하는 도구는 프록시를 지원하고 해당 보안 인증서를 신뢰해야 합니다.

Copilot CLI 는 샌드박스가 적용된 도구에 임시 인증서 번들을 자동으로 제공합니다. 일부 도구는 이 번들을 사용하지 않으며 인증서 또는 인증 오류를 보고할 수 있습니다.

macOS 및 Windows에서 필요에 따라 운영 체제의 신뢰 저장소에 프록시의 인증 기관(CA) 인증서를 설치하여 호환성을 향상시킬 수 있습니다. Copilot CLI 세션에서 /sandbox ca create을 실행한 다음 /sandbox ca trust를 실행합니다. Windows에서 인증서를 설치하려면 관리자의 승인이 필요합니다. 이렇게 하면 Copilot CLI 외부의 애플리케이션에 대한 인증서 신뢰도 변경됩니다.

인증서를 설치해도 모든 호환성 문제가 해결되지는 않습니다. HTTP/2가 필요하거나, 특정 서버 인증서(인증서 고정)만 허용하거나, 클라이언트 인증서를 사용하거나, 자격 증명을 사용하여 요청에 서명하는 도구는 여전히 실패할 수 있습니다.

마스킹된 환경 변수의 경우 CLI에서 변수를 사용할 수 있는지 확인하고, 대상이 해당 주입 호스트와 일치하는지 확인하고, 네트워크 설정이 연결을 허용하는지 확인합니다. 도구는 X-Api-Key 또는 Authorization와 같은 자리 표시자를 HTTPS 요청 헤더에서 자격 증명으로 보내야 합니다. 자리 표시자가 암호인 경우에도 HTTP 기본 인증이 작동합니다. 일반 텍스트 HTTP, 요청 본문, URL 및 서명된 요청은 실제 값을 받지 않습니다.

마스킹은 구성된 환경 변수와 활성화된 Git 및 gh 인증만 보호합니다. 자격 증명 파일, 다른 환경 변수 또는 원격 MCP 인증에서 비밀을 숨기지 않습니다.

Copilot app에서 로컬 샌드박싱 사용

적용할 수 있는 엔터프라이즈 관리 설정에 따라 슬래시 명령을 사용하여 현재 활성 세션에 대한 로컬 샌드박스를 사용하거나 사용하지 않도록 설정할 수 있습니다.

세션에 대한 샌드박싱 활성화 및 비활성화

로컬 샌드박싱을 켜려면 다음을 입력합니다.

/sandbox on

샌드박싱을 끄려면 다음을 입력합니다.

/sandbox off

엔터프라이즈 관리 설정이 변경을 방지하지 않는 한 이러한 명령은 샌드박싱을 즉시 켜거나 끕니다. 선택한 내용은 다시 시작한 후를 포함하여 현재 세션에 적용되며 리포지토리 기본값보다 우선합니다. 다른 세션의 리포지토리 기본값은 변경되지 않습니다.

로컬 샌드박싱이 해제된 경우 에이전트 실행 명령은 사용자 계정과 동일한 파일, 네트워크 및 자격 증명에 액세스할 수 있습니다.

클라우드 샌드박스 세션 또는 원격 호스트에서 실행되는 세션에는 로컬 샌드박싱을 사용할 수 없습니다.

참고

  • 세션이 시작되기 전에 위의 명령 중 하나를 입력하는 경우(예: 새로를 클릭하고, 리포지토리 또는 로컬 폴더를 선택한 다음, 명령을 입력) 명령은 선택한 리포지토리 또는 폴더에 대한 기본 샌드박싱 설정을 변경합니다. 또는 설정에서 기본값을 설정할 수 있습니다. 로컬 샌드박스 설정 구성을(를) 참조하세요.
  • CLI와 달리 /sandbox 또는 off 없이 on을 입력해도 구성 인터페이스가 열리지 않습니다.

샌드박스 외부에서 도구 실행

샌드박스 정책이 허용하지 않는 액세스 권한이 도구에 필요한 경우 앱은 샌드박스 외부에서 실행을 표시할 수 있나요? 프롬프트입니다. 유효한 정책에 따라 다음을 수행할 수 있습니다.

  • 작업을 취소합니다.
  • 샌드박스 외부에서 작업을 한 번 실행합니다.
  • 현재 세션의 나머지 부분에 대해 샌드박싱을 사용하지 않도록 설정하고 작업을 실행합니다.

이 프롬프트에서 샌드박싱을 사용하지 않도록 설정하려면 추가 옵션을 클릭한 다음 샌드박스 비활성화 후 실행을 클릭하고 선택을 확인합니다.

이 프롬프트에서 샌드박싱을 사용하지 않도록 설정하면 앱은 이 세션에 대해 샌드박스를 해제합니다. 샌드박스 다시 사용을 클릭하여 다시 켤 수 있습니다.

샌드박싱을 일시적으로 사용하지 않도록 설정해도 리포지토리 기본값이나 세션의 저장된 설정은 변경되지 않습니다. 세션이 다시 시작되거나 다시 연결되면 종료됩니다.

엔터프라이즈 소유자는 사용자가 샌드박스 외부에서 도구를 실행하지 못하도록 할 수 있습니다. 자세한 내용은 엔터프라이즈 관리 설정을(를) 참조하세요.

추가 읽기