Sandbox local do GitHub Copilot App: configuração e testes
Guia prático sobre padrões do projeto, substituições de sessão, políticas de arquivos, rede e credenciais, falha segura e verificação.
Conteúdo
Você ativa o sandbox, mas a sessão que já estava aberta continua com as permissões anteriores, ou o agente pede acesso repetidamente para instalar dependências, conectar a um servidor local ou enviar uma branch. O problema costuma estar na combinação entre padrão do projeto, substituição da sessão e controles separados de arquivos, rede e credenciais.
Ao terminar este guia, você poderá escolher uma política inicial para um repositório local ou working tree, aplicar a mudança à sessão correta e confirmar os limites com dados fictícios. O caminho mais curto é: confirmar o tipo de sessão → ativar Sandbox new sessions → restringir as três áreas → iniciar ou reiniciar a sessão → executar testes seguros.
O GitHub anunciou o recurso em 23 de setembro de 2026, e ele continua em prévia pública; interface e comportamento podem mudar. Guarde três limites: o sandbox local vem desativado, a política é definida por projeto e, se o host não conseguir aplicá-la, o shell no sandbox falha em vez de executar silenciosamente o comando sem proteção.
Primeiro confirme se sua sessão está coberta
A política do projeto se aplica apenas a sessões locais de repositório e working tree. Sandboxes na nuvem, hosts remotos e GitHub Copilot CLI usam outros mecanismos, então confira o escopo antes de alterar uma configuração que a sessão alvo não lê.
| Tipo de sessão | É coberta? | Limite importante |
|---|---|---|
| Sessão de repositório local | Sim | Usa as configurações de sandbox do projeto atual |
| Sessão local de working tree | Sim | Um working tree separa branches e arquivos, mas não restringe o acesso a outros locais da máquina; o sandbox fornece essa fronteira |
| Sessão de sandbox na nuvem | Não | Usa o próprio isolamento da sessão em nuvem |
| Sessão executada em host remoto | Não | A política local do projeto não é aplicada ao host remoto |
| GitHub Copilot CLI | Configuração separada | As configurações do Copilot app e do Copilot CLI não substituem uma à outra |
Configurações corporativas gerenciadas podem tornar a política efetiva mais restritiva que a solicitada no projeto. A página do projeto descreve o que o app pede, não necessariamente o acesso máximo que a organização permitirá.
Como ativar o sandbox para novas sessões
Para que as próximas sessões locais usem a política do projeto, ative Sandbox new sessions e crie uma nova sessão; mudar apenas o controle não atualiza uma sessão já aberta. Siga estes passos:
- Abra as configurações do GitHub Copilot app.
- Selecione o projeto que deseja configurar.
- Encontre a seção
Sandbox. - Ative
Sandbox new sessions. - Inicie uma nova sessão local.
A opção afeta somente as sessões criadas depois. Ela não altera uma sessão já em andamento. Mudanças posteriores na política de arquivos, rede ou credenciais também só entram em vigor em novas sessões ou após reiniciar a sessão.
Para manter o histórico da conversa atual e recarregar a política, digite /restart-session.
O GitHub recomenda começar pela política padrão na maioria dos projetos. Ela permite tarefas comuns como instalar dependências, conectar-se a um servidor de desenvolvimento local, enviar uma branch e criar um pull request. Restrinja-a quando o projeto estiver próximo de pastas sensíveis, não precisar de rede ou não deva usar suas credenciais.
Como limitar arquivos, rede e credenciais separadamente
São três controles independentes: restringir arquivos não desativa credenciais, e desativar credenciais não protege uma pasta sensível que continua legível. Ajuste cada área conforme a tarefa em vez de desligar tudo de uma vez.
1. Sistema de arquivos: o que pode ser lido e alterado
Comece com o menor escopo: mantenha leitura e gravação no workspace e adicione outros caminhos só quando a tarefa realmente precisar. Por padrão, a sessão pode ler e gravar no workspace e no diretório atual; as configurações acrescentam três listas:
Additional read/write: pastas extras que as ferramentas do agente podem ler e modificar.Additional read-only: pastas extras que podem ler, mas não modificar.Denied: pastas que não podem acessar.
Uma pasta mais específica em Denied continua negada mesmo quando uma pasta-pai mais ampla tem acesso de leitura ou gravação. Prefira conceder o caminho mínimo necessário em vez de abrir o diretório pessoal inteiro e depender de muitas exceções.
No Windows há uma fronteira importante de imposição. Você pode salvar um caminho negado, mas, se os recursos ativos do sandbox do Windows não puderem garantir a negação, o comando falha com uma mensagem do tipo unsupported-policy. Ele não continua com o caminho exposto e não desativa o sandbox automaticamente.
2. Rede: separe internet e rede local
Se a tarefa instala dependências ou usa um servidor local de desenvolvimento, não bloqueie automaticamente as duas rotas; decida separadamente se precisa de internet e rede local. Por padrão, a sessão alcança ambas, e você pode controlar:
Outbound internet: acesso ao GitHub, registros de pacotes e outros serviços de internet.Local network: conexões de loopback e rede local, incluindo servidores de desenvolvimento locais.
As restrições podem afetar instalação de dependências, chamadas de API, servidores de preview e qualquer ferramenta que precise de conexão. Trate a negação de rede como um compromisso funcional, não como um botão de segurança sem custo.
O Linux tem uma limitação específica: o sandbox não consegue controlar de forma independente o acesso à rede local de processos gerados, como comandos de shell e servidores MCP ou LSP locais. A configuração ainda se aplica a operações dentro do processo, como requisições web e conexões MCP remotas. No Linux, verifique os dois caminhos em vez de testar apenas um.
3. Credenciais: controle Git e GitHub CLI separadamente
Para leitura de código ou análise offline, desative primeiro as credenciais de Git e GitHub CLI; habilite-as apenas quando a tarefa exigir push ou pull request. Por padrão, operações autenticadas ficam disponíveis e você pode desativar:
Git credentials: operações Git HTTPS autenticadas.GitHub CLI credentials: autenticação usada pelo GitHub CLI.
Ao desativá-las, ações como enviar uma branch ou criar um pull request podem deixar de funcionar no sandbox. A política de arquivos e a de credenciais são fronteiras diferentes: mesmo sem credenciais, proteja por regras de arquivo os diretórios que contêm chaves, configurações ou outros dados sensíveis.
Quando mudar o projeto, a sessão atual ou uma operação
Mude o projeto quando sessões futuras devem herdar a regra; use /sandbox on ou /sandbox off para a sessão atual; depois de editar a política do projeto, execute /restart-session se a sessão ativa precisar recarregá-la.
| Ação | Quando entra em vigor | Efeito em outras sessões |
|---|---|---|
Alterar as configurações Sandbox do projeto | Em novas sessões ou após reinício | Muda o padrão herdado por sessões futuras do projeto |
Digitar /sandbox on em uma sessão local ativa | Imediatamente, como substituição persistente dessa sessão | Não altera o padrão do projeto para outras sessões |
Digitar /sandbox off em uma sessão local ativa | Desativa imediatamente o sandbox dessa sessão | Não altera outras sessões; os comandos passam a ter o mesmo acesso a arquivos, rede e credenciais que sua conta de usuário |
Digitar /sandbox on ou /sandbox off antes de iniciar uma sessão | Muda o padrão do projeto herdado por novas sessões | Afeta sessões iniciadas depois com esse padrão |
Digitar /restart-session | Reinicia a sessão atual, mantém o histórico e recarrega a política | Não edita por si só a política do projeto |
Quando uma ferramenta precisa de acesso não permitido, o app pode exibir Run outside the sandbox?. Conforme a política efetiva, você pode cancelar, executar aquela operação uma vez fora do sandbox ou desativá-lo pelo restante da sessão atual. Um proprietário corporativo pode impedir a execução de ferramentas fora do sandbox.
Desativar por esse aviso não reescreve o padrão do projeto nem a substituição existente da sessão. O estado temporário termina quando a sessão reinicia ou é reanexada. Depois de aparecer Sandbox off for this session, use Re-enable sandbox para ativá-lo novamente.
A ordem mais segura é cancelar primeiro e entender por que o comando precisa de mais acesso. Se a necessidade for recorrente, ajuste a política de forma estreita e reinicie. Só execute uma operação uma vez fora do sandbox após revisar o comando, os argumentos e o impacto. Em um repositório desconhecido ou com comando montado dinamicamente a partir de um Prompt, evite desativar o sandbox inteiro por conveniência.
Se o host não impuser a política, o comando para
Se o sistema operacional não puder aplicar uma regra, o resultado seguro é a falha do comando, não uma continuação automática sem sandbox.
O GitHub Copilot app aceita as configurações antes de saber se o sistema operacional consegue aplicar todas elas. A compatibilidade é verificada quando o primeiro shell no sandbox começa.
Se o host não conseguir impor a política solicitada:
- O shell mostra
unsupported-platformouunsupported-policy. - O comando não continua sem sandbox.
- Se o app mostrar
Sandbox unavailable, corrija o problema relatado e selecioneRetry sandbox.
Esse é um comportamento fail-closed, não uma execução de melhor esforço. Salvar as configurações com sucesso não prova que a política está ativa na máquina. Inicie pelo menos um shell no sandbox, confirme que não aparece mensagem de incompatibilidade e faça uma verificação mínima.
Como verificar a política com dados fictícios
O GitHub descreve o comportamento esperado, mas só um teste na sua máquina confirma que aquela combinação de sistema operacional e regras funciona. O procedimento usa pastas descartáveis e arquivos fictícios, sem tocar em chaves reais ou configuração de produção.
Crie pastas descartáveis fora do workspace e coloque nelas apenas arquivos fictícios. Não use chaves SSH reais, credenciais de nuvem ou configuração de produção.
| Verificação | Procedimento seguro | Comportamento esperado |
|---|---|---|
| Herança de nova sessão | Ative Sandbox new sessions e crie uma nova sessão local | A nova sessão usa a política; uma sessão antiga não muda automaticamente |
| Aplicação de mudança | Altere uma regra e digite /restart-session | A sessão reinicia, mantém o histórico e recarrega a política |
| Pasta somente leitura | Adicione uma pasta descartável a Additional read-only, leia um arquivo fictício e tente criar outro | A leitura deve funcionar; a alteração deve ser bloqueada |
| Pasta negada | Adicione outra pasta descartável a Denied e tente listar ou ler um arquivo fictício | O acesso deve ser bloqueado, mesmo se um caminho-pai amplo estiver permitido |
| Internet | Desative Outbound internet e faça uma verificação de conexão sem efeitos | A conexão externa deve falhar; reative e compare |
| Rede local | Desative Local network e conecte-se a um serviço local descartável | O acesso deve seguir os recursos da plataforma; considere a limitação de processos gerados no Linux |
| Credenciais Git | Desative Git credentials e faça uma verificação autenticada que não altere um repositório de teste | Operações Git HTTPS autenticadas podem ficar indisponíveis |
| Credenciais do GitHub CLI | Desative GitHub CLI credentials e execute uma checagem sem alteração, como gh auth status | O GitHub CLI não deve receber a capacidade de autenticação anterior; o erro exato pode variar |
| Fail-closed | Se aparecer unsupported-platform ou unsupported-policy, confirme que o arquivo fictício de destino não foi criado | O comando não deve continuar sem sandbox nem produzir o efeito pretendido |
Apague as pastas ao terminar e restaure somente as permissões mínimas exigidas pelo projeto. Não teste uma regra de negação tentando acessar um diretório realmente sensível.
Qual política inicial usar em cada cenário
Desenvolvimento diário, repositório desconhecido e análise offline não devem usar a mesma política. Preserve o necessário no trabalho normal, comece mais restrito com código desconhecido e desligue primeiro rede e credenciais no modo offline.
Desenvolvimento diário
Ative o sandbox, mantenha as capacidades padrão de rede e credenciais, adicione apenas as pastas externas necessárias e negue explicitamente diretórios sensíveis próximos. É adequado para instalar dependências, executar serviços locais, enviar branches e abrir pull requests.
Revisão de repositório desconhecido
Dê leitura e gravação somente ao workspace, disponibilize referências extras como somente leitura, desative por padrão as credenciais de Git e GitHub CLI e mantenha a internet desligada até entender a origem das dependências. Quando precisar de acesso temporário, abra uma capacidade específica em vez de usar imediatamente /sandbox off.
Análise local offline
Desative internet e credenciais desnecessárias, mantendo apenas o acesso essencial a arquivos. Se o isolamento da rede local também for importante, verifique separadamente os processos gerados no Linux; não presuma que um único controle da interface governa todos os processos de forma idêntica.
Esses não são presets nomeados pelo GitHub. São pontos de partida montados com as dimensões de permissão disponíveis. Ajuste a política final ao repositório, sistema operacional, regras corporativas e tarefa real.
Erros que tornam a política ineficaz ou ampla demais
Os erros mais comuns são tratar “configuração salva” como “política aplicada” e desligar todo o sandbox após a primeira negação. Os sete casos abaixo invalidam o teste ou concedem acesso maior que o necessário.
- Tratar um working tree como fronteira de segurança. Ele separa branches e arquivos concorrentes, mas não impede comandos de acessar outros locais da máquina.
- Alterar a política e continuar testando uma sessão antiga. As mudanças não são retroativas; crie outra sessão ou use
/restart-session. - Supor que app e CLI compartilham um sandbox. Eles são configurados separadamente.
- Tratar um salvamento bem-sucedido como prova de suporte do host. A verificação ocorre ao iniciar o primeiro shell no sandbox.
- Ignorar o significado de
/sandbox off. Os comandos passam a ter o mesmo alcance de acesso da conta do usuário. - Supor comportamento de rede idêntico em todas as plataformas. O Linux tem uma limitação documentada para a rede local de processos gerados.
- Usar um bypass amplo sempre que o acesso é negado. Em geral é mais seguro confirmar a necessidade, fazer o menor ajuste e reiniciar.
O que fazer agora
Primeiro confirme que você usa uma sessão local de repositório ou working tree e ative Sandbox new sessions. No desenvolvimento diário, parta da política padrão e mantenha somente pastas, rede e credenciais necessárias; para código desconhecido ou análise offline, comece com o perfil mais restrito e abra uma capacidade por vez.
Depois de mudar a política do projeto, inicie outra sessão ou execute /restart-session, então verifique leitura, negação, rede e credenciais com dados descartáveis. Se aparecer unsupported-platform, unsupported-policy ou Sandbox unavailable, resolva a incompatibilidade em vez de usar /sandbox off e confundir uma execução sem isolamento com uma verificação bem-sucedida.
Referências oficiais
Use estas páginas do GitHub antes e depois da configuração para confirmar a interface, o escopo e o comportamento de falha atuais.
