Usando o sandbox local

Introduction

O isolamento local restringe o acesso a arquivos, recursos de rede e credenciais em seu computador. Este artigo explica como habilitar e desabilitar o sandboxing local dentro Copilot CLI e no Copilot app. Para uma visão geral conceitual das sandboxes na nuvem e locais para Copilot, consulte Sobre o sandboxing local para GitHub Copilot. Para obter informações sobre como ajustar as configurações de sandbox, consulte Configurando as configurações locais da sandbox.

Para obter informações sobre como usar o sandboxing local, Visual Studio Codeconsulte comandos de terminal do agente sandbox na documentação VS Code.

Prerequisites

• Windows: o isolamento local no Windows requer Windows 11 versão 25H2 com atualização KB5124010 ou posterior, ou Windows 11 versão 26H1 com atualização KB5124006 ou posterior, com suporte para a camada BaseContainer do back-end ProcessContainer.
• Linux: O Bubblewrap (bwrap), versão 0.5.0 ou posterior, e slirp4netns devem estar instalados e disponíveis no PATH.

Usando sandbox local em Copilot CLI

Quando você habilita o sandboxing local, Copilot CLI executa a maioria dos comandos e ferramentas que ele invoca em seu nome dentro de uma área restrita do sistema operacional. Depois de ativar o sandboxing local, ele será usado em todas as suas sessões Copilot CLI até você desativá-lo ou desligá-lo para uma sessão específica. Se as configurações gerenciadas da empresa exigirem isolamento em sandbox, a configuração normal e a opção de linha de comando --no-sandbox não poderão desativá-lo. No entanto, se a política efetiva permitir ignorar o sandbox, você poderá desativar explicitamente o sandbox pelo restante da sessão atual, seja a partir de uma solicitação ativa de permissão para ignorar o sandbox ou executando /sandbox disable. Esta desativação da sessão não flexibiliza a política salva.

Por padrão, comandos e ferramentas em sandbox podem gravar no diretório de trabalho atual e em pastas temporárias. Em um repositório Git, os metadados git do repositório também são graváveis, enquanto o restante do repositório acima do diretório de trabalho atual é legível, mas não gravável. Os locais selecionados do sistema e da ferramenta de desenvolvedor são legíveis e alguns caches de build e pacote são graváveis. Isso não concede acesso a todo o diretório pessoal. Outros caminhos são bloqueados, a menos que você conceda acesso.

O acesso à Internet de saída está ativado por padrão. O acesso à rede local está desativado. A forma como essas configurações afetam os comandos depende do sistema operacional. Consulte Configurando as configurações locais da sandbox.

A autenticação para Git e GitHub CLI (gh) é habilitada por padrão, mas operações como git push e gh pr create dependem das configurações de rede e da compatibilidade da ferramenta. Os comandos e scripts em área restrita recebem credenciais Git e gh de espaço reservado. Um proxy local substitui essas informações por suas credenciais reais apenas para destinos HTTPS aprovados.

As credenciais do Git mantêm suas restrições de caminho de host, porta e repositório originais. Para gh, as credenciais são usadas apenas para github.com, api.github.come uploads.github.com. Você pode desabilitar a autenticação na guia Credenciais em /sandbox config.

Você também pode mascarar variáveis de ambiente adicionais, como tokens de API. Comandos, servidores MCP locais e servidores de linguagem executados dentro da área restrita recebem espaços reservados para essas variáveis. O proxy fornece cada valor real apenas para os hosts HTTPS especificados. Para obter instruções de configuração, confira Configurando as configurações locais da sandbox.

No Windows, isso requer uma versão que dê suporte a conexões do sandbox aos serviços no seu computador (loopback do host). Você também deve habilitar Permitir rede local na guia Rede em /sandbox config. Isso também permite o acesso à rede privada, não apenas o acesso ao proxy de credencial.

Para obter uma visão geral conceitual do sandboxing em Copilot CLI, consulte Sobre o sandboxing local para GitHub Copilot.

Comandos de sandbox

Você gerencia o sandbox local de dentro de uma Copilot CLI sessão usando o comando de barra /sandbox. Possui os seguintes subcomandos.

Ativando o sandbox local

Para habilitar o sandboxing local, insira o seguinte comando em uma sessão interativa Copilot CLI :

/sandbox enable

/sandbox enable

O sandboxing começa a ser usado imediatamente para a sessão atual.

Depois de habilitar o sandboxing local, ele continuará a ser usado para as sessões interativas atuais e futuras e para sessões programáticas.

Desabilitando o sandboxing local

Se as configurações gerenciadas pela empresa exigirem isolamento em sandbox, /sandbox disable será recusado, a menos que a política efetiva permita ignorar o isolamento em sandbox. Quando a permissão de bypass é permitida, executar /sandbox disable — ou responder a uma solicitação de permissão de bypass ativa — desativa o sandbox apenas para o restante da sessão atual, sem flexibilizar a política salva.

Para parar de usar o sandboxing local, insira o seguinte comando em uma sessão interativa Copilot CLI :

/sandbox disable

/sandbox disable

A menos que as configurações gerenciadas pela empresa exijam isolamento em sandbox, isso desativa esse recurso na sessão atual e em sessões novas e reiniciadas. Em uma política gerenciada que permite desvio, ela desativa o sandbox apenas para a sessão atual.

Um comando comum para habilitar ou desabilitar salva sua escolha como sandbox.enabled no arquivo de configurações pessoais (~/.copilot/settings.json por padrão). Uma desativação somente de sessão gerenciada não altera esse arquivo. Execute /sandbox enable para restaurar o sandboxing nessa sessão.

Usando o sandbox para uma única sessão

Você pode usar a opção --sandbox de linha de comando para usar o sandboxing para uma única sessão, sem habilitar o sandboxing para suas outras sessões. Se o sandboxing já estiver habilitado, você poderá desabilitá-lo para uma única sessão usando a opção --no-sandbox . A opção --no-sandbox não pode substituir as configurações gerenciadas pela empresa que exigem sandbox.

Você pode combinar essas opções com a opção -p de linha de comando para controlar o sandboxing para uso programático da CLI. Por exemplo:

copilot --sandbox -p "PROMPT"

copilot --sandbox -p "PROMPT"

Executar um único comando fora da sandbox

Quando a área restrita bloqueia um comando, Copilot pode pedir que você aprove outra tentativa com acesso mais amplo. O prompt descreve o comando e a nova tentativa proposta. Você pode aprová-lo, manter o resultado bloqueado ou desabilitar o sandbox para o restante da sessão atual. Desabilitar a sandbox na sessão só estará disponível se a política efetiva permitir ignorar a sandbox. Quando isso é permitido, você também pode fazer isso a qualquer momento executando /sandbox disable.

As solicitações de bypass são habilitadas por padrão e podem ser desativadas nas configurações da sandbox.

Um bypass de comando aprovado ignora o mascaramento de credenciais e o proxy do sandbox. O comando é executado com seu ambiente comum, que pode conter valores de segredo reais. Restrições de host de variável mascarada não protegem um comando executado fora da sandbox.

A sandbox é apenas um dos motivos pelos quais um comando pode falhar. Copilot oferece uma nova tentativa com acesso mais amplo somente quando a sandbox é a causa provável e a execução fora dela pode realmente ajudar. Outras falhas não mostram nenhum prompt de bypass. Para obter um comportamento de repetição específico da plataforma, consulte Configurando as configurações locais da sandbox.

Verificando se o sandboxing está sendo usado

Para verificar se o sandboxing local está sendo usado para a sessão atual, insira:

/sandbox status

/sandbox status

Copilot CLI informa se o sandboxing está habilitado para a sessão. Se as configurações gerenciadas da sua organização exigirem isolamento em sandbox, o status também indicará isso. Como o status reflete o que a sessão realmente aplica, esta é a forma confiável de confirmar se os comandos que Copilot executa estão sendo executados em sandbox.

Para ver não apenas se o isolamento em sandbox está habilitado, mas exatamente quais caminhos podem ser lidos, gravados ou bloqueados, digite /sandbox policy. Para obter mais informações, consulte Noções básicas sobre políticas de sistema de arquivos para área restrita local em GitHub Copilot CLI.

Você também pode ver de imediato o status do sandbox na linha de status, que contém sandbox enabled quando o modo sandbox está sendo usado. A exibição das informações da sandbox na linha de status é ativada por padrão. Se ele tiver sido desativado, você poderá ativá-lo novamente:

1. Insira /statusline.
2. Mova a seleção para baixo na lista de opções para área restrita.
3. Pressione Enter para alternar a configuração para que ela mostre uma marca de seleção.

Troubleshooting

Use as diretrizes a seguir para solucionar problemas de comandos bloqueados, do PowerShell e do Git em Windows e falhas de autenticação.

Solução de problemas de comandos bloqueados

Se um comando não puder acessar um arquivo, usar uma ferramenta ou se conectar a um host, verifique a política de área restrita antes de conceder acesso mais amplo.

1. Execute /sandbox status para confirmar se o sandboxing está ativado para a sessão atual.

2. Execute /sandbox policy para inspecionar a política efetiva. Para ver os caminhos adicionais disponíveis para ferramentas usadas por um comando, inclua o comando após /sandbox policy. Por exemplo:

   Shell

   /sandbox policy npm install
   

   Isto mostra a prévia da política sem executar npm install. Examine os caminhos listados e as configurações de rede. Verifique Notas sobre as configurações que não puderam ser aplicadas.

3. Se a política bloquear o acesso que você pretende permitir, use /sandbox config para atualizar as regras de caminho ou de host necessárias. Conceda apenas o acesso de que o comando precisa. Para caminhos ausentes e links simbólicos, consulte Noções básicas sobre políticas de sistema de arquivos para área restrita local em GitHub Copilot CLI. Para conceder acesso de leitura e gravação a um diretório somente para a sessão atual, sem alterar as configurações de área restrita salvas, use /add-dir PATH. O acesso concedido dessa forma ainda está sujeito a qualquer política de sandbox gerenciada pela sua organização.

4. Se a configuração for gerenciada pela sua organização, contate o administrador. Se o erro nomeia um recurso de sistema operacional ausente ou dependência do Linux, resolva esse requisito e reinicie Copilot CLI antes de tentar novamente.

5. Peça Copilot para executar o comando novamente. Se um bypass de um comando for oferecido, aprove-o somente se você estiver confortável com o acesso mais amplo descrito. Desabilitar o sandbox para toda a sessão fornece aos comandos subsequentes acesso mais amplo, não apenas ao comando bloqueado.

Solução de problemas de caminhos inexistentes bloqueados

Suas configurações de área restrita podem bloquear o acesso a arquivos ou diretórios específicos. Se um caminho bloqueado não existir em seu computador, Copilot CLI criará um diretório nesse local antes de iniciar um comando em sandbox. Ele também cria todos os diretórios pai ausentes. Esses diretórios não são removidos automaticamente posteriormente.

Por exemplo, se você bloquear o acesso a .env antes que esse arquivo exista, Copilot CLI criará um diretório nomeado .env, não um arquivo.

• Se o caminho bloqueado for destinado a ser um arquivo, crie esse arquivo fora da área restrita antes de executar um comando em área restrita.
• Se você vir Failed to prepare denied sandbox path, o comando não foi iniciado. Verifique se o caminho configurado está correto e se sua conta tem permissão para criar diretórios lá. Use /sandbox config para corrigir um caminho não intencional ou contate o administrador se a configuração for gerenciada.

A execução /sandbox policy não cria esses diretórios. No Linux, os caminhos que ainda não existem são omitidos da política efetiva mostrada na visualização. Elas permanecem nas suas configurações definidas.

Solução de problemas do PowerShell e do Git no Windows

Em instalações do Windows sem as atualizações necessárias, o PowerShell em área restrita pode relatar uma raiz da unidade, como C:\, como seu diretório atual. Set-Location E os comandos git que dependem do diretório atual podem falhar mesmo que o PowerShell seja iniciado.

1. Instale a atualização de setembro de 2026 ou posterior para uma versão de Windows com suporte. Se sua organização gerencia as atualizações do Windows, contate o administrador.

2. Se você não puder atualizar imediatamente, peça Copilot para usar um caminho de repositório absoluto para comandos Git. Por exemplo:

   Shell

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

   Isso evita depender do diretório atual do PowerShell. A sandbox ainda deve permitir o acesso ao repositório. Ele não corrige outras falhas de autenticação ou sistema de arquivos.

Solução de problemas de autenticação

Quando o mascaramento de credenciais está habilitado, Copilot CLI usa um proxy local para adicionar as credenciais reais às solicitações de saída. As ferramentas que usam essas credenciais devem dar suporte ao proxy e confiar em seu certificado de segurança.

Copilot CLI fornece automaticamente um pacote de certificado temporário para ferramentas em área restrita. Algumas ferramentas não usam esse pacote e podem relatar erros de certificado ou autenticação.

No macOS e Windows, opcionalmente, você pode instalar a autoridade de certificação do proxy no repositório de confiança do sistema operacional para melhorar a compatibilidade. Em uma Copilot CLI sessão, execute /sandbox ca create, em seguida /sandbox ca trust. No Windows, a instalação do certificado requer aprovação do administrador. Isso também altera a confiança do certificado para aplicativos fora de Copilot CLI.

A instalação do certificado não resolve todos os problemas de compatibilidade. Ferramentas que exigem HTTP/2, aceitam apenas certificados de servidor específicos (fixação de certificado), usam certificados de cliente ou usam credenciais para assinar solicitações ainda podem falhar.

Para variáveis de ambiente mascaradas, verifique se a variável está disponível para a CLI, se o destino corresponde aos hosts de injeção e as configurações de rede permitem a conexão. As ferramentas devem enviar o marcador como uma credencial em um cabeçalho de solicitação HTTPS, como Authorization ou X-Api-Key. A autenticação HTTP Basic também funciona quando o placeholder é a senha. HTTP em texto simples, corpos de solicitação, URLs e solicitações assinadas não recebem o valor real.

O mascaramento protege apenas as variáveis de ambiente configuradas e o Git e a autenticação gh habilitados. Ele não oculta segredos em arquivos de credencial, outras variáveis de ambiente ou autenticação remota do MCP.

Usar o isolamento local em sandbox no Copilot app

Dependendo de qualquer configuração gerenciada da empresa que possa ser aplicada, você pode usar comandos slash para habilitar ou desabilitar o sandbox local para a sessão ativa no momento.

Como habilitar e desabilitar o isolamento em sandbox para sua sessão

Para ativar o sandboxing local, insira:

/sandbox on

Para desativar o isolamento em sandbox, insira:

/sandbox off

Esses comandos ativam ou desativam o sandboxing imediatamente, a menos que as configurações gerenciadas pela empresa impeçam a alteração. Sua escolha se aplica à sessão atual, inclusive após uma reinicialização, e tem precedência sobre o padrão do repositório. Ele não altera o padrão do repositório para outras sessões.

Quando o isolamento local está desativado, os comandos executados pelo agente podem acessar os mesmos arquivos, redes e credenciais que a sua conta de usuário.

Você não pode usar o isolamento local para uma sessão de sandbox na nuvem ou uma sessão que é executada em um host remoto.

Executar uma ferramenta fora do sandbox

Se uma ferramenta precisar de acesso que a política de sandbox não permite, o aplicativo pode exibir a solicitação Executar fora da sandbox?. Dependendo da política efetiva, você pode:

• Cancele a operação.
• Execute a operação uma vez fora da sandbox.
• Desabilite o sandboxing para o restante da sessão atual e execute a operação.

Para desabilitar o sandboxing desse prompt, clique em Mais opções, em seguida, Desativar sandbox e executar e confirme sua escolha.

Se você desativar o sandbox neste prompt, o aplicativo exibirá Sandbox desativado nesta sessão. Clique em Reativar sandbox para ativá-la.

Desabilitar temporariamente o sandbox não altera o padrão do repositório ou a configuração salva da sessão. Ela termina quando a sessão é reiniciada ou reanexada.

Um proprietário da empresa pode impedir que os usuários executem ferramentas fora da área restrita. Para obter mais informações, consulte Configurações gerenciadas pela empresa.

Leitura adicional

• Sobre o sandboxing local para GitHub Copilot
• Configurando as configurações locais da sandbox